diff --git a/source/reference/command/count-field.yaml b/source/reference/command/count-field.yaml new file mode 100644 index 00000000000..cfe02960234 --- /dev/null +++ b/source/reference/command/count-field.yaml @@ -0,0 +1,49 @@ +object: + name: count + type: dbcommand +field: + optional: false + type: field +name: count +type: string +position: 1 +description: | + The name of the collection to count. +--- +object: + name: count + type: dbcommand +field: + optional: true + type: field +name: query +type: document +position: 2 +description: | + The selection query to determine which documents in the collection to + count. +--- +object: + name: count + type: dbcommand +field: + optional: true + type: field +name: limit +type: integer +position: 3 +description: | + The maximum number of matching documents to return. +--- +object: + name: count + type: dbcommand +field: + optional: true + type: field +name: skip +type: integer +position: 4 +description: | + The number of matching documents to skip before returning results. +... diff --git a/source/reference/command/count.txt b/source/reference/command/count.txt index 6b1cd1632a7..3fa226fd035 100644 --- a/source/reference/command/count.txt +++ b/source/reference/command/count.txt @@ -4,88 +4,86 @@ count .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: count - The :dbcommand:`count` command counts the number of documents in a - collection. The command returns a document that contains the count - as well as the command status. The :dbcommand:`count` command takes - the following prototype form: - + Counts the number of documents in a collection and returns a document + that contains the number as well as the command status. + :dbcommand:`count` has the following form: + .. code-block:: javascript - + { count: , query: , limit: , skip: } - - The command fields are as follows: - - :field String count: - - The name of the collection to count. - - :field document query: - - Optional. Specifies the selection query to determine which - documents in the collection to count. - - :field integer limit: - - Optional. Specifies the limit for the documents matching the - selection ``query``. - - :field integer skip: - Optional. Specifies the number of matching documents to skip. - - Consider the following examples of the :dbcommand:`count` command: - - - Count the number of all documents in the ``orders`` collection: - - .. code-block:: javascript - - db.runCommand( { count: 'orders' } ) - - In the result, the ``n``, which represents the count, is ``26`` - and the command status ``ok`` is ``1``: - - .. code-block:: javascript - - { "n" : 26, "ok" : 1 } - - - Count the number of the documents in the ``orders`` collection - with the field ``ord_dt`` greater than ``new Date('01/01/2012')``: - - .. code-block:: javascript - - db.runCommand( { count:'orders', - query: { ord_dt: { $gt: new Date('01/01/2012') } } - } ) - - In the result, the ``n``, which represents the count, is ``13`` - and the command status ``ok`` is ``1``: - - .. code-block:: javascript - - { "n" : 13, "ok" : 1 } - - - Count the number of the documents in the ``orders`` collection - with the field ``ord_dt`` greater than ``new Date('01/01/2012')`` - skipping the first ``10`` matching records: - - .. code-block:: javascript - - db.runCommand( { count:'orders', - query: { ord_dt: { $gt: new Date('01/01/2012') } }, - skip: 10 } ) - - In the result, the ``n``, which represents the count, is ``3`` and - the command status ``ok`` is ``1``: - - .. code-block:: javascript - - { "n" : 3, "ok" : 1 } - - .. note:: - - MongoDB also provides the :method:`cursor.count()` - method and the shell wrapper :method:`db.collection.count()` - method. - - .. read-lock + + :dbcommand:`count` has the following fields: + + .. include:: /reference/command/count-field.rst + +.. note:: + + MongoDB also provides the :method:`~cursor.count()` method and the + shell wrapper :method:`db.collection.count()` method. + +Examples +-------- + +The following sections provide examples of the :dbcommand:`count` command. + +Count all Documents +~~~~~~~~~~~~~~~~~~~ + +The following operation counts the number of all documents in the +``orders`` collection: + +.. code-block:: javascript + + db.runCommand( { count: 'orders' } ) + +In the result, the ``n``, which represents the count, is ``26``, +and the command status ``ok`` is ``1``: + +.. code-block:: javascript + + { "n" : 26, "ok" : 1 } + +Count Documents with Specified Field Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following operation counts the number of the documents in the +``orders`` collection with the field ``ord_dt`` greater than ``new +Date('01/01/2012')``: + +.. code-block:: javascript + + db.runCommand( { count:'orders', + query: { ord_dt: { $gt: new Date('01/01/2012') } } + } ) + +In the result, the ``n``, which represents the count, is ``13`` +and the command status ``ok`` is ``1``: + +.. code-block:: javascript + + { "n" : 13, "ok" : 1 } + +Skip Matching Documents +~~~~~~~~~~~~~~~~~~~~~~~ + +The following operation counts the number of the documents in the +``orders`` collection with the field ``ord_dt`` greater than ``new +Date('01/01/2012')`` and skip the first ``10`` matching documents: + +.. code-block:: javascript + + db.runCommand( { count:'orders', + query: { ord_dt: { $gt: new Date('01/01/2012') } }, + skip: 10 } ) + +In the result, the ``n``, which represents the count, is ``3`` and +the command status ``ok`` is ``1``: + +.. code-block:: javascript + + { "n" : 3, "ok" : 1 } diff --git a/source/reference/command/create-field.yaml b/source/reference/command/create-field.yaml new file mode 100644 index 00000000000..a7caf2488e6 --- /dev/null +++ b/source/reference/command/create-field.yaml @@ -0,0 +1,72 @@ +object: + name: create + type: dbcommand +field: + optional: false + type: field +name: create +type: string +position: 1 +description: | + The name of the new collection. +--- +object: + name: create + type: dbcommand +field: + optional: true + type: field +name: capped +type: Boolean +position: 2 +description: | + Creates a :term:`capped collection`. To create a capped collection, + specify ``true``. If you create a capped collection, you must also set + a maximum size in the ``size`` field. +--- +object: + name: create + type: dbcommand +field: + optional: true + type: field +name: autoIndexID +type: Boolean +position: 3 +description: | + Disables the automatic creation of an index on the ``_id`` field. To + disable the automatic creation, specify ``false``. Before 2.2, the + default value for ``autoIndexId`` was ``false``. +--- +object: + name: create + type: dbcommand +field: + optional: true + type: field +name: size +type: integer +position: 4 +description: | + The maximum size for the capped collection. Once a capped collection + reaches its maximum size, MongoDB drops old documents from the + collection to make way for new documents. The ``size`` field is + required for capped collections. +--- +object: + name: create + type: dbcommand +field: + optional: true + type: field +name: max +type: integer +position: 5 +description: | + The maximum number of documents to keep in the capped collection. The + ``size`` limit takes precedence over this limit. If a capped + collection reaches its maximum size before it reaches the maximum + number of documents, MongoDB removes old documents. If you use this + limit, ensure that the ``size`` limit is sufficient to contain the + documents limit. +... diff --git a/source/reference/command/create.txt b/source/reference/command/create.txt index e6433d52877..18280322d8e 100644 --- a/source/reference/command/create.txt +++ b/source/reference/command/create.txt @@ -4,53 +4,46 @@ create .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: create - The ``create`` command explicitly creates a collection. The command - uses the following syntax: + Explicitly creates a collection. :dbcommand:`create` has the + following form: .. code-block:: javascript - { create: } - - To create a :term:`capped collection` limited to 40 KB, issue command in - the following form: + { create: , + capped: , + autoIndexId: , + size: , + max: + } - .. code-block:: javascript + :dbcommand:`create` has the following fields: - { create: "collection", capped: true, size: 40 * 1024 } + .. include:: /reference/command/create-field.rst - The options for creating capped collections are: + For more information on the ``autoIndexId`` field in versions before + 2.2, see :ref:`2.2-id-indexes-capped-collections`. - :option capped: Specify ``true`` to create a :term:`capped collection`. + The :method:`db.createCollection()` method wraps the + :dbcommand:`create` command. - :option autoIndexId: Specify ``false`` to disable the automatic - index created on the ``_id`` field. Before - 2.2, the default value for ``autoIndexId`` was - ``false``. See :ref:`2.2-id-indexes-capped-collections` - for more information. +.. note:: - :option size: The maximum size for the capped collection. Once a - capped collection reaches its max size, MongoDB will - drop old documents from the database to make way for - the new documents. You must specify a ``size`` - argument for all capped collections. + The :dbcommand:`create` command obtains a write lock on the affected database and + will block other operations until it has completed. The write + lock for this operation is typically short lived. However, + allocations for large capped collections may take longer. - :option max: The maximum number of documents to preserve in the - capped collection. This limit is subject to the - overall size of the capped collection. If a capped - collection reaches its maximum size before it contains - the maximum number of documents, the database will - remove old documents. Thus, if you use this option, - ensure that the total size for the capped collection - is sufficient to contain the max. +Example +------- - The :method:`db.createCollection()` provides a wrapper function that - provides access to this functionality. +To create a :term:`capped collection` limited to 40 KB, issue the +command in the following form: - .. note:: +.. code-block:: javascript - This command obtains a write lock on the affected database and - will block other operations until it has completed. The write - lock for this operation is typically short lived; however, - allocations for large capped collections may take longer. + db.runCommand( { create: "collection", capped: true, size: 40 * 1024 } ) diff --git a/source/reference/command/shardCollection-field.yaml b/source/reference/command/shardCollection-field.yaml new file mode 100644 index 00000000000..9f78db3eb9f --- /dev/null +++ b/source/reference/command/shardCollection-field.yaml @@ -0,0 +1,60 @@ +object: + name: shardCollection + type: dbcommand +field: + optional: false + type: field +name: shardCollection +type: string +position: 1 +description: | + The :term:`namespace` of the collection to shard in the form + ``.``. +--- +object: + name: shardCollection + type: dbcommand +field: + optional: false + type: field +name: key +type: document +position: 2 +description: | + The :ref:`index specification document ` + to use as the shard key. The index must exist prior to the + :dbcommand:`shardCollection` command, unless the collection is empty. + If the collection is empty, in which case MongoDB creates the index + prior to sharding the collection. New in version 2.4: The key may be + in the form ``{ field : "hashed" }``, which will use the specified + field as a hashed shard key. +--- +object: + name: shardCollection + type: dbcommand +field: + optional: false + type: field +name: unique +type: Boolean +position: 3 +description: | + When ``true``, the ``unique`` option ensures that the underlying index + enforces a unique constraint. Hashed shard keys do not support unique + constraints. +--- +object: + name: shardCollection + type: dbcommand +field: + optional: false + type: field +name: numInitialChunks +type: integer +position: 4 +description: | + New in version 2.4: The number of chunks to create upon sharding the + collection. The collection will then be pre-split and balanced across + the specified number of chunks. The ``numInitialChunks`` option has a + maximum of ``8192`` chunks. +... diff --git a/source/reference/command/shardCollection.txt b/source/reference/command/shardCollection.txt index 121388bd9d3..d05dc8b9b99 100644 --- a/source/reference/command/shardCollection.txt +++ b/source/reference/command/shardCollection.txt @@ -4,64 +4,54 @@ shardCollection .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: shardCollection - The :dbcommand:`shardCollection` command marks a collection for sharding and - will allow data to begin distributing among shards. You must run + Marks a collection for sharding and allows MongoDB to begin + distributing data among shards. You must run :dbcommand:`enableSharding` on a database before running the - :dbcommand:`shardCollection` command. + :dbcommand:`shardCollection` command. :dbcommand:`shardCollection` + has the following form: .. code-block:: javascript { shardCollection: ".", key: } - This enables sharding for the collection specified by - ```` in the database named ````, using the key - ```` to distribute documents among the - shard. ```` is a document and takes the same form as an - :ref:`index specification document `. - - :param string shardCollection: + :dbcommand:`shardCollection` has the following fields: - Specify the namespace of a collection to shard in the form - ``.``. + .. include:: /reference/command/shardCollection-field.rst - :param document key: +Shard Keys +~~~~~~~~~~ - Specify the index specification to use as the shard key. The - index must exist prior to the :dbcommand:`shardCollection` command - unless the collection is empty. If the collection is empty, then - MongoDB will create the index prior to sharding the collection. +Choosing the best shard key to effectively distribute load among your +shards requires some planning. Review :ref:`sharding-shard-key` +regarding choosing a shard key. - .. versionadded:: 2.4 - The key may be in the form ``{ field : "hashed" }`` which will - use the specified field as a :ref:`hashed shard key - ` . +Hashed Shard Keys +~~~~~~~~~~~~~~~~~ - :param boolean unique: +.. versionadded:: 2.4 - When true, the ``unique`` option ensures that the underlying - index enforces a unique constraint. :term:`Hashed shard keys - ` do not support unique constraints. +:ref:`Hashed shard keys ` use a +hashed index of a single field as the shard key. - :param integer numInitialChunks: - .. versionadded:: 2.4 +.. include:: /includes/warning-cannot-unshard-collection.rst - Specify the number of chunks to create upon sharding the - collection. The collection will then be pre-split and balanced - across the specified number of chunks. +.. seealso:: - You can specify no more than ``8192`` chunks using - ``numInitialChunks``. + :doc:`/sharding`, :doc:`/core/sharded-clusters`, and + :doc:`/tutorial/deploy-shard-cluster`. - Choosing the right shard key to effectively distribute load among - your shards requires some planning. Also review - :ref:`sharding-shard-key` regarding choosing a shard key. +Example +------- - .. include:: /includes/warning-cannot-unshard-collection.rst +The following operation enables sharding for the ``people`` collection in the ``records`` database and uses the +``zipcode`` field as the :ref:`shard key `: - .. seealso:: +.. code-block:: javascript - :doc:`/sharding`, :doc:`/core/sharded-clusters`, and - :doc:`/tutorial/deploy-shard-cluster`. + db.runCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )