2d.txt

==============
``2d`` Indexes
==============

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Use a ``2d`` index for data stored as points on a two-dimensional plane. The
``2d`` index is intended for legacy coordinate pairs used in MongoDB 2.2
and earlier.

Use a ``2d`` index if:

- your database has legacy location data from MongoDB 2.2 or earlier, *and*

- you do not intend to store any location data as :term:`GeoJSON` objects.

See the :doc:`/reference/operator/query-geospatial` for the query
operators that support geospatial queries.

Considerations
--------------

.. |first-geo-index| replace:: ``2d`` index
.. |second-geo-index| replace:: :doc:`2dsphere index</core/2dsphere>`
.. include:: /includes/fact-limitation-one-geo-index-per-collection.rst

Do not use a ``2d`` index if your location data includes GeoJSON objects. To
index on both legacy coordinate pairs *and* GeoJSON objects, use a
:doc:`2dsphere </core/2dsphere>` index.

You cannot use a ``2d`` index as a shard key when sharding a
collection. However, you can create and maintain a geospatial index on
a sharded collection by using a different field as the shard key.

Behavior
--------

The ``2d`` index supports calculations on a flat, Euclidean plane. The
``2d`` index also supports *distance-only* calculations on a sphere,
but for *geometric* calculations (e.g. :query:`$geoWithin`) on a
sphere, store data as GeoJSON objects and use the ``2dsphere`` index
type.

A ``2d`` index can reference two fields. The first must be the location
field. A ``2d`` compound index constructs queries that select first on
the location field, and then filters those results by the additional
criteria. A compound ``2d`` index can cover queries.

.. _geospatial-indexes-store-grid-coordinates:

Points on a 2D Plane
--------------------

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

To store location data as legacy coordinate pairs, use an array or an
embedded document. When possible, use the array format:

.. code-block:: javascript

   loc : [ <longitude> , <latitude> ]

Consider the embedded document form:

.. code-block:: javascript

   loc : { lng : <longitude> , lat : <latitude> }

Arrays are preferred as certain languages do not guarantee associative
map ordering.

For all points, if you use longitude and latitude,
store coordinates in **longitude, latitude** order.

``sparse`` Property
-------------------

``2d`` indexes are :doc:`sparse </core/index-sparse>` by default and
ignores the :doc:`sparse: true </core/index-sparse>` option. If a
document lacks a ``2d`` index field (or the field is ``null`` or an
empty array), MongoDB does not add an entry for the document to the
``2d`` index. For inserts, MongoDB inserts the document but does not
add to the ``2d`` index.

For a compound index that includes a ``2d`` index key along with keys
of other types, only the ``2d`` index field determines whether the
index references a document.

.. class:: hidden

   .. toctree::
      :titlesonly: 

      /tutorial/build-a-2d-index
      /tutorial/query-a-2d-index
      /core/geospatial-indexes
      /tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes