From 9e003f066fb36ca215638aa02addad79118c7830 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 13 Mar 2014 22:59:58 -0400 Subject: [PATCH] DOCS-2720 createIndexes command --- .../includes/ref-spec-indexes-commands.yaml | 1 + .../ref-toc-command-administration.yaml | 4 + .../command/createIndexes-field.yaml | 25 ++++ .../command/createIndexes-indexes-field.yaml | 79 ++++++++++ source/reference/command/createIndexes.txt | 138 ++++++++++++++++++ source/reference/limits.txt | 2 +- source/reference/privilege-actions.txt | 3 +- 7 files changed, 250 insertions(+), 2 deletions(-) create mode 100644 source/reference/command/createIndexes-field.yaml create mode 100644 source/reference/command/createIndexes-indexes-field.yaml create mode 100644 source/reference/command/createIndexes.txt diff --git a/source/includes/ref-spec-indexes-commands.yaml b/source/includes/ref-spec-indexes-commands.yaml index 9d1447daed3..1b99df26e5b 100644 --- a/source/includes/ref-spec-indexes-commands.yaml +++ b/source/includes/ref-spec-indexes-commands.yaml @@ -4,6 +4,7 @@ sources: - ref-toc-command-geospatial.yaml - ref-toc-command-sharding.yaml files: + - /reference/command/createIndexes - /reference/command/dropIndexes - /reference/command/compact - /reference/command/reIndex diff --git a/source/includes/ref-toc-command-administration.yaml b/source/includes/ref-toc-command-administration.yaml index aa84a00aa38..c07eb3d23d8 100644 --- a/source/includes/ref-toc-command-administration.yaml +++ b/source/includes/ref-toc-command-administration.yaml @@ -42,6 +42,10 @@ name: ":dbcommand:`filemd5`" file: /reference/command/filemd5 description: "Returns the :term:`md5` hash for files stored using :term:`GridFS`." --- +name: ":dbcommand:`createIndexes`" +file: /reference/command/createIndexes +description: "Builds one or more indexes for a collection." +--- name: ":dbcommand:`dropIndexes`" file: /reference/command/dropIndexes description: "Removes indexes from a collection." diff --git a/source/reference/command/createIndexes-field.yaml b/source/reference/command/createIndexes-field.yaml new file mode 100644 index 00000000000..fd5945558c5 --- /dev/null +++ b/source/reference/command/createIndexes-field.yaml @@ -0,0 +1,25 @@ +object: + name: createIndexes + type: dbcommand +field: + optional: false + type: field +name: createIndexes +type: string +position: 1 +description: | + The collection for which to create indexes. +--- +object: + name: createIndexes + type: dbcommand +field: + optional: false + type: field +name: indexes +type: array +position: 2 +description: | + Specifies the indexes to create. Each document in the array specifies a + separate index. +... diff --git a/source/reference/command/createIndexes-indexes-field.yaml b/source/reference/command/createIndexes-indexes-field.yaml new file mode 100644 index 00000000000..77b8cd50301 --- /dev/null +++ b/source/reference/command/createIndexes-indexes-field.yaml @@ -0,0 +1,79 @@ +object: + name: createIndexes + type: dbcommand +field: + optional: false + type: field +name: key +type: document +position: 1 +description: | + Specifies the index's fields. For each field, specify a key-value pair + in which the key is the name of the field to index and the value is + either the index direction or :doc:`index type `. If + specifying direction, specify ``1`` for ascending or ``-1`` for + descending. +--- +object: + name: createIndexes + type: dbcommand +field: + optional: false + type: field +name: name +type: string +position: 2 +description: | + A name that uniquely identifies the index. +--- +object: + name: createIndexes + type: dbcommand +field: + optional: true + type: field +name: ns +type: string +position: 3 +description: | + The :term:`namespace` (i.e. ``.``) of the + collection for which to create the index. If you omit ``ns``, MongoDB + generates the namespace. +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: background +position: 4 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: unique +position: 5 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: dropDups +position: 6 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: sparse +position: 7 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: expireAfterSeconds +position: 8 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: v +position: 9 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: weights +position: 10 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: default_language +position: 11 +--- +file: /reference/method/db.collection.ensureIndex-options-param.yaml +name: language_override +position: 12 +... + \ No newline at end of file diff --git a/source/reference/command/createIndexes.txt b/source/reference/command/createIndexes.txt new file mode 100644 index 00000000000..b9d252bce9b --- /dev/null +++ b/source/reference/command/createIndexes.txt @@ -0,0 +1,138 @@ +============= +createIndexes +============= + +.. default-domain:: mongodb + +.. dbcommand:: createIndexes + + Builds multiple indexes on a collection. MongoDB builds the indexes + serially. + + The :dbcommand:`createIndexes` command takes the following form: + + .. code-block:: javascript + + db.runCommand( + { + createIndexes: , + indexes: [ + { + key: { + , + , + ... + }, + name: , + , + , + ... + }, + { ... }, + { ... } + ] + } + ) + + .. warning:: An index name, including the :term:`namespace`, cannot be + longer than the :ref:`Index Name Length ` limit. + + The :dbcommand:`createIndexes` command takes the following fields: + + .. include:: /reference/command/createIndexes-field.rst + + Each document in the ``indexes`` array can take the following fields: + + .. include:: /reference/command/createIndexes-indexes-field.rst + +Behavior +-------- + +Non-background indexing operations block all other operations on a +database. + +If you create an index with one set of options and then issue +:dbcommand:`createIndexes` with the same index fields but different options, +MongoDB will not change the options nor rebuild the index. To +change index options, you must first :method:`drop +` the existing index before running +:dbcommand:`createIndexes` with the new options. + +MongoDB will not create an index on a collection if the value of the index +field in an existing document exceeds the :limit:`index key size limit +`. + +Example +------- + +The following command builds two indexes on the ``inventory`` collection of +the ``products`` database: + +.. code-block:: javascript + + db.getSiblingDB("products").runCommand( + { + createIndexes: "inventory", + indexes: [ + { + key: { + item: 1, + manufacturer: 1, + model: 1 + }, + name: "item_manufacturer_model", + unique: true + }, + { + key: { + item: 1, + supplier: 1, + model: 1 + }, + name: "item_supplier_model", + unique: true + } + ] + } + ) + +When the indexes successfully finish building, MongoDB returns a results +document that includes a status of ``"ok" : 1``. + +Output +------ + +The :dbcommand:`createIndexes` command returns a document that indicates +the success of the operation. The document contains some but not all of +the following fields, depending on outcome: + +.. data:: createdCollectionAutomatically + + If ``true``, then the collection didn't exist and was created in the + process of creating the index. + +.. data:: numIndexesBefore + + The number of indexes at the start of the command. + +.. data:: numIndexesAfter + + The number of indexes at the end of the command. + +.. data:: ok + + A value of ``1`` indicates the indexes are in place. A value of + ``0`` indicates an error. + +.. data:: note + + This ``note`` is returned if an existing index or indexes already + exist. This indicates that the index was not created or changed. + +.. data:: errmsg + + Returns information about any errors. + +.. data:: code + + The error code representing the type of error. diff --git a/source/reference/limits.txt b/source/reference/limits.txt index 8dac849d9aa..c7766dbbd80 100644 --- a/source/reference/limits.txt +++ b/source/reference/limits.txt @@ -79,7 +79,7 @@ Indexes .. limit:: Index Name Length The names of indexes, including their namespace (i.e database and - collection name) cannot be longer than 125 characters. The default + collection name), cannot be longer than 125 characters. The default index name is the concatenation of the field names and index directions. diff --git a/source/reference/privilege-actions.txt b/source/reference/privilege-actions.txt index eadc380c3b1..10d397e8d43 100644 --- a/source/reference/privilege-actions.txt +++ b/source/reference/privilege-actions.txt @@ -71,7 +71,8 @@ Database Management Actions .. authaction:: createIndex - Provides access to the :method:`db.collection.createIndex()` method. + Provides access to the :method:`db.collection.createIndex()` method + and the :dbcommand:`createIndexes` command. Apply this action to database or collection resources. .. authaction:: createRole