DOCS-2933 ensureIndex options

Author: kay-kim

source/core/2d.txt

@@ -71,3 +71,17 @@ 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.

source/core/2dsphere.txt

@@ -39,6 +39,8 @@ To create a ``2dsphere`` index as a version 1, include the option ``{
 Additional GeoJSON Objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. versionchanged:: 2.6
+
 Version 2 adds support for additional GeoJSON object:
 :ref:`geojson-multipoint`, :ref:`geojson-multilinestring`,
 :ref:`geojson-multipolygon`, and
@@ -47,15 +49,22 @@ Version 2 adds support for additional GeoJSON object:
 ``sparse`` Property
 ~~~~~~~~~~~~~~~~~~~
 
+.. versionchanged:: 2.6
+
 Version 2 ``2dsphere`` indexes are :doc:`sparse </core/index-sparse>`
 by default and ignores the :doc:`sparse: true </core/index-sparse>`
 option. If a document lacks a ``2dsphere`` index field (or the field is
-a ``null`` or an empty array), MongoDB does not add an entry for the
+``null`` or an empty array), MongoDB does not add an entry for the
 document to the ``2dsphere`` index. For inserts, MongoDB inserts the
 document but does not add to the ``2dsphere`` index.
 
-Version 1 ``2dsphere`` indexes are not sparse by default and will
-reject documents with ``null`` location fields.
+For a compound index that includes a ``2dsphere`` index key along with
+keys of other types, only the ``2dsphere`` index field determines
+whether the index references a document.
+
+Earlier versions of MongoDB only support Version 1 ``2dsphere``
+indexes. Version 1 ``2dsphere`` indexes are *not* sparse by default and
+will reject documents with ``null`` location fields.
 
 Considerations
 --------------

source/core/geohaystack.txt

@@ -1,27 +1,49 @@
 .. _index-geohaystack-index:
 
-================
-Haystack Indexes
-================
+=======================
+``geoHaystack`` Indexes
+=======================
 
 .. default-domain:: mongodb
 
-A haystack index is a special index that is optimized to return results
-over small areas. Haystack indexes improve performance on queries that
-use flat geometry.
+A ``geoHaystack`` index is a special index that is optimized to return
+results over small areas. ``geoHaystack`` indexes improve performance
+on queries that use flat geometry.
 
 For queries that use spherical geometry, a **2dsphere index is a better
 option** than a haystack index. :doc:`2dsphere indexes
-</core/2dsphere>` allow field reordering; haystack indexes require the
-first field to be the location field. Also, haystack indexes are only
-usable via commands and so always return all results at once.
+</core/2dsphere>` allow field reordering; ``geoHaystack`` indexes
+require the first field to be the location field. Also, ``geoHaystack``
+indexes are only usable via commands and so always return all results
+at once.
 
-Haystack indexes create "buckets" of documents from the same geographic
-area in order to improve performance for queries limited to that area.
-Each bucket in a haystack index contains all the documents within a
-specified proximity to a given longitude and latitude.
+Behavior
+--------
 
-To create a geohaystacks index, see
+``geoHaystack`` indexes create "buckets" of documents from the same
+geographic area in order to improve performance for queries limited to
+that area. Each bucket in a ``geoHaystack`` index contains all the
+documents within a specified proximity to a given longitude and
+latitude.
+
+``sparse`` Property
+-------------------
+
+``geoHaystack`` indexes are :doc:`sparse </core/index-sparse>` by
+default and ignores the :doc:`sparse: true </core/index-sparse>`
+option. If a document lacks a ``geoHaystack`` index field (or the field
+is ``null`` or an empty array), MongoDB does not add an entry for the
+document to the ``geoHaystack`` index. For inserts, MongoDB inserts the
+document but does not add to the ``geoHaystack`` index.
+
+For a compound index that includes a ``geoHaystack`` index key along
+with a key of a different type, only the ``geoHaystack`` index field
+determines whether the index references a document.
+
+Create ``geoHaystack`` Index
+----------------------------
+
+To create a ``geoHaystack`` index, see
 :doc:`/tutorial/build-a-geohaystack-index`. For information and example
 on querying a haystack index, see
 :doc:`/tutorial/query-a-geohaystack-index`.

source/core/index-text.txt

@@ -56,6 +56,21 @@ for non-diacritics; i.e. case insensitive for ``[A-z]``.
 To specify a language for the ``text`` index, see
 :doc:`/tutorial/specify-language-for-text-index`
 
+``sparse`` Property
+-------------------
+
+``text`` indexes are :doc:`sparse </core/index-sparse>` by default and
+ignores the :doc:`sparse: true </core/index-sparse>` option. If a
+document lacks a ``text`` index field (or the field is ``null`` or an
+empty array), MongoDB does not add an entry for the document to the
+``text`` index. For inserts, MongoDB inserts the document but does not
+add to the ``text`` index.
+
+For a compound index that includes a ``text`` index key along with keys
+of other types, only the ``text`` index field determine whether the
+index references a document. The other keys do not determine whether
+the index references the documents or not.
+
 Restrictions
 ------------
 

source/reference/command/createIndexes-indexes-field.yaml

@@ -64,15 +64,39 @@ file: /reference/method/db.collection.ensureIndex-options-param.yaml
 name: v
 position: 9
 ---
-file: /reference/method/db.collection.ensureIndex-options-param.yaml
+file: /reference/method/db.collection.ensureIndex-options-text.yaml
 name: weights
 position: 10
 ---
-file: /reference/method/db.collection.ensureIndex-options-param.yaml
+file: /reference/method/db.collection.ensureIndex-options-text.yaml
 name: default_language
 position: 11
 ---
-file: /reference/method/db.collection.ensureIndex-options-param.yaml
+file: /reference/method/db.collection.ensureIndex-options-text.yaml
 name: language_override
 position: 12
+---
+file: /reference/method/db.collection.ensureIndex-options-text.yaml
+name: textIndexVersion
+position: 13
+---
+file: /reference/method/db.collection.ensureIndex-options-2dsphere.yaml
+name: 2dsphereIndexVersion
+position: 14
+---
+file: /reference/method/db.collection.ensureIndex-options-2d.yaml
+name: bits
+position: 15
+---
+file: /reference/method/db.collection.ensureIndex-options-2d.yaml
+name: min
+position: 16
+---
+file: /reference/method/db.collection.ensureIndex-options-2d.yaml
+name: max
+position: 17
+---
+file: /reference/method/db.collection.ensureIndex-options-geohaystack.yaml
+name: bucketSize
+position: 18
 ...

source/reference/method/db.collection.ensureIndex-options-2d.yaml

@@ -0,0 +1,42 @@
+object:
+  name: db.collection.ensureIndex()
+  type: method
+field:
+  optional: true
+  type: param
+name: bits
+type: integer
+position: 1
+description: |
+  For :doc:`2d </core/2d>` indexes, the number of precision of the
+  stored :term:`geohash` value of the location data.
+
+  The ``bits`` value ranges from 1 to 32 inclusive. The default value
+  is ``26``.
+---
+object:
+  name: db.collection.ensureIndex()
+  type: method
+field:
+  optional: true
+  type: param
+name: min
+type: number
+position: 2
+description: |
+  For :doc:`2d </core/2d>` indexes, the lower inclusive boundary for
+  the longitude and latitude values. The default value is ``-180.0``.
+---
+object:
+  name: db.collection.ensureIndex()
+  type: method
+field:
+  optional: true
+  type: param
+name: max
+type: number
+position: 3
+description: |
+  For :doc:`2d </core/2d>` indexes, the upper inclusive boundary for
+  the longitude and latitude values. The default value is ``180.0``.
+...

source/reference/method/db.collection.ensureIndex-options-2dsphere.yaml

@@ -0,0 +1,19 @@
+object:
+  name: db.collection.ensureIndex()
+  type: method
+field:
+  optional: true
+  type: param
+name: 2dsphereIndexVersion
+type: integer
+position: 1
+description: |
+  For :doc:`2dsphere </core/2dsphere>` indexes, the ``2dsphere``
+  index version number. Version can be either ``1`` or ``2``. 
+
+  In MongoDB 2.6, the default version is ``2``. MongoDB 2.4 can only
+  support version ``1``.
+
+  .. versionadded:: 2.6
+
+...

source/reference/method/db.collection.ensureIndex-options-geohaystack.yaml

@@ -0,0 +1,17 @@
+object:
+  name: db.collection.ensureIndex()
+  type: method
+field:
+  optional: false
+  type: param
+name: bucketSize
+type: number
+position: 1
+description: |
+  For :doc:`geoHaystack </core/geohaystack>` indexes, specify the
+  number of units within which to group the location values; i.e. group
+  in the same bucket those location values that are within the
+  specified number of units to each other.
+
+  The value must be greater than 0.
+...

source/reference/method/db.collection.ensureIndex-options-param.yaml

@@ -25,7 +25,9 @@ description: |
   Creates a unique index so that the collection will not accept
   insertion of documents where the index key or keys match an existing
   value in the index. Specify ``true`` to create a unique index. The
-  default value is ``false``. This option applies only to ascending/descending
+  default value is ``false``.
+
+  The option is *unavailable* for :doc:`hashed </core/index-hashed>`
   indexes.
 ---
 object:
@@ -40,6 +42,10 @@ position: 3
 description: |
   The name of the index. If unspecified, MongoDB generates an index name
   by concatenating the names of the indexed fields and the sort order.
+
+  Whether user specified or MongoDB generated, index names including
+  their full namespace (i.e. ``database.collection``) cannot be longer
+  than the :limit:`Index Name Limit`.
 ---
 object:
   name: db.collection.ensureIndex()
@@ -55,7 +61,10 @@ description: |
   indexes only the first occurrence of a key and **removes** all
   documents from the collection that contain subsequent occurrences of
   that key. Specify ``true`` to create unique index. The default value
-  is ``false``. This option applies only to scalar indexes.
+  is ``false``.
+
+  The option is *unavailable* for :doc:`hashed </core/index-hashed>`
+  indexes.
 
   .. deprecated:: 2.6
 
@@ -75,8 +84,20 @@ position: 5
 description: |
   If ``true``, the index only references documents with the specified
   field. These indexes use less space but behave differently in some
-  situations (particularly sorts). The default value is ``false``. This
-  applies only to ascending/descending indexes.
+  situations (particularly sorts). The default value is ``false``.
+  See :doc:`/core/index-sparse` for more information.
+
+  .. versionchanged:: 2.6
+
+     :doc:`2dsphere </core/2dsphere>` indexes are sparse by default and
+     ignore this option. For a compound index that includes
+     ``2dsphere`` index key(s) along with keys of other types, only the
+     ``2dsphere`` index fields determine whether the index references a
+     document.
+
+     :doc:`2d </core/2d>`, :doc:`geoHaystack </core/geohaystack>`, and
+     :doc:`text </core/index-text>` indexes behave similarly to the
+     :doc:`2dsphere </core/2dsphere>` indexes.
 ---
 object:
   name: db.collection.ensureIndex()
@@ -108,54 +129,4 @@ description: |
   version 2.0, the this value was 0; versions 2.0 and later use version
   1, which provides a smaller and faster index format. Specify a
   different index version *only* in unusual situations.
----
-object:
-  name: db.collection.ensureIndex()
-  type: method
-field:
-  optional: true
-  type: param
-name: weights
-type: document
-position: 8
-description: |
-  For ``text`` indexes, the significance of the field relative to the
-  other indexed fields. The document contains field and weight pairs.
-  The weight is a number ranging from 1 to 99,999 and denotes the
-  significance of the field relative to the other indexed fields in
-  terms of the score. You can specify weights for some or all the
-  indexed fields. See :doc:`/tutorial/control-results-of-text-search` to
-  adjust the scores. The default value is ``1``. This applies to
-  ``text`` indexes only.
----
-object:
-  name: db.collection.ensureIndex()
-  type: method
-field:
-  optional: true
-  type: param
-name: default_language
-type: string
-position: 9
-description: |
-  For a ``text`` index, the language that determines the list of stop
-  words and the rules for the stemmer and tokenizer. See
-  :ref:`text-search-languages` for the available languages and
-  :doc:`/tutorial/specify-language-for-text-index` for more information
-  and examples. The default value is ``english``. This applies to
-  ``text`` indexes only.
----
-object:
-  name: db.collection.ensureIndex()
-  type: method
-field:
-  optional: true
-  type: param
-name: language_override
-type: string
-position: 10
-description: |
-  For a ``text`` index, specify the name of the field in the document
-  that contains, for that document, the language to override the default
-  language. The default value is ``language``.
 ...