From 74cd31f8c3a1db33dc7d599b0a1aefa99a71f587 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 2 Oct 2012 00:08:15 -0400 Subject: [PATCH] DOCS-555 update the main crud reference docs --- draft/applications/create.txt | 86 ++++++++++++ draft/applications/delete.txt | 24 ++++ draft/applications/read.txt | 45 +++++++ draft/applications/update.txt | 67 ++++++++++ .../reference/method/db.collection.find.txt | 124 ++++++++++++++++-- .../reference/method/db.collection.insert.txt | 120 +++++++++++++++-- .../reference/method/db.collection.remove.txt | 71 ++++++---- .../reference/method/db.collection.save.txt | 87 +++++++++++- .../reference/method/db.collection.update.txt | 80 +++++------ 9 files changed, 616 insertions(+), 88 deletions(-) create mode 100644 draft/applications/create.txt create mode 100644 draft/applications/delete.txt create mode 100644 draft/applications/read.txt create mode 100644 draft/applications/update.txt diff --git a/draft/applications/create.txt b/draft/applications/create.txt new file mode 100644 index 00000000000..adeafc77c08 --- /dev/null +++ b/draft/applications/create.txt @@ -0,0 +1,86 @@ +====== +Create +====== + +.. default-domain:: mongodb + +Create operation adds new :term:`documents ` to a +:term:`collection`. MongoDB provides the :ref:`insert() ` +method to perform create operations. Additionally, the :ref:`update() +with upsert option ` method and the :ref:`save() +` method also provide functionality to create +documents. + +All three methods exhibit the following behavior during the create +operation: + +- If the new document does not specify an :term:`_id` field, these + methods will add the ``_id`` field to the document and assign as + its value a unique :term:`objectid`. + +- If the document specifies a new field, these methods will add + the document with the new field **without** requiring a schema change + to the collection or any change to the existing documents. + +Keep in mind that MongoDB v2.2 has a limit on document size of 16 +megabytes (MB). + + +.. _insert: + +Insert() +-------- + +The :method:`insert() ` method is the primary +method to insert a document or documents into a collection. The +:method:`insert() ` is analogous to the ``SQL +INSERT`` except the :method:`insert() ` method +provides these additional functionalities: + +- If the collection does not exist, then the :method:`insert() + ` method will create the collection. + +- If the new document does not specify an ``_id`` field, then + :method:`insert() ` will add the ``_id`` + field to the document and assign a unique ``objectid`` as its + value. + +- If passed an array of documents, the :method:`insert() + ` method can perform bulk inserts into a + collection. + +.. _update_and_save: + +Update() with Upsert Option and Save() +-------------------------------------- + +Both the :method:`update() ` method and the +:method:`save() ` method will be discussed in +fuller detail in the Update section. But a quick introduction to their +insert capabilities is presented here for completeness. + +Update() with Upsert Option +```````````````````````````` + +The :method:`update() with upsert option ` or +an ``upsert`` will insert a single document into a collection if no +document exists that matches the update query criteria. The inserted +document will contain the fields and values of both the update query +criteria and the update operation. If the ``_id`` is not specified in +either the query criteria and the update operation documents, the +``upsert`` will add the ``_id`` field to the document and assign a +unique ``objectid`` as its value. + +The ``upsert`` removes the need to perform a separate query to +check for the existence of a record before performing either an insert +or an update. + +Save() +`````` + +The :method:`save() ` will insert a document into +a :term:`collection` if the document does not contain the ``_id`` field +or contains an ``_id`` field with a value not in the collection. If the +``_id`` is not specified in the document parameter, :method:`save() +` will add the ``_id`` field to the document +and assign a unique ``objectid`` as its value. diff --git a/draft/applications/delete.txt b/draft/applications/delete.txt new file mode 100644 index 00000000000..8184c05dafb --- /dev/null +++ b/draft/applications/delete.txt @@ -0,0 +1,24 @@ +====== +Delete +====== + +.. default-domain:: mongodb + +Delete operation removes documents from a :term:`collection`. MongoDB +provides the :ref:`remove() ` method to perform delete operations. + +.. _remove: + +Remove() +-------- + +The :method:`remove() ` method is the method to +delete documents from a collection. By default, the :method:`remove() +` deletes all documents that meet the delete +selection criteria. However, using the ``justOne`` option limits the +deletion to just one document. + +Note that calling :method:`remove() ` without +specifying the delete selection criteria removes all documents in the +collection. + diff --git a/draft/applications/read.txt b/draft/applications/read.txt new file mode 100644 index 00000000000..4196aca6dcc --- /dev/null +++ b/draft/applications/read.txt @@ -0,0 +1,45 @@ +==== +Read +==== + +.. default-domain:: mongodb + +Read operation selects documents from a collection. MongoDB +provides the :ref:`find() ` method to perform read operations. +Additionally, the :ref:`Aggregation Framework ` also +provides read operations that involve various aggregation functions, +such as ``SUM``. + +.. _find: + +Find() +------ + +The :method:`find() ` method is the primary +method to select documents from a collection. The find() method returns +a cursor to the selected documents. The :method:`find() +` method can accept a selection criteria on +document fields, including array fields and subdocuments, to limit the +selection. + +The :method:`find() ` method offers the +flexibility to specify the fields to return through the include/exclude +flags of the ``projection`` document. For instance, if selecting 11 out +of 15 fields, with the :method:`find() ` method, you +can choose to specify the 4 to exclude rather than the 11 to include. + +.. TODO -- sort/limit/other options... + +.. _aggregation: + +Aggregation Framework +--------------------- + +The Aggregation Framework provides a rich set of tools for performing +various sequence of operations, not the least of which is the read operation. + +Although the Aggregation Framework is discussed in detail in its own +section, a brief introduction to the aggregation read operation is +provided here for completeness. + +.. seealso:: :doc:`/applications/aggregation` diff --git a/draft/applications/update.txt b/draft/applications/update.txt new file mode 100644 index 00000000000..f7b227f687c --- /dev/null +++ b/draft/applications/update.txt @@ -0,0 +1,67 @@ +====== +Update +====== + +.. default-domain:: mongodb + +Update operation modifies an existing :term:`document ` or +documents in a :term:`collection`. MongoDB provides the :ref:`update() +` method to perform update operations. +Additionally, the :ref:`save() ` method also provides the +functionality to update documents. + +Note that the two methods also provide the option to insert a new +document into a collection. + +.. TODO ? findAndModify? + +.. _update: + +Update +------ + +The :method:`update() ` method is the primary +method to update an existing document or documents in a collection. The +:method:`update() ` method can either replace +the existing document with the new document or update specific fields +in the existing document. + +By default the :method:`update() ` method +updates a single document, but by using the ``multi`` option, the +method can update all documents that match the update selection +criteria. + +Additionally, if no existing document match the update selection +criteria, by using the ``upsert`` option, the method can insert +a new document into the collection. + +Note also that the :method:`update() ` method +can also modify the name of the ``field`` in a document using the +:operator:`$rename` operator. + + .. _save: + +Save +---- + +The :method:`save() ` method updates an existing +document or inserts a document depending on the parameter. The +:method:`save() ` method is like an ``upsert`` +operation that has the update selection criteria on the :term:`_id` +field: + +- If no ``_id`` field exists, the :method:`save() + ` method performs an insert. The insert will + add the ``_id`` field and assign a unique :term:`objectid` as its + value. + +- If ``_id`` field exists but does not match any document in the + collection, the :method:`save() ` method + performs an insert. The insert will add the ``_id`` field and assign + a unique :term:`objectid` as its value. + +- If ``_id`` field exists and matches an existing document in the + collection, the :method:`save() ` method + performs an update that replaces the existing document with the new + document. + diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 7e56177ac6e..a431ebd83ed 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -6,18 +6,118 @@ db.collection.find() .. method:: db.collection.find(query,projection) - :param document query: A :term:`document` that specifies the - :term:`query` using the JSON-like syntax and - :doc:`query operators `. + The :method:`find() ` method selects + documents in a collection and returns a + :term:`cursor` to the selected documents. - :param document projection: Optional. A :term:`document` that - controls the :term:`projection`, or the - contents of the data returned. + The :method:`find() ` method can take the + following parameters: - :returns: A cursor whose iteration visits all of the documents that - match the ``query`` document. + :param document query: - Queries for documents matching ``query``. The argument to - :method:`find() ` takes the form of a :term:`document`. See - the ":doc:`/reference/operators`" for an overview of the available - operators for specifying and narrowing the query. + Optional. A document that specifies + the selection criteria using :doc:`query operators + `. Omit the ``query`` parameter or pass + an empty ``{}`` document to return all documents in the + collection. + + :param document projection: + + Optional. A document that controls the fields to return, or + the :term:`projection`. The ``projection`` document has + the following syntax: + + .. code-block:: javascript + + { field1: boolean, field2: boolean ... } + + The ``boolean`` can take the following include/exclude values: + + - ``1`` or ``true`` to include. The :method:`find() + ` method always includes the + :term:`_id` field even if the field is not explicitly + stated to return in the :term:`projection` parameter. + + - ``0`` or ``false`` to exclude. + + Currently, you cannot mix include and exclude fields in + the projection document. + + :returns: + + A :term:`cursor` to the documents that match + the ``query`` criteria and contain the ``projection`` fields. + + .. examples-begin + + Consider the following examples of the :method:`find() + ` method. + + - To select all documents in a collection, call the + :method:`find() ` method with no parameters: + + .. code-block:: javascript + + db.products.find() + + The query will return all the documents with all the fields from + the collection ``products``. By default, in the :program:`mongo` + shell, the cursor returns the first batch of 20 matching + documents. In the :program:`mongo` shell, iterate through the next + batch by typing ``it``. Use the appropriate cursor + handling mechanism for your specific language driver. + + - To select the documents that match a selection criteria, call the + :method:`find() ` method with the ``query`` + criteria: + + .. code-block:: javascript + + db.products.find( { qty: { $gt: 25 } } ) + + The query will return all the documents from the collection + ``products`` where ``qty`` is greater than ``25``. The resulting + documents will contain all their respective fields. + + - To select the documents that match a selection criteria and return + only certain fields, call the :method:`find() + ` method with the ``query`` criteria and the + ``projection`` parameter using the ``include`` syntax: + + .. code-block:: javascript + + db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } ) + + The query will return all the documents from the collection + ``products`` where ``qty`` is greater than ``25``. The resulting + documents will contain only the ``_id``, ``item``, and ``qty`` + fields. Note that the ``_id`` field is returned even without + explicitly including it. + + .. code-block:: javascript + + { "_id" : 11, "item" : "pencil", "qty" : 50 } + { "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 } + { "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 } + + - To select the documents that match a selection criteria and + exclude certain fields from the resulting documents, call the + :method:`find() ` method with the ``query`` + criteria and the ``projection`` parameter using the ``exclude`` syntax: + + .. code-block:: javascript + + db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } ) + + The query will return all the documents from the collection + ``products`` where ``qty`` is greater than ``25``. The resulting + documents will contain all fields **except** the ``_id`` and + ``qty`` fields. + + .. code-block:: javascript + + { "item" : "pencil", "type" : "no.2" } + { "item" : "bottle", "type" : "blue" } + { "item" : "paper" } + + .. examples-end \ No newline at end of file diff --git a/source/reference/method/db.collection.insert.txt b/source/reference/method/db.collection.insert.txt index 0948411578c..b702096e9d1 100644 --- a/source/reference/method/db.collection.insert.txt +++ b/source/reference/method/db.collection.insert.txt @@ -5,15 +5,117 @@ db.collection.insert() .. default-domain:: mongodb .. method:: db.collection.insert(document) + + The :method:`insert() ` method inserts a + document or documents into a collection. - :param document: Specify a document to save to the ``collection``. + .. versionchanged:: 2.2 + The :method:`insert() ` method can accept + an array of documents to perform a bulk insert of the + documents into the collection. + + Consider the following behaviors of the :method:`insert() + ` method: + + - If the collection does not exist, then the :method:`insert() + ` method will create the collection. - :param array documents: Optional alternate. After version 2.2, if - you pass an array to :method:`insert() - `, :program:`mongo` - will perform a bulk insert operation and - insert all documents into the collection. + - If the document does not specify an :term:`_id` field, + then MongoDB will add the ``_id`` field and assign a unique + :term:`objectid` for the document before inserting. + + - If the document specifies a new field, then the + :method:`insert() ` method inserts the + document with the new field and *no* schema change is + necessary to the collection or the existing documents. + + The :method:`insert() ` method takes one of + the following parameters: - Inserts the :term:`document`, or documents, into a collection. If - you do not specify a value for the ``_id`` field, then MongoDB will - create a new ObjectID for this document before inserting. + :param document: + + A document to insert into the collection. + + :param array documents: + + .. versionadded:: 2.2 + + An array of documents to insert into the collection. + + .. examples-begin + + Consider the following examples of the :method:`insert() + ` method. + + - To insert a single document and have MongoDB generate the unique + ``_id``, omit the ``_id`` field in the document and pass + the document to the :method:`insert() ` + method as in the following: + + .. code-block:: javascript + + db.products.insert( { item: "card", qty: 15 } ) + + The query will insert into the ``products`` collection a new + document with the field ``item`` set to ``card``, the field + ``qty`` set to ``15`` and the field ``_id`` set to a unique + ``objectid``: + + .. code-block:: javascript + + { "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 } + + - To insert a single document where you specify the ``_id`` + field, include the ``_id`` field set to a unique identifier + and pass the document to the + :method:`insert() ` method as in the + following: + + .. code-block:: javascript + + db.products.insert( { _id: 10, item: "box", qty: 20 } ) + + The query will insert into the ``products`` collection a new + document with the field ``_id`` set to ``10``, + the field ``item`` set to ``box``, the field + ``qty`` set to ``20``: + + .. code-block:: javascript + + { "_id" : 10, "item" : "box", "qty" : 20 } + + - To insert multiple documents, pass an array of documents to the + :method:`insert() ` method as in the + following: + + .. code-block:: javascript + + db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" }, + { item: "pen", qty: 20 }, + { item: "eraser", qty: 25 } ] ) + + The query will insert into the ``products`` collection three documents: + + - A document with the fields ``_id`` set to ``11``, ``item`` + set to ``pencil``, ``qty`` set to ``50``, and the ``type`` set + to ``no.2``. + + - A document with the fields ``_id`` set to a unique + ``objectid``, ``item`` set to ``pen``, + and ``qty`` set to ``20``. + + - A document with the fields ``_id`` set to a unique + ``objectid``, ``item`` set to + ``eraser``, and ``qty`` set to ``25``. + + .. code-block:: javascript + + { "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" } + { "_id" : ObjectId("50631bc0be4617f17bb159ca"), "item" : "pen", "qty" : 20 } + { "_id" : ObjectId("50631bc0be4617f17bb159cb"), "item" : "eraser", "qty" : 25 } + + Notice that the addition of the new field ``type`` for the first + document did not require any changes to either the + collection or the other documents. + + .. examples-end diff --git a/source/reference/method/db.collection.remove.txt b/source/reference/method/db.collection.remove.txt index d3e255e68cf..dca85ba2a7e 100644 --- a/source/reference/method/db.collection.remove.txt +++ b/source/reference/method/db.collection.remove.txt @@ -6,39 +6,62 @@ db.collection.remove() .. method:: db.collection.remove(query,justOne) - Call the :method:`db.collection.remove()` method on a collection object, to - remove documents from a collection. Use the following form: + The :method:`remove ` method + removes documents from a collection. - .. code-block:: javascript + The :method:`remove() ` method can take the + following parameters: - db.collection.remove() + :param query: - Where ``collection`` is the name of the collection that you want - to remove. Without arguments, this method removes all documents in - the collection. To control the output of :method:`db.collection.remove()`: + Optional. A document that specifies the deletion + criteria using :doc:`query operators `. + Omit the ``query`` parameter or pass an empty ``{}`` document + to delete all :term:`documents ` in the + :term:`collection`. - :param query: Optional. Specify a query object to limit or filter - the documents to remove. See - :method:`db.collection.find()` and the :doc:`operator - reference ` for more - information. + :param boolean justOne: - :param Boolean justOne: Optional. Specify ``true`` to only delete - the first result. Equivalent to the - operation of :method:`db.collection.findOne()`. + Optional. A boolean that limits the deletion to just one + document. Default value is ``false``. Set to ``true`` to + delete only the first result. - Consider the following example: + .. examples-begin - .. code-block:: javascript + Consider the following examples of the :method:`remove + ` method. - db.records.remove({expired: 1, archived: 1}, false) + - To remove all documents in a collection, call the + :method:`remove ` method with no + parameters: - This is functionally equivalent to: + .. code-block:: javascript - .. code-block:: javascript + db.products.remove() - db.records.remove({expired: 1, archived: 1}) + The query will remove all the documents from the collection + ``products``. - These operations remove documents with ``expired`` *and* - ``archived`` fields holding a value of ``1`` from the - collection named ``records``. + - To remove the documents that match a deletion criteria, call the + :method:`remove ` method with the ``query`` + criteria: + + .. code-block:: javascript + + db.products.remove( { qty: { $gt: 20 } } ) + + The query will remove all the documents from the collection + ``products`` where ``qty`` is greater than ``20``. + + - To remove the first document that match a deletion criteria, call the + :method:`remove ` method with the ``query`` + criteria and the ``justOne`` parameter set to ``true``: + + .. code-block:: javascript + + db.products.remove( { qty: { $gt: 20 } }, true ) + + The query will remove all the documents from the collection + ``products`` where ``qty`` is greater than ``20``. + + .. examples-end diff --git a/source/reference/method/db.collection.save.txt b/source/reference/method/db.collection.save.txt index 6759f110727..48b9f7e15c0 100644 --- a/source/reference/method/db.collection.save.txt +++ b/source/reference/method/db.collection.save.txt @@ -6,11 +6,86 @@ db.collection.save() .. method:: db.collection.save(document) - :param document: Specify a document to save to the ``collection``. + The :method:`save() ` method updates an + existing document or inserts a document depending on the parameter. - If :term:`document` has an `_id` field, then perform an - :method:`db.collection.update()` with no :ref:`update-operators - ` as an :term:`upsert`. Otherwise, insert a new + The :method:`save() ` method takes the following + parameter: - document with fields from `document` and a newly generated - ObjectId() for the ``_id`` field. + :param document: + + Specify a document to save to the collection. + + **If** the document does not contain an :term:`_id` field, + then the :method:`save() ` method performs + an insert with the specified fields in the document as well + as an ``_id`` field with a unique :term:`objectid` value. + + **If** the document contains an ``_id`` field, then the + :method:`save() ` method performs an + ``upsert`` querying the collection on the ``_id`` field: + + - If a document does not exist with the specified ``_id`` value, + the :method:`save() ` method performs an + insert with the specified fields in the document. + + - If a document exists with the specified ``_id`` value, the + :method:`save() ` method performs an + update, replacing all field in the existing record with the + fields from the document. + + Consider the following examples of the :method:`save() + ` method: + + - Pass to the :method:`save() ` method a + document without the ``_id`` field to insert the document into the + collection and have MongoDB generate the unique ``_id`` as in the + following: + + .. code-block:: javascript + + db.products.save( { item: "book", qty: 40 } ) + + The query will insert into the ``products`` collection a new + document with the field ``item`` set to ``book``, the field + ``qty`` set to ``40`` and the field ``_id`` set to a unique + ``objectid``: + + .. code-block:: javascript + + { "_id" : ObjectId("50691737d386d8fadbd6b01d"), "item" : "book", "qty" : 40 } + + - Pass to the :method:`save() ` method a + document with the ``_id`` field whose value is not in the + collection to insert the document with the specified ``_id`` value + into the collection, as in the following: + + .. code-block:: javascript + + db.products.save( { _id: 100, item: "water", qty: 30 } ) + + The query will insert into the ``products`` collection a new + document with the field ``_id`` set to ``100``, the field ``item`` + set to ``water``, and the field ``qty`` set to ``30`` : + + .. code-block:: javascript + + { "_id" : 100, "item" : "water", "qty" : 30 } + + - Pass to the :method:`save() ` method a + document with the ``_id`` field matching a value in the + ``collection`` to replace all fields and values of the matching + document with the new fields and values, as in the following: + + .. code-block:: javascript + + db.products.save( { _id:100, item:"juice" } ) + + The query will replace the existing document that has the ``_id`` + value of ``100``. The updated document will only contain the + fields in the new document: + + .. code-block:: javascript + + { "_id" : 100, "item" : "juice" } + diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index 2177eed0b25..4013be30ae4 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -6,54 +6,46 @@ db.collection.update() .. method:: db.collection.update(query, update, [options]) - .. versionchanged:: 2.2 - The :program:`mongo` shell adds an updated interface that - accepts parameters in a more clear :term:`document` form to - specify ``multi`` and ``upsert`` options. - - The :method:`update() ` method provides the - ability to modify an existing document in a collection. + The :method:`update() ` method modifies an + existing document or documents in a collection. By default the + :method:`update() ` method updates a single + document. To update all documents in the collection that match the + update query criteria, specify the ``multi`` option. To insert a + document if no document matches the update query criteria, specify + the ``upsert`` option. - By default the :method:`update() ` method updates a - single document. If you specify a ``multi`` update, the - :method:`update() ` method will update all - documents in the collection that match the query criteria. If you - specify ``upsert``, the :method:`update() ` - method will insert the document if no document matches the query - criteria: otherwise, the operation is a conventional update. - - Before version 2.2, in the :program:`mongo` shell, ``upsert`` and - ``multi`` were positional boolean options and the operation has the - following form: + .. versionchanged:: 2.2 + The :program:`mongo` shell provides an updated interface that + accepts the options parameter in a document format to specify + ``multi`` and ``upsert`` options. + + Prior to version 2.2, in the :program:`mongo` shell, ``upsert`` and + ``multi`` were positional boolean options: .. code-block:: javascript - + db.collection.update(query, update, ) - Since version 2.2, the :method:`update() ` - method can *also* take an ``options`` :term:`document` as a - parameter to specify the ``multi`` and the ``upsert`` options. - The :method:`update() ` method takes the following parameters: :param document query: - A :term:`document` that specifies the selection criteria for - the update. The ``query`` parameter employs the same - :ref:`query selectors ` as used in the + A document that specifies the selection criteria for the + update. The ``query`` parameter employs the same :ref:`query + selectors ` as used in the :method:`db.collection.find()` method. :param document update: - A :term:`document` that specifies the modifications to apply. + A document that specifies the modifications to apply. **If** the ``update`` parameter contains any :ref:`update operators ` expressions such as the :operator:`$set` operator expression, then: - - the ``update`` parameter must contain only :ref:`update - operators ` expressions. + - the ``update`` parameter must contain only ``update + operators`` expressions. - the :method:`update() ` method updates only the corresponding fields in the document. @@ -61,19 +53,23 @@ db.collection.update() **If** the ``update`` parameter consists only of ``field: value`` expressions, then: - - the :method:`update() ` method updates the - document to contain only the :term:`_id` field and the - fields in the ``updates`` parameter. + - the :method:`update() ` method + *replaces* the document with the ``updates`` document. If + the ``updates`` document is missing the :term:`_id` field, + MongoDB will add the ``_id`` field and assign to it a + unique :term:`objectid` . - the :method:`update() ` method updates cannot update multiple documents. :param document options: - Optional. A :term:`document` that specifies whether to - perform an :term:`upsert` and/or a multiple update. You can - use the ``options`` parameter instead of the individual - ``upsert`` and ``multi`` parameters. + .. versionadded:: 2.2 + + Optional. A document that specifies whether to perform an + :term:`upsert` and/or a multiple update. You can use the + ``options`` parameter instead of the individual ``upsert`` + and ``multi`` parameters. :param boolean upsert: @@ -110,9 +106,17 @@ db.collection.update() In version 2.2 of the :program:`mongo` shell, you may also specify ``multi`` in the ``options`` parameter. + + Although the update operation may apply mostly to updating the + values of the fields, the :method:`update() + ` method can also modify the name of the + ``field`` in a document using the :operator:`$rename` operator. + + .. examples-begin + Consider the following examples of the :method:`update() ` method. These examples all use the 2.2 - option to specify options in document form. + interface to specify options in the document form. - To update specific fields in a single document, you can call the :method:`update() ` method with the ``update`` @@ -193,3 +197,5 @@ db.collection.update() .. code-block:: javascript db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true ) + + .. examples-end