From b6bb6cf4bde69d0fcbf2a1aec22271cdfe1c7712 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Tue, 14 Sep 2021 14:51:52 -0700 Subject: [PATCH] DOCSP-15486 fix build errors --- .../steps-compass-manual-queries.yaml | 31 +- source/reference/audit-message.txt | 44 +- source/reference/built-in-roles.txt | 7 - source/reference/command/mapReduce.txt | 2 +- source/reference/command/setAuditConfig.txt | 17 +- source/reference/privilege-actions.txt | 12 + source/reference/program/mongo.txt | 4 +- source/reference/program/mongod.txt | 2 +- source/reference/program/mongokerberos.txt | 2 +- source/reference/program/mongoldap.txt | 2 +- source/reference/program/mongos.txt | 2 +- source/release-notes/2.4-upgrade.txt | 4 +- .../tutorial/add-shards-to-shard-cluster.txt | 2 +- source/tutorial/configure-audit-filters.txt | 16 +- .../configure-linux-iptables-firewall.txt | 2 +- .../convert-secondary-into-arbiter.txt | 4 +- source/tutorial/expand-replica-set.txt | 2 +- source/tutorial/insert-documents.txt | 1326 ++++++------ source/tutorial/update-documents.txt | 1908 +++++++++-------- 19 files changed, 1762 insertions(+), 1627 deletions(-) diff --git a/source/includes/steps-compass-manual-queries.yaml b/source/includes/steps-compass-manual-queries.yaml index cec87ce5ace..909f42f6f52 100644 --- a/source/includes/steps-compass-manual-queries.yaml +++ b/source/includes/steps-compass-manual-queries.yaml @@ -1,34 +1,17 @@ -title: Enter a query in the query bar +title: Enter a document filter level: 4 ref: enter-query action: pre: | - Queries entered in the query bar must be valid MongoDB syntax. Only - :dbcommand:`finds ` will be executed. - - This example manually selects documents whose ``departureAirportFsCode`` is - "JFK". - - .. figure:: /images/compass/manual-query.png - :alt: Compass query bar with query entered - - When a valid query is entered, the bar is colored green and can be - executed. Invalid queries are colored red. The UI will automatically update - to indicate which fields and values are selected in the query. + A document filter must use valid MongoDB syntax. Only + :dbcommand:`finds ` can be executed. Invalid filters are + colored red. --- -title: Apply the query +title: Apply a document filter level: 4 ref: apply action: pre: | - After entering a query, run it by clicking the Apply button. To clear the - query, use the Reset button. - - Continuing with the example, executing the query displays information on the - matching documents. - - .. figure:: /images/compass/manual-query-results.png - :alt: Compass Apply button executes query - - To clear a query, use the Reset button. + To run a filter, click the :guilabel:`FIND` button. To clear a + filter, click the :guilabel:`RESET` button. ... diff --git a/source/reference/audit-message.txt b/source/reference/audit-message.txt index 56784e2f75e..e00e54ef9d9 100644 --- a/source/reference/audit-message.txt +++ b/source/reference/audit-message.txt @@ -178,7 +178,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-authenticate: - :authaction:`authenticate` + ``authenticate`` - .. code-block:: none :copyable: false @@ -189,7 +189,7 @@ associated ``param`` details and the ``result`` values, if any. mechanism: } - Starting in MongoDB 5.0, :authaction:`authenticate`: + Starting in MongoDB 5.0, ``authenticate``: - Is logged for incomplete authentication attempts. @@ -207,7 +207,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-authCheck: - :authaction:`authCheck` + ``authCheck`` - .. code-block:: none :copyable: false @@ -227,8 +227,8 @@ associated ``param`` details and the ``result`` values, if any. .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst - Starting in MongoDB 5.0, :authaction:`authCheck` is not logged - for actions that are generated internally. + Starting in MongoDB 5.0, ``authCheck`` is not logged for actions + that are generated internally. .. versionchanged:: 5.0 @@ -238,7 +238,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-clientMetadata: - :authaction:`clientMetadata` + ``clientMetadata`` - .. code-block:: none :copyable: false @@ -308,7 +308,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`createDatabase` + * - ``createDatabase`` - .. code-block:: none :copyable: false @@ -367,7 +367,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-directAuthMutation: - :authaction:`directAuthMutation` + ``directAuthMutation`` - .. code-block:: none :copyable: false @@ -389,7 +389,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`renameCollection` + * - ``renameCollection`` - .. code-block:: none :copyable: false @@ -495,7 +495,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropAllUsersFromDatabase` + * - ``dropAllUsersFromDatabase`` - .. code-block:: none :copyable: false @@ -505,7 +505,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`updateUser` + * - ``updateUser`` - .. code-block:: none :copyable: false @@ -529,7 +529,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantRolesToUser` + * - ``grantRolesToUser`` - .. code-block:: none :copyable: false @@ -549,7 +549,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokeRolesFromUser` + * - ``revokeRolesFromUser`` - .. code-block:: none :copyable: false @@ -601,7 +601,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`updateRole` + * - ``updateRole`` - .. code-block:: none :copyable: false @@ -646,7 +646,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropAllRolesFromDatabase` + * - ``dropAllRolesFromDatabase`` - .. code-block:: none :copyable: false @@ -656,7 +656,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantRolesToRole` + * - ``grantRolesToRole`` - .. code-block:: none :copyable: false @@ -676,7 +676,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokeRolesFromRole` + * - ``revokeRolesFromRole`` - .. code-block:: none :copyable: false @@ -696,7 +696,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantPrivilegesToRole` + * - ``grantPrivilegesToRole`` - .. code-block:: none :copyable: false @@ -719,7 +719,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokePrivilegesFromRole` + * - ``revokePrivilegesFromRole`` - .. code-block:: none :copyable: false @@ -779,7 +779,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`shardCollection` + * - ``shardCollection`` - .. code-block:: none :copyable: false @@ -861,7 +861,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-logout: - :authaction:`logout` + ``logout`` - .. code-block:: none :copyable: false @@ -895,7 +895,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-startup: - :authaction:`startup` + ``startup`` - .. code-block:: none :copyable: false diff --git a/source/reference/built-in-roles.txt b/source/reference/built-in-roles.txt index 02350dcb875..7a50fd15cc9 100644 --- a/source/reference/built-in-roles.txt +++ b/source/reference/built-in-roles.txt @@ -247,9 +247,7 @@ Cluster Administration Roles - :authaction:`cleanupOrphaned` - :authaction:`flushRouterConfig` - :authaction:`getDefaultRWConcern` (New in version 4.4) - - :authaction:`listSessions` (New in version 3.6) - - :authaction:`listShards` - :authaction:`removeShard` - :authaction:`replSetConfigure` @@ -257,9 +255,7 @@ Cluster Administration Roles - :authaction:`replSetGetStatus` - :authaction:`replSetStateChange` - :authaction:`resync` - - :authaction:`setDefaultRWConcern` (New in version 4.4) - - :authaction:`setFeatureCompatibilityVersion` - :authaction:`setFreeMonitoring` @@ -399,16 +395,13 @@ Cluster Administration Roles - :authaction:`hostInfo` - :authaction:`inprog` - :authaction:`listDatabases` - - :authaction:`listSessions` (New in version 3.6) - - :authaction:`listShards` - :authaction:`netstat` - :authaction:`replSetGetConfig` - :authaction:`replSetGetStatus` - :authaction:`serverStatus` - :authaction:`setFreeMonitoring` (New in version 4.0) - - :authaction:`shardingState` - :authaction:`top` diff --git a/source/reference/command/mapReduce.txt b/source/reference/command/mapReduce.txt index 370384114b3..54d0f15cc08 100644 --- a/source/reference/command/mapReduce.txt +++ b/source/reference/command/mapReduce.txt @@ -370,7 +370,7 @@ collection `: - :authaction:`find`, - :authaction:`insert`, -- :authaction:`replace` +- :authaction:`remove` Map-reduce with the ``merge`` or ``reduce`` actions when :ref:`outputting to a collection `: diff --git a/source/reference/command/setAuditConfig.txt b/source/reference/command/setAuditConfig.txt index 94cae1f0de1..136b7100fdf 100644 --- a/source/reference/command/setAuditConfig.txt +++ b/source/reference/command/setAuditConfig.txt @@ -59,14 +59,13 @@ Behavior Enable :doc:`Auditing ` to use :dbcommand:`setAuditConfig` at runtime. -:parameter:`auditAuthorizationSuccess` enables -:doc:`auditing ` of authorization success for the -:ref:`authCheck ` action. The parameter -value must be ``true`` to audit :authaction:`read` and -:authaction:`write` operations. However, when +:parameter:`auditAuthorizationSuccess` enables :doc:`auditing +` of authorization success for the :ref:`authCheck +` action. The parameter value must be +``true`` to audit read and write operations. However, when :parameter:`auditAuthorizationSuccess` is ``false`` auditing has less -performance impact because the :doc:`audit system ` -only logs authorization failures. +performance impact because the :doc:`audit system ` only +logs authorization failures. Configuration updates are distributed via the :term:`oplog` mechanism which means updates on :binary:`~bin.mongod` nodes are distributed to @@ -146,8 +145,8 @@ Audit Document Interactions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set :parameter:`auditAuthorizationSuccess` to ``true`` and create a -filter which includes actions of interest to audit :authaction:`read` -and :authaction:`write` operations. +filter which includes actions of interest to audit read and write +operations. .. code-block:: javascript diff --git a/source/reference/privilege-actions.txt b/source/reference/privilege-actions.txt index 6f0f3c867ff..7fbed05869b 100644 --- a/source/reference/privilege-actions.txt +++ b/source/reference/privilege-actions.txt @@ -265,6 +265,13 @@ Database Management Actions User can kill **any** cursor, even cursors created by other users. Apply this action to collection resources. +.. authaction:: planCacheIndexFilter + + User can run the :dbcommand:`planCacheClearFilters`, + :dbcommand:`planCacheListFilters`, and + :dbcommand:`planCacheSetFilter` commands. Apply the + :authaction:`planCacheIndexFilter` action to collection resources. + .. authaction:: revokeRole User can remove any role from any user from any database in the system. @@ -302,6 +309,11 @@ Database Management Actions Apply this action to database resources. +.. authaction:: setFeatureCompatibilityVersion + + User can run the :dbcommand:`setFeatureCompatibilityVersion` command. + Apply this action to the ``cluster`` resource. + .. authaction:: unlock User can perform the :method:`db.fsyncUnlock()` method. Apply this diff --git a/source/reference/program/mongo.txt b/source/reference/program/mongo.txt index f97890f2fdf..329a36086c5 100644 --- a/source/reference/program/mongo.txt +++ b/source/reference/program/mongo.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongo @@ -435,7 +435,7 @@ Core Options Specifies a JavaScript file to run and then exit. Generally this should be the last option specified. - .. optional:: + .. note:: Optional To specify a JavaScript file to execute *and* allow :program:`mongo` to prompt you for a password using diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt index d6cfb153029..71c82a35e9e 100644 --- a/source/reference/program/mongod.txt +++ b/source/reference/program/mongod.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongod diff --git a/source/reference/program/mongokerberos.txt b/source/reference/program/mongokerberos.txt index b85d4439afe..719fc495811 100644 --- a/source/reference/program/mongokerberos.txt +++ b/source/reference/program/mongokerberos.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongokerberos diff --git a/source/reference/program/mongoldap.txt b/source/reference/program/mongoldap.txt index 0551a638b6f..ff187ff43c2 100644 --- a/source/reference/program/mongoldap.txt +++ b/source/reference/program/mongoldap.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongoldap diff --git a/source/reference/program/mongos.txt b/source/reference/program/mongos.txt index c35404b688b..289e98408cd 100644 --- a/source/reference/program/mongos.txt +++ b/source/reference/program/mongos.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongos diff --git a/source/release-notes/2.4-upgrade.txt b/source/release-notes/2.4-upgrade.txt index 5e4f50a00ee..1fa2f673c08 100644 --- a/source/release-notes/2.4-upgrade.txt +++ b/source/release-notes/2.4-upgrade.txt @@ -210,7 +210,7 @@ operations. :term:`sharded cluster`, as described in :ref:`sharding-balancing-disable-temporarily`. - .. optional:: + .. note:: Optional For additional security during the upgrade, you can make a backup of the config database using :binary:`~bin.mongodump` or @@ -265,7 +265,7 @@ operations. require manual intervention. To continue the upgrade process, you must follow the :ref:`upgrade-cluster-resync` procedure. - .. optional:: + .. note:: Optional If the :binary:`~bin.mongos` logs show the upgrade waiting for the upgrade lock, a previous upgrade process may still be active or diff --git a/source/tutorial/add-shards-to-shard-cluster.txt b/source/tutorial/add-shards-to-shard-cluster.txt index 83a6fb7754a..c56c73c305f 100644 --- a/source/tutorial/add-shards-to-shard-cluster.txt +++ b/source/tutorial/add-shards-to-shard-cluster.txt @@ -55,7 +55,7 @@ instance. name of the replica set and specify a member of the set. In production deployments, all shards should be replica sets. - .. optional:: + .. note:: Optional You can instead use the :dbcommand:`addShard` database command, which lets you specify a name and maximum size for the diff --git a/source/tutorial/configure-audit-filters.txt b/source/tutorial/configure-audit-filters.txt index 7e1dbf83bbd..71a42f6bba1 100644 --- a/source/tutorial/configure-audit-filters.txt +++ b/source/tutorial/configure-audit-filters.txt @@ -133,8 +133,8 @@ that occur against the ``test`` database by using the filter: path: data/db/auditLog.bson filter: '{ atype: "authenticate", "param.db": "test" }' -To filter on all :authaction:`authenticate` operations across -databases, use the filter ``{ atype: "authenticate" }``. +To filter on all ``authenticate`` operations across databases, omit +``"param.db": "test"`` and use the filter ``{ atype: "authenticate" }``. Filter on Collection Creation and Drop Operations for a Single Database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -215,9 +215,9 @@ with roles that inherit from :authrole:`readWrite`, by using the filter: Filter on Read and Write Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To capture :authaction:`read` and :authaction:`write` operations in the -audit, you must also enable the audit system to log authorization -successes using the :parameter:`auditAuthorizationSuccess` parameter. +To capture read and write operations in the audit, you must also +enable the audit system to log authorization successes using the +:parameter:`auditAuthorizationSuccess` parameter. [#authorization-agnostic]_ .. note:: @@ -260,9 +260,9 @@ The following example audits the :method:`~db.collection.find()`, Filter on Read and Write Operations for a Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To capture :authaction:`read` and :authaction:`write` operations in the -audit, you must also enable the audit system to log authorization -successes using the :parameter:`auditAuthorizationSuccess` parameter. +To capture read and write operations in the audit, you must also +enable the audit system to log authorization successes using the +:parameter:`auditAuthorizationSuccess` parameter. [#authorization-agnostic]_ .. note:: diff --git a/source/tutorial/configure-linux-iptables-firewall.txt b/source/tutorial/configure-linux-iptables-firewall.txt index 44b1eb87259..adc79ca951d 100644 --- a/source/tutorial/configure-linux-iptables-firewall.txt +++ b/source/tutorial/configure-linux-iptables-firewall.txt @@ -82,7 +82,7 @@ port ``27017``, which allows the application server to connect to the :binary:`~bin.mongod` instance. The second rule, allows outgoing traffic from the :binary:`~bin.mongod` to reach the application server. -.. optional:: +.. note:: Optional If you have only one application server, you can replace ```` with either the IP address itself, such as: diff --git a/source/tutorial/convert-secondary-into-arbiter.txt b/source/tutorial/convert-secondary-into-arbiter.txt index 541fc195dca..07225ba3e71 100644 --- a/source/tutorial/convert-secondary-into-arbiter.txt +++ b/source/tutorial/convert-secondary-into-arbiter.txt @@ -65,7 +65,7 @@ Convert Secondary to Arbiter and Reuse the Port Number mv /data/db /data/db-old - .. optional:: + .. note:: Optional You may remove the data instead. @@ -178,6 +178,6 @@ Convert Secondary to Arbiter Running on a New Port Number mv /data/db /data/db-old - .. optional:: + .. note:: Optional You may remove the data instead. diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index 02f227547d9..5903889f79d 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -136,7 +136,7 @@ Add a Member to an Existing Replica Set For more information on configuration options, see the :binary:`~bin.mongod` manual page. - .. optional:: + .. note:: Optional You can specify the data directory, replica set name, and the ip binding in the ``mongod.conf`` :doc:`configuration file diff --git a/source/tutorial/insert-documents.txt b/source/tutorial/insert-documents.txt index 04012b5a814..6ef7460ce23 100644 --- a/source/tutorial/insert-documents.txt +++ b/source/tutorial/insert-documents.txt @@ -28,7 +28,6 @@ This page provides examples of insert operations in MongoDB. .. note:: Creating a Collection - If the collection does not currently exist, insert operations will create the collection. @@ -39,294 +38,311 @@ Insert a Single Document .. tabs-drivers:: - tabs: - - id: shell - content: | - :method:`db.collection.insertOne()` inserts a *single* - :ref:`document` into a collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, MongoDB adds the ``_id`` field with an - ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: compass - content: | - To insert a single document using :ref:`MongoDB Compass `: - - 1. Navigate to the collection you wish to insert the document - into: - - a. In the left-hand MongoDB Compass navigation pane, click - the database to which your target collection belongs. - - b. From the database view, click the target collection name. - - 2. Click the :guilabel:`Insert Document` button: - - .. figure:: /images/compass-insert-button.png - :alt: Compass insert button - - 3. For each field in the document, select the field type and - fill in the field name and value. Add fields by clicking - the last line number, then clicking - :guilabel:`Add Field After ...` - - - For ``Object`` types, add nested fields by clicking the - last field's number and selecting - :guilabel:`Add Field After ...` - - - For ``Array`` types, add additional elements to the array - by clicking the last element's line number and selecting - :guilabel:`Add Array Element After ...` - - 4. Once all fields have been filled out, click :guilabel:`Insert`. - - The following example inserts a new document into the - ``test.inventory`` collection: - - - id: python - content: | - :py:meth:`pymongo.collection.Collection.insert_one` inserts a - *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the PyMongo driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: motor - content: | - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` inserts a - *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Motor driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: java-sync - content: | - com.mongodb.client.MongoCollection.insertOne_ - inserts a *single* :ref:`document` into - a collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the driver adds the ``_id`` field with an - ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: java-async - content: | - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ - inserts a *single* :ref:`document` into - a collection with the `Java Reactive Streams - Driver `_: - - .. code-block:: json - - { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } - - The following example inserts the document above into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the driver adds the ``_id`` field with an - ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: nodejs - content: | - :node-api:`Collection.insertOne() ` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Node.js driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: php - content: | - :phpmethod:`MongoDB\\Collection::insertOne() ` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the PHP driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: perl - content: | - :perl-api:`MongoDB::Collection::insert_one()` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Perl driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: ruby - content: | - :ruby-api:`Mongo::Collection#insert_one()` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Ruby driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: scala - content: | - :scala-api:`collection.insertOne()` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Scala driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: csharp - content: | - :csharp-api:`IMongoCollection.InsertOne() ` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the C# driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: go - content: | - - :go-api:`Collection.InsertOne ` - inserts a *single* :ref:`document` into a - collection. + .. tab:: + :tabid: shell + + :method:`db.collection.insertOne()` inserts a *single* + :ref:`document` into a collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, MongoDB adds the ``_id`` field with an + ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: compass + + To insert a single document using :ref:`MongoDB Compass `: + + 1. Navigate to the collection you wish to insert the document + into: + + a. In the left-hand MongoDB Compass navigation pane, click + the database to which your target collection belongs. + + b. From the database view, click the target collection name. + + 2. Click the :guilabel:`Insert Document` button: + + .. figure:: /images/compass-insert-button.png + :alt: Compass insert button + + 3. For each field in the document, select the field type and + fill in the field name and value. Add fields by clicking + the last line number, then clicking + :guilabel:`Add Field After ...` + + - For ``Object`` types, add nested fields by clicking the + last field's number and selecting + :guilabel:`Add Field After ...` + + - For ``Array`` types, add additional elements to the array + by clicking the last element's line number and selecting + :guilabel:`Add Array Element After ...` + + 4. Once all fields have been filled out, click :guilabel:`Insert`. + + The following example inserts a new document into the + ``test.inventory`` collection: + + .. tab:: + :tabid: python + + :py:meth:`pymongo.collection.Collection.insert_one` inserts a + *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the PyMongo driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: motor + + :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` inserts a + *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Motor driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-sync + + com.mongodb.client.MongoCollection.insertOne_ + inserts a *single* :ref:`document` into + a collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the driver adds the ``_id`` field with an + ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-async + + `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + inserts a *single* :ref:`document` into + a collection with the `Java Reactive Streams + Driver `_: + + .. code-block:: json + + { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } + + The following example inserts the document above into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the driver adds the ``_id`` field with an + ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: nodejs + + :node-api:`Collection.insertOne() ` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Node.js driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: php + + :phpmethod:`MongoDB\\Collection::insertOne() ` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the PHP driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: perl + + :perl-api:`MongoDB::Collection::insert_one()` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Perl driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: ruby + + :ruby-api:`Mongo::Collection#insert_one()` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Ruby driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: scala + + :scala-api:`collection.insertOne()` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Scala driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: csharp + + :csharp-api:`IMongoCollection.InsertOne() ` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the C# driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: go + + :go-api:`Collection.InsertOne ` + inserts a *single* :ref:`document` into a + collection. - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. .. include:: /includes/driver-examples/driver-example-insert-1.rst .. tabs-drivers:: - tabs: - - id: shell - content: | - :method:`~db.collection.insertOne()` returns a document that - includes the newly inserted document's ``_id`` field value. For - an example of a return document, see - :ref:`db.collection.insertOne() reference`. - - - id: compass - content: | - .. note:: - - MongoDB Compass generates the ``_id`` field and its value - automatically. The generated - :term:`ObjectId` consists of a - unique randomly generated hexadecimal value. - - You can change this value prior to inserting your document - so long as it remains unique and is a valid ``ObjectId``. - For more information on the ``_id`` field, see - :ref:`_id Field `. - - - id: python - content: | - :py:meth:`~pymongo.collection.Collection.insert_one` returns an - instance of :py:class:`pymongo.results.InsertOneResult` whose - ``inserted_id`` field contains the ``_id`` of the newly - inserted document. - - - id: motor - content: | - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_one` returns an - instance of :py:class:`pymongo.results.InsertOneResult` whose - ``inserted_id`` field contains the ``_id`` of the newly - inserted document. - - - id: java-sync - content: | - - - id: java-async - content: | - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ - returns a `Publisher `_ - object. The ``Publisher`` inserts the document into a collection when subscribers request data. - - - id: nodejs - content: | - :node-api:`insertOne() ` returns a - promise that provides a ``result``. The ``result.insertedId`` - promise contains the ``_id`` of the newly inserted document. - - - id: php - content: | - Upon successful insert, the - :phpmethod:`insertOne() ` - method returns an instance of - :phpclass:`MongoDB\\InsertOneResult ` - whose - :phpmethod:`getInsertedId() ` - method returns the ``_id`` of the newly inserted document. - - - id: perl - content: | - Upon successful insert, the - :perl-api:`insert_one()` method returns - an instance of - :perl-api:`MongoDB::InsertOneResult` whose - ``inserted_id`` attribute contains the ``_id`` of the newly - inserted document. - - - id: ruby - content: | - Upon successful insert, the - :ruby-api:`insert_one()` - method returns an instance of - :ruby-api:`Mongo::Operation::Result`, whose - ``inserted_id`` attribute contains the ``_id`` of the newly - inserted document. - - - id: scala - content: | - Upon successful insert, the - :scala-api:`collection.insertOne()` - method returns an instance of - :scala-api:`collection.insertOne().results();` whose - ``inserted_id`` attribute contains the ``_id`` of the newly - inserted document. - - - id: csharp - content: | - - - id: go - content: | - - :go-api:`Collection.InsertOne ` - function returns an instance of - :go-api:`InsertOneResult` whose - ``InsertedID`` attribute contains the ``_id`` of the newly - inserted document. + .. tab:: + :tabid: shell + + :method:`~db.collection.insertOne()` returns a document that + includes the newly inserted document's ``_id`` field value. For + an example of a return document, see + :ref:`db.collection.insertOne() reference`. + + .. tab:: + :tabid: compass + + .. note:: + + MongoDB Compass generates the ``_id`` field and its value + automatically. The generated + :term:`ObjectId` consists of a + unique randomly generated hexadecimal value. + + You can change this value prior to inserting your document + so long as it remains unique and is a valid ``ObjectId``. + For more information on the ``_id`` field, see + :ref:`_id Field `. + + .. tab:: + :tabid: python + + :py:meth:`~pymongo.collection.Collection.insert_one` returns an + instance of :py:class:`pymongo.results.InsertOneResult` whose + ``inserted_id`` field contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: motor + + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_one` returns an + instance of :py:class:`pymongo.results.InsertOneResult` whose + ``inserted_id`` field contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: java-sync + + `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + returns a `Publisher `_ + object. The ``Publisher`` inserts the document into a collection when subscribers request data. + + .. tab:: + :tabid: nodejs + + :node-api:`insertOne() ` returns a + promise that provides a ``result``. The ``result.insertedId`` + promise contains the ``_id`` of the newly inserted document. + + .. tab:: + :tabid: php + + Upon successful insert, the + :phpmethod:`insertOne() ` + method returns an instance of + :phpclass:`MongoDB\\InsertOneResult ` + whose + :phpmethod:`getInsertedId() ` + method returns the ``_id`` of the newly inserted document. + + .. tab:: + :tabid: perl + + Upon successful insert, the + :perl-api:`insert_one()` method returns + an instance of + :perl-api:`MongoDB::InsertOneResult` whose + ``inserted_id`` attribute contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: ruby + + Upon successful insert, the + :ruby-api:`insert_one()` + method returns an instance of + :ruby-api:`Mongo::Operation::Result`, whose + ``inserted_id`` attribute contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: scala + + Upon successful insert, the + :scala-api:`collection.insertOne()` + method returns an instance of + :scala-api:`collection.insertOne().results();` whose + ``inserted_id`` attribute contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: go + + :go-api:`Collection.InsertOne ` + function returns an instance of + :go-api:`InsertOneResult` whose + ``InsertedID`` attribute contains the ``_id`` of the newly + inserted document. To retrieve the document that you just inserted, :ref:`query the collection `: @@ -347,298 +363,316 @@ upper-right to set the language of the examples on this page. .. tabs-drivers:: - tabs: - - id: shell - content: | - .. versionadded:: 3.2 - - :method:`db.collection.insertMany()` can insert *multiple* - :ref:`documents ` into a collection. Pass an - array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, MongoDB adds the ``_id`` field with an ObjectId - value to each document. See :ref:`write-op-insert-behavior`. - - - id: compass - content: | - Currently, MongoDB Compass does not support inserting multiple - documents in a single operation. - - - id: python - content: | - .. versionadded:: 3.2 - - :py:meth:`pymongo.collection.Collection.insert_many` can insert - *multiple* :ref:`documents ` into a - collection. Pass an iterable of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the PyMongo driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: motor - content: | - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` - can insert *multiple* :ref:`documents ` - into a collection. Pass an iterable of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the PyMongo driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: java-sync - content: | - .. versionadded:: 3.2 - - com.mongodb.client.MongoCollection.insertMany_ - can insert *multiple* :ref:`documents ` - into a collection. Pass a list of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: java-async - content: | - .. versionadded:: 3.2 - - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany - `_ - inserts the following documents with the `Java Reactive Streams - Driver `_: - - .. code-block:: json - - { item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } } - { item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } } - { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } } - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: nodejs - content: | - .. versionadded:: 3.2 - - :node-api:`Collection.insertMany() ` - can insert *multiple* :ref:`documents ` - into a collection. Pass an array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Node.js driver adds the ``_id`` field with - an ObjectId value to each document. See - :ref:`write-op-insert-behavior`. - - - id: php - content: | - .. versionadded:: 3.2 - - :phpmethod:`MongoDB\\Collection::insertMany() ` - can insert *multiple* :ref:`documents ` into a - collection. Pass an array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the PHP driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: perl - content: | - .. versionadded:: 3.2 - - :perl-api:`MongoDB::Collection::insert_many()` - can insert *multiple* :ref:`documents ` into a - collection. Pass an array reference of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Perl driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: ruby - content: | - .. versionadded:: 3.2 - - :ruby-api:`Mongo::Collection#insert_many()` - can insert *multiple* :ref:`documents ` into a - collection. Pass an array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Ruby driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: scala - content: | - .. versionadded:: 3.2 - - :scala-api:`collection.insertMany()` - can insert *multiple* :ref:`documents ` into a - collection. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Scala driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: csharp - content: | - .. versionadded:: 3.2 - - :csharp-api:`IMongoCollection.InsertMany()` - can insert *multiple* :ref:`documents ` - into a collection. Pass an enumerable collection of documents - to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: go - content: | - - :go-api:`Collection.InsertMany ` - can insert *multiple* :ref:`documents ` into a - collection. + .. tab:: + :tabid: shell + + .. versionadded:: 3.2 + + :method:`db.collection.insertMany()` can insert *multiple* + :ref:`documents ` into a collection. Pass an + array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, MongoDB adds the ``_id`` field with an ObjectId + value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: compass + + Currently, MongoDB Compass does not support inserting multiple + documents in a single operation. + + .. tab:: + :tabid: python + + .. versionadded:: 3.2 + + :py:meth:`pymongo.collection.Collection.insert_many` can insert + *multiple* :ref:`documents ` into a + collection. Pass an iterable of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the PyMongo driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: motor + + :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` + can insert *multiple* :ref:`documents ` + into a collection. Pass an iterable of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the PyMongo driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-sync + + .. versionadded:: 3.2 + + com.mongodb.client.MongoCollection.insertMany_ + can insert *multiple* :ref:`documents ` + into a collection. Pass a list of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-async + + .. versionadded:: 3.2 + + `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany + `_ + inserts the following documents with the `Java Reactive Streams + Driver `_: + + .. code-block:: json + + { item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } } + { item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } } + { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } } + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: nodejs + + .. versionadded:: 3.2 + + :node-api:`Collection.insertMany() ` + can insert *multiple* :ref:`documents ` + into a collection. Pass an array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Node.js driver adds the ``_id`` field with + an ObjectId value to each document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: php + + .. versionadded:: 3.2 + + :phpmethod:`MongoDB\\Collection::insertMany() ` + can insert *multiple* :ref:`documents ` into a + collection. Pass an array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the PHP driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: perl + + .. versionadded:: 3.2 + + :perl-api:`MongoDB::Collection::insert_many()` + can insert *multiple* :ref:`documents ` into a + collection. Pass an array reference of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Perl driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: ruby + + .. versionadded:: 3.2 + + :ruby-api:`Mongo::Collection#insert_many()` + can insert *multiple* :ref:`documents ` into a + collection. Pass an array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Ruby driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: scala + + .. versionadded:: 3.2 + + :scala-api:`collection.insertMany()` + can insert *multiple* :ref:`documents ` into a + collection. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Scala driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: csharp + + .. versionadded:: 3.2 + + :csharp-api:`IMongoCollection.InsertMany()` + can insert *multiple* :ref:`documents ` + into a collection. Pass an enumerable collection of documents + to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: go + + :go-api:`Collection.InsertMany ` + can insert *multiple* :ref:`documents ` into a + collection. - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. .. include:: /includes/driver-examples/driver-example-insert-3.rst .. tabs-drivers:: - tabs: - - id: shell - content: | - :method:`~db.collection.insertMany()` returns a document that includes - the newly inserted documents ``_id`` field values. See the - :ref:`reference ` for an example. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: python - content: | - :py:meth:`~pymongo.collection.Collection.insert_many` returns - an instance of :py:class:`pymongo.results.InsertManyResult` - whose ``inserted_ids`` field is a list containing the ``_id`` - of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: motor - content: | - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_many` - returns an instance of :py:class:`pymongo.results.InsertManyResult` - whose ``inserted_ids`` field is a list containing the ``_id`` - of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: java-sync - content: | - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: java-async - content: | - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany - `_ - returns a `Publisher `_ - object. The ``Publisher`` inserts the document into a collection - when subscribers request data. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: nodejs - content: | - :node-api:`insertMany() ` returns a - promise that provides a ``result``. The ``result.insertedIds`` - field contains an array with the ``_id`` of each newly inserted - document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: php - content: | - Upon successful insert, the - :phpmethod:`insertMany() ` - method - returns an instance of - :phpclass:`MongoDB\\InsertManyResult ` - whose - :phpmethod:`getInsertedIds() ` - method returns the ``_id`` of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: perl - content: | - Upon successful insert, the - :perl-api:`insert_many()` method - returns an instance of - :perl-api:`MongoDB::InsertManyResult` - whose ``inserted_ids`` attribute is a list containing the - ``_id`` of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: ruby - content: | - Upon successful insert, the - :ruby-api:`insert_many()` method - returns an instance of - :ruby-api:`Mongo::BulkWrite::Result` - whose ``inserted_ids`` attribute is a list containing the - ``_id`` of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: scala - content: | - Upon successful insert, the - :scala-api:`insertMany()` - method returns an `Observable `_ with a type parameter indicating when - the operation has completed or with either a - ``com.mongodb.DuplicateKeyException`` or - ``com.mongodb.MongoException``. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: csharp - content: | - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: go - content: | - - To retrieve the inserted documents, :ref:`query the collection - `: + .. tab:: + :tabid: shell + + :method:`~db.collection.insertMany()` returns a document that includes + the newly inserted documents ``_id`` field values. See the + :ref:`reference ` for an example. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: python + + :py:meth:`~pymongo.collection.Collection.insert_many` returns + an instance of :py:class:`pymongo.results.InsertManyResult` + whose ``inserted_ids`` field is a list containing the ``_id`` + of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: motor + + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_many` + returns an instance of :py:class:`pymongo.results.InsertManyResult` + whose ``inserted_ids`` field is a list containing the ``_id`` + of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: java-sync + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: java-async + + `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany + `_ + returns a `Publisher `_ + object. The ``Publisher`` inserts the document into a collection + when subscribers request data. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: nodejs + + :node-api:`insertMany() ` returns a + promise that provides a ``result``. The ``result.insertedIds`` + field contains an array with the ``_id`` of each newly inserted + document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: php + + Upon successful insert, the + :phpmethod:`insertMany() ` + method + returns an instance of + :phpclass:`MongoDB\\InsertManyResult ` + whose + :phpmethod:`getInsertedIds() ` + method returns the ``_id`` of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: perl + + Upon successful insert, the + :perl-api:`insert_many()` method + returns an instance of + :perl-api:`MongoDB::InsertManyResult` + whose ``inserted_ids`` attribute is a list containing the + ``_id`` of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: ruby + + Upon successful insert, the + :ruby-api:`insert_many()` method + returns an instance of + :ruby-api:`Mongo::BulkWrite::Result` + whose ``inserted_ids`` attribute is a list containing the + ``_id`` of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: scala + + Upon successful insert, the + :scala-api:`insertMany()` + method returns an `Observable `_ with a type parameter indicating when + the operation has completed or with either a + ``com.mongodb.DuplicateKeyException`` or + ``com.mongodb.MongoException``. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: csharp + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: go + + To retrieve the inserted documents, :ref:`query the collection + `: .. include:: /includes/driver-examples/driver-example-query-7.rst @@ -677,124 +711,136 @@ requested from MongoDB for write operations. For details, see .. tabs-drivers:: - tabs: - - id: shell - content: | - .. seealso:: + .. tab:: + :tabid: shell + + .. seealso:: + + - :method:`db.collection.insertOne()` + + - :method:`db.collection.insertMany()` + + - :ref:`additional-inserts` + + .. tab:: + :tabid: python + + .. seealso:: + + - :py:meth:`pymongo.collection.Collection.insert_one` + + - :py:meth:`pymongo.collection.Collection.insert_many` + + - :ref:`additional-inserts` + + .. tab:: + :tabid: motor + + .. seealso:: + + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` + + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` - - :method:`db.collection.insertOne()` + - :ref:`additional-inserts` - - :method:`db.collection.insertMany()` + .. tab:: + :tabid: java-sync - - :ref:`additional-inserts` + .. seealso:: - - id: python - content: | - .. seealso:: + - com.mongodb.client.MongoCollection.insertOne_ - - :py:meth:`pymongo.collection.Collection.insert_one` + - com.mongodb.client.MongoCollection.insertMany_ - - :py:meth:`pymongo.collection.Collection.insert_many` + - `Additional Java Synchronous Driver Write Examples`_ - - :ref:`additional-inserts` + .. tab:: + :tabid: java-async - - id: motor - content: | - .. seealso:: + .. seealso:: - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` + - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` + - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany `_ - - :ref:`additional-inserts` + - `Java Reactive Streams Driver Quick Tour `_ - - id: java-sync - content: | - .. seealso:: + .. tab:: + :tabid: nodejs - - com.mongodb.client.MongoCollection.insertOne_ + .. seealso:: - - com.mongodb.client.MongoCollection.insertMany_ + - :node-api:`Collection.insertOne() ` - - `Additional Java Synchronous Driver Write Examples`_ + - :node-api:`Collection.insertMany() ` - - id: java-async - content: | - .. seealso:: + - :ref:`additional-inserts` - - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + .. tab:: + :tabid: php - - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany `_ + .. seealso:: - - `Java Reactive Streams Driver Quick Tour `_ + - :phpmethod:`MongoDB\\Collection::insertOne() ` - - id: nodejs - content: | - .. seealso:: + - :phpmethod:`MongoDB\\Collection::insertMany() ` - - :node-api:`Collection.insertOne() ` + - :ref:`additional-inserts` - - :node-api:`Collection.insertMany() ` + .. tab:: + :tabid: perl - - :ref:`additional-inserts` + .. seealso:: - - id: php - content: | - .. seealso:: + - :perl-api:`MongoDB::Collection::insert_one()` - - :phpmethod:`MongoDB\\Collection::insertOne() ` + - :perl-api:`MongoDB::Collection::insert_many()` - - :phpmethod:`MongoDB\\Collection::insertMany() ` + - :ref:`additional-inserts` - - :ref:`additional-inserts` + .. tab:: + :tabid: ruby - - id: perl - content: | - .. seealso:: + .. seealso:: - - :perl-api:`MongoDB::Collection::insert_one()` + - :ruby-api:`Mongo::Collection#insert_one()` - - :perl-api:`MongoDB::Collection::insert_many()` + - :ruby-api:`Mongo::Collection#insert_many()` - - :ref:`additional-inserts` + .. tab:: + :tabid: scala - - id: ruby - content: | - .. seealso:: + .. seealso:: - - :ruby-api:`Mongo::Collection#insert_one()` + - :scala-api:`collection.insertOne()` - - :ruby-api:`Mongo::Collection#insert_many()` + - :scala-api:`collection.insertMany()` - - id: scala - content: | - .. seealso:: + - :ref:`additional-inserts` - - :scala-api:`collection.insertOne()` + .. tab:: + :tabid: csharp - - :scala-api:`collection.insertMany()` + .. seealso:: - - :ref:`additional-inserts` + - :csharp-api:`IMongoCollection.InsertOne() ` - - id: csharp - content: | - .. seealso:: + - :csharp-api:`IMongoCollection.InsertMany() ` - - :csharp-api:`IMongoCollection.InsertOne() ` + - :ref:`additional-inserts` - - :csharp-api:`IMongoCollection.InsertMany() ` + .. tab:: + :tabid: go - - :ref:`additional-inserts` + .. seealso:: - - id: go - content: | - .. seealso:: + - :go-api:`Collection.InsertOne ` - - :go-api:`Collection.InsertOne ` + - :go-api:`Collection.InsertMany ` - - :go-api:`Collection.InsertMany ` + - :ref:`additional-inserts` - - :ref:`additional-inserts` .. toctree:: :titlesonly: :hidden: diff --git a/source/tutorial/update-documents.txt b/source/tutorial/update-documents.txt index 73f542db208..a8b62eab4c3 100644 --- a/source/tutorial/update-documents.txt +++ b/source/tutorial/update-documents.txt @@ -30,177 +30,188 @@ upper-right to set the language of the following examples. .. tabs-drivers:: - tabs: - - id: shell - content: | - This page uses the following :binary:`~bin.mongosh` methods: + .. tab:: + :tabid: shell - - :method:`db.collection.updateOne(\, \, \) ` + This page uses the following :binary:`~bin.mongosh` methods: - - :method:`db.collection.updateMany(\, \, \) ` + - :method:`db.collection.updateOne(\, \, \) ` - - :method:`db.collection.replaceOne(\, \, \) ` + - :method:`db.collection.updateMany(\, \, \) ` - |populate-inventory| + - :method:`db.collection.replaceOne(\, \, \) ` - - id: compass - content: | + |populate-inventory| - This page uses :ref:`MongoDB Compass ` to - update the documents. + .. tab:: + :tabid: compass - The examples on this page use the ``inventory`` collection. - Populate the ``inventory`` collection with the following - documents: + This page uses :ref:`MongoDB Compass ` to + update the documents. - - id: python - content: | - This page uses the - following :api:`PyMongo ` - Python driver methods: + The examples on this page use the ``inventory`` collection. + Populate the ``inventory`` collection with the following + documents: - - :py:meth:`pymongo.collection.Collection.update_one` + .. tab:: + :tabid: python - - :py:meth:`pymongo.collection.Collection.update_many` + This page uses the + following :api:`PyMongo ` + Python driver methods: - - :py:meth:`pymongo.collection.Collection.replace_one` + - :py:meth:`pymongo.collection.Collection.update_one` - |populate-inventory| + - :py:meth:`pymongo.collection.Collection.update_many` - - id: motor - content: | - This page uses the - following `Motor `_ - driver methods: + - :py:meth:`pymongo.collection.Collection.replace_one` + + |populate-inventory| - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` + .. tab:: + :tabid: motor - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` + This page uses the + following `Motor `_ + driver methods: - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` - |populate-inventory| + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` - - id: java-sync - content: | - This page uses the - following `Java Synchronous Driver`_ methods: + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` - - com.mongodb.client.MongoCollection.updateOne_ + |populate-inventory| - - com.mongodb.client.MongoCollection.updateMany_ + .. tab:: + :tabid: java-sync - - com.mongodb.client.MongoCollection.replaceOne_ + This page uses the + following `Java Synchronous Driver`_ methods: - |populate-inventory| + - com.mongodb.client.MongoCollection.updateOne_ - - id: java-async - content: | - This page uses the - following `Java Reactive Streams Driver - `_ methods: + - com.mongodb.client.MongoCollection.updateMany_ - - `com.mongodb.reactivestreams.client.MongoCollection.updateOne - `_ + - com.mongodb.client.MongoCollection.replaceOne_ - - `com.mongodb.reactivestreams.client.MongoCollection.updateMany - `_ + |populate-inventory| - - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne - `_ + .. tab:: + :tabid: java-async - |populate-inventory| + This page uses the + following `Java Reactive Streams Driver + `_ methods: - - id: nodejs - content: | - This page uses the - following :node-docs:`MongoDB Node.js Driver <>` methods: + - `com.mongodb.reactivestreams.client.MongoCollection.updateOne + `_ - - :node-api:`Collection.updateOne() ` + - `com.mongodb.reactivestreams.client.MongoCollection.updateMany + `_ - - :node-api:`Collection.updateMany() ` + - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne + `_ - - :node-api:`Collection.replaceOne() ` + |populate-inventory| - |populate-inventory| + .. tab:: + :tabid: nodejs - - id: php - content: | - This page uses the - following `MongoDB PHP Library `_ methods: + This page uses the + following :node-docs:`MongoDB Node.js Driver <>` methods: - - :phpmethod:`MongoDB\\Collection::updateOne() ` + - :node-api:`Collection.updateOne() ` - - :phpmethod:`MongoDB\\Collection::updateMany() ` + - :node-api:`Collection.updateMany() ` - - :phpmethod:`MongoDB\\Collection::replaceOne() ` + - :node-api:`Collection.replaceOne() ` - |populate-inventory| + |populate-inventory| - - id: perl - content: | - This page uses the - following `MongoDB Perl Driver `_ methods: + .. tab:: + :tabid: php - - :perl-api:`MongoDB::Collection::update_one()` + This page uses the following `MongoDB PHP Library + `_ methods: - - :perl-api:`MongoDB::Collection::update_many()` + - :phpmethod:`MongoDB\\Collection::updateOne() ` - - :perl-api:`MongoDB::Collection::replace_one()` + - :phpmethod:`MongoDB\\Collection::updateMany() ` - |populate-inventory| + - :phpmethod:`MongoDB\\Collection::replaceOne() ` - - id: ruby - content: | - This page uses the - following `MongoDB Ruby Driver `_ methods: + |populate-inventory| - - :ruby-api:`Mongo::Collection#update_one()` + .. tab:: + :tabid: perl - - :ruby-api:`Mongo::Collection#update_many()` + This page uses the following `MongoDB Perl Driver + `_ methods: - - :ruby-api:`Mongo::Collection#replace_one()` + - :perl-api:`MongoDB::Collection::update_one()` - |populate-inventory| + - :perl-api:`MongoDB::Collection::update_many()` - - id: scala - content: | - This page uses the - following `MongoDB Scala Driver `_ methods: + - :perl-api:`MongoDB::Collection::replace_one()` - - :scala-api:`collection.updateOne()` + |populate-inventory| - - :scala-api:`collection.updateMany()` + .. tab:: + :tabid: ruby - - :scala-api:`collection.replaceOne()` + This page uses the following `MongoDB Ruby Driver + `_ methods: - |populate-inventory| + - :ruby-api:`Mongo::Collection#update_one()` - - id: csharp - content: | - This page uses the - following `MongoDB C# Driver `_ methods: + - :ruby-api:`Mongo::Collection#update_many()` - - :csharp-api:`IMongoCollection.UpdateOne()` + - :ruby-api:`Mongo::Collection#replace_one()` - - :csharp-api:`IMongoCollection.UpdateMany()` + |populate-inventory| - - :csharp-api:`IMongoCollection.ReplaceOne() ` + .. tab:: + :tabid: scala - |populate-inventory| + This page uses the following `MongoDB Scala Driver + `_ methods: - - id: go - content: | - This page uses the - following `MongoDB Go Driver `_ functions: + - :scala-api:`collection.updateOne()` - - :go-api:`Collection.UpdateOne` + - :scala-api:`collection.updateMany()` - - :go-api:`Collection.UpdateMany` + - :scala-api:`collection.replaceOne()` - - :go-api:`Collection.ReplaceOne ` + |populate-inventory| + + .. tab:: + :tabid: csharp + + This page uses the following `MongoDB C# Driver + `_ methods: + + - :csharp-api:`IMongoCollection.UpdateOne()` + + - :csharp-api:`IMongoCollection.UpdateMany()` + + - :csharp-api:`IMongoCollection.ReplaceOne() ` + + |populate-inventory| + + .. tab:: + :tabid: go + + This page uses the following `MongoDB Go Driver + `_ functions: + + - :go-api:`Collection.UpdateOne` - |populate-inventory| + - :go-api:`Collection.UpdateMany` + + - :go-api:`Collection.ReplaceOne ` + + |populate-inventory| .. include:: /includes/driver-examples/driver-example-update-51.rst @@ -211,255 +222,264 @@ Update Documents in a Collection .. tabs-drivers:: - tabs: - - id: shell - content: | - To update a document, MongoDB provides - :manual:`update operators `, such - as :update:`$set`, to modify field values. + .. tab:: + :tabid: shell + + To update a document, MongoDB provides + :manual:`update operators `, such + as :update:`$set`, to modify field values. + + To use the update operators, pass to the update methods an + update document of the form: + + .. code-block:: javascript + + { + : { : , ... }, + : { : , ... }, + ... + } + + .. include:: /includes/fact-update-set-create-fields.rst + + .. tab:: + :tabid: compass + + To update a document in Compass, hover over the target + document and click the pencil icon: + + .. figure:: /images/compass-update-doc-button.png + :alt: Click edit document + + After clicking the pencil icon, the document enters edit mode: - To use the update operators, pass to the update methods an - update document of the form: + .. figure:: /images/compass-update-edit-mode.png + :alt: Document edit mode - .. code-block:: javascript + You can now change the this document by clicking the item you wish + to change and modifying the value. - { - : { : , ... }, - : { : , ... }, - ... - } + For detailed instructions on updating documents in Compass, + refer to the + :ref:`Compass documentation ` + or follow the :ref:`example ` below. - .. include:: /includes/fact-update-set-create-fields.rst + Once you are satisfied with your changes, click + :guilabel:`Update` to save the updated document. - - id: compass - content: | - To update a document in Compass, hover over the target - document and click the pencil icon: + Click :guilabel:`Cancel` to revert any modifications made to + the document and exit edit mode. - .. figure:: /images/compass-update-doc-button.png - :alt: Click edit document + .. tab:: + :tabid: python - After clicking the pencil icon, the document enters edit mode: + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. figure:: /images/compass-update-edit-mode.png - :alt: Document edit mode + To use the update operators, pass to the update methods an + update document of the form: - You can now change the this document by clicking the item you wish to - change and modifying the value. + .. code-block:: python - For detailed instructions on updating documents in Compass, - refer to the - :ref:`Compass documentation ` - or follow the :ref:`example ` below. + { + : { : , ... }, + : { : , ... }, + ... + } - Once you are satisfied with your changes, click - :guilabel:`Update` to save the updated document. + .. include:: /includes/fact-update-set-create-fields.rst - Click :guilabel:`Cancel` to revert any modifications made to - the document and exit edit mode. + .. tab:: + :tabid: motor - - id: python - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - To use the update operators, pass to the update methods an - update document of the form: + To use the update operators, pass to the update methods an + update document of the form: - .. code-block:: python + .. code-block:: python - { - : { : , ... }, - : { : , ... }, - ... - } + { + : { : , ... }, + : { : , ... }, + ... + } - .. include:: /includes/fact-update-set-create-fields.rst + .. include:: /includes/fact-update-set-create-fields.rst - - id: motor - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. tab:: + :tabid: java-sync - To use the update operators, pass to the update methods an - update document of the form: + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. code-block:: python + The driver provides the `com.mongodb.client.model.Updates + `__ + class to facilitate the creation of update documents. For example: - { - : { : , ... }, - : { : , ... }, - ... - } + .. code-block:: java - .. include:: /includes/fact-update-set-create-fields.rst + combine(set( , ), set(, ) ) - - id: java-sync - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + For a list of the update helpers, see + `com.mongodb.client.model.Updates + `__. - The driver provides the `com.mongodb.client.model.Updates `__ - class to facilitate the creation of update documents. For example: + .. include:: /includes/fact-update-set-create-fields.rst - .. code-block:: java + .. tab:: + :tabid: java-async - combine(set( , ), set(, ) ) + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - For a list of the update helpers, see `com.mongodb.client.model.Updates `__. + The driver provides the `com.mongodb.client.model.Updates + `__ + class to facilitate the creation of update documents. For example: - .. include:: /includes/fact-update-set-create-fields.rst + .. code-block:: java - - id: java-async - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + combine(set( , ), set(, ) ) - The driver provides the `com.mongodb.client.model.Updates `__ - class to facilitate the creation of update documents. For example: + For a list of the update helpers, see + `com.mongodb.client.model.Updates + `__. - .. code-block:: java + .. include:: /includes/fact-update-set-create-fields.rst - combine(set( , ), set(, ) ) + .. tab:: + :tabid: nodejs - For a list of the update helpers, see `com.mongodb.client.model.Updates `__. + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. include:: /includes/fact-update-set-create-fields.rst + To use the update operators, pass to the update methods an + update document of the form: - - id: nodejs - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. code-block:: javascript - To use the update operators, pass to the update methods an - update document of the form: + { + : { : , ... }, + : { : , ... }, + ... + } - .. code-block:: javascript + .. include:: /includes/fact-update-set-create-fields.rst - { - : { : , ... }, - : { : , ... }, - ... - } + .. tab:: + :tabid: php - .. include:: /includes/fact-update-set-create-fields.rst + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - - id: php - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + To use the update operators, pass to the update methods an + update document of the form: - To use the update operators, pass to the update methods an - update document of the form: + .. code-block:: php - .. code-block:: php + [ + => [ => , ... ], + => [ => , ... ], + ... + ] - [ - => [ => , ... ], - => [ => , ... ], - ... - ] + .. include:: /includes/fact-update-set-create-fields.rst - .. include:: /includes/fact-update-set-create-fields.rst + .. tab:: + :tabid: perl - - id: perl - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - To use the update operators, pass to the update methods an - update document of the form: + To use the update operators, pass to the update methods an + update document of the form: - .. code-block:: perl + .. code-block:: perl - { - => { => , ... }, - => { => , ... }, - ... - } + { + => { => , ... }, + => { => , ... }, + ... + } - .. include:: /includes/fact-update-set-create-fields.rst + .. include:: /includes/fact-update-set-create-fields.rst - - id: ruby - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. tab:: + :tabid: ruby - To use the update operators, pass to the update methods an - update document of the form: + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. code-block:: ruby + To use the update operators, pass to the update methods an + update document of the form: - { - => { => , ... }, - => { => , ... }, - ... - } + .. code-block:: ruby - .. include:: /includes/fact-update-set-create-fields.rst + { + => { => , ... }, + => { => , ... }, + ... + } - - id: csharp - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. include:: /includes/fact-update-set-create-fields.rst - To use the update operators, pass to the update methods an - update document of the form: + .. tab:: + :tabid: csharp - .. code-block:: c# + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - { - => { => , ... }, - => { => , ... }, - ... - } + To use the update operators, pass to the update methods an + update document of the form: - .. include:: /includes/fact-update-set-create-fields.rst + .. code-block:: c# - - id: scala - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + { + => { => , ... }, + => { => , ... }, + ... + } - To use the update operators, pass to the update methods an - update document of the form: + .. include:: /includes/fact-update-set-create-fields.rst - .. code-block:: scala + .. tab:: + :tabid: scala - ( - set (, ), - set (, ), - ... - ) + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. include:: /includes/fact-update-set-create-fields.rst + To use the update operators, pass to the update methods an + update document of the form: - - id: go - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. code-block:: scala - .. include:: /includes/fact-update-set-create-fields.rst + ( + set (, ), + set (, ), + ... + ) + .. include:: /includes/fact-update-set-create-fields.rst - - id: go - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. tab:: + :tabid: go - .. include:: /includes/fact-update-set-create-fields.rst + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. + + .. include:: /includes/fact-update-set-create-fields.rst .. note:: @@ -474,109 +494,122 @@ Update a Single Document .. tabs-drivers:: - tabs: - - id: shell - content: | - The following example uses the - :method:`db.collection.updateOne()` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: compass - content: | - The following example demonstrates using |compass| to modify - a single document where ``item: paper`` in the ``inventory`` - collection: - - .. note:: - - This example uses the Compass - :ref:`Table View ` to modify the - document. The editing process using the Compass - :ref:`List View ` follows a very - similar approach. - - For more information on the differences between Table View - and List View in Compass, refer to the - :ref:`Compass documentation `. - - - id: python - content: | - The following example uses the - :py:meth:`~pymongo.collection.Collection.update_one` method on - the ``inventory`` collection to update the *first* document - where ``item`` equals ``"paper"``: - - - id: motor - content: | - The following example uses the - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one` method on - the ``inventory`` collection to update the *first* document - where ``item`` equals ``"paper"``: - - - id: java-sync - content: | - The following example uses the - com.mongodb.client.MongoCollection.updateOne_ method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: java-async - content: | - The following example uses the - `com.mongodb.reactivestreams.client.MongoCollection.updateOne - `_ - on the ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: nodejs - content: | - The following example uses the - :node-api:`Collection.updateOne() ` - method on the ``inventory`` collection to update the *first* - document where ``item`` equals ``"paper"``: - - - id: php - content: | - The following example uses the - :phpmethod:`updateOne() ` - method on the ``inventory`` collection to update the *first* - document where ``item`` equals ``"paper"``: - - - id: perl - content: | - The following example uses the - :perl-api:`update_one()` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: ruby - content: | - The following example uses the - :ruby-api:`update_one()` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: scala - content: | - The following example uses the - :scala-api:`updateOne()` - method on the ``inventory`` collection to update the *first* - document where ``item`` equals ``"paper"``: - - - id: csharp - content: | - The following example uses the - :csharp-api:`IMongoCollection.UpdateOne() ` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: go - content: | - The following example uses the - :go-api:`Collection.UpdateOne` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: + .. tab:: + :tabid: shell + + The following example uses the + :method:`db.collection.updateOne()` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: compass + + The following example demonstrates using |compass| to modify + a single document where ``item: paper`` in the ``inventory`` + collection: + + .. note:: + + This example uses the Compass + :ref:`Table View ` to modify the + document. The editing process using the Compass + :ref:`List View ` follows a very + similar approach. + + For more information on the differences between Table View + and List View in Compass, refer to the + :ref:`Compass documentation `. + + .. tab:: + :tabid: python + + The following example uses the + :py:meth:`~pymongo.collection.Collection.update_one` method on + the ``inventory`` collection to update the *first* document + where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: motor + + The following example uses the + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: java-sync + + The following example uses the + com.mongodb.client.MongoCollection.updateOne_ method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: java-async + + The following example uses the + `com.mongodb.reactivestreams.client.MongoCollection.updateOne + `_ + on the ``inventory`` collection to update the *first* document + where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: nodejs + + The following example uses the + :node-api:`Collection.updateOne() ` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: php + + The following example uses the :phpmethod:`updateOne() + ` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: perl + + The following example uses the + :perl-api:`update_one()` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: ruby + + The following example uses the + :ruby-api:`update_one()` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: scala + + The following example uses the + :scala-api:`updateOne()` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: csharp + + The following example uses the + :csharp-api:`IMongoCollection.UpdateOne() + ` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: go + + The following example uses the + :go-api:`Collection.UpdateOne` method + on the ``inventory`` collection to update the *first* document + where ``item`` equals ``"paper"``: .. include:: /includes/driver-examples/driver-example-update-52.rst @@ -585,272 +618,303 @@ Update a Single Document .. tabs-drivers:: - tabs: - - id: shell - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. versionadded:: 3.2 - - The following example uses the :method:`db.collection.updateMany()` - method on the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: python - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. versionadded:: 3.2 - - The following example uses the - :py:meth:`~pymongo.collection.Collection.update_many` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: motor - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. versionadded:: 3.2 - - The following example uses the - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: java-sync - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - com.mongodb.client.MongoCollection.updateMany_ method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: java-async - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - `com.mongodb.reactivestreams.client.MongoCollection.updateMany - `_ - method on the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: nodejs - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :node-api:`Collection.updateMany() ` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: php - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :phpmethod:`updateMany() ` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: perl - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :perl-api:`update_many()` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: ruby - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :ruby-api:`update_many()` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: scala - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :scala-api:`updateMany()` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: csharp - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :csharp-api:`IMongoCollection.UpdateMany() ` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: go - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :go-api:`Collection.UpdateMany` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: + .. tab:: + :tabid: compass + + .. tab:: + :tabid: shell + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. versionadded:: 3.2 + + The following example uses the + :method:`db.collection.updateMany()` method on the ``inventory`` + collection to update all documents where ``qty`` is less than + ``50``: + + .. tab:: + :tabid: python + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. versionadded:: 3.2 + + The following example uses the + :py:meth:`~pymongo.collection.Collection.update_many` method on + the ``inventory`` collection to update all documents where ``qty`` + is less than ``50``: + + .. tab:: + :tabid: motor + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. versionadded:: 3.2 + + The following example uses the + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: java-sync + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + com.mongodb.client.MongoCollection.updateMany_ method on + the ``inventory`` collection to update all documents where + ``qty`` is less than ``50``: + + .. tab:: + :tabid: java-async + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + `com.mongodb.reactivestreams.client.MongoCollection.updateMany + `_ + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: nodejs + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the :node-api:`Collection.updateMany() + ` method on the ``inventory`` + collection to update all documents where ``qty`` is less than + ``50``: + + .. tab:: + :tabid: php + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the :phpmethod:`updateMany() + ` method on the + ``inventory`` collection to update all documents where ``qty`` is + less than ``50``: + + .. tab:: + :tabid: perl + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :perl-api:`update_many()` method on the + ``inventory`` collection to update all documents where ``qty`` is + less than ``50``: + + .. tab:: + :tabid: ruby + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :ruby-api:`update_many()` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: scala + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :scala-api:`updateMany()` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: csharp + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :csharp-api:`IMongoCollection.UpdateMany() + ` method on the + ``inventory`` collection to update all documents where ``qty`` is + less than ``50``: + + .. tab:: + :tabid: go + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :go-api:`Collection.UpdateMany` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: .. include:: /includes/driver-examples/driver-example-update-53.rst .. tabs-drivers:: - tabs: - - id: shell - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: compass - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :method:`db.collection.replaceOne()`. + .. tab:: + :tabid: shell - .. include:: /includes/fact-update-replace-example.rst + Replace a Document + ------------------ - - id: python - content: | - Replace a Document - ------------------ + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :method:`db.collection.replaceOne()`. - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :py:meth:`~pymongo.collection.Collection.replace_one`. + .. include:: /includes/fact-update-replace-example.rst - .. include:: /includes/fact-update-replace-example.rst + .. tab:: + :tabid: python - - id: motor - content: | - Replace a Document - ------------------ + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one`. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :py:meth:`~pymongo.collection.Collection.replace_one`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: java-sync - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: motor + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - com.mongodb.client.MongoCollection.replaceOne_. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: java-async - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: java-sync + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne - `_. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + com.mongodb.client.MongoCollection.replaceOne_. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: nodejs - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: java-async + + Replace a Document + ------------------ - To replace the entire content of a document except for the - ``_id`` field, pass an entirely new document as the second - argument to - :node-api:`Collection.replaceOne() `. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + `com.mongodb.reactivestreams.client.MongoCollection.replaceOne + `_. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: php - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: nodejs + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :phpmethod:`replaceOne() `. + To replace the entire content of a document except for the + ``_id`` field, pass an entirely new document as the second + argument to + :node-api:`Collection.replaceOne() `. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: perl - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: php + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :perl-api:`replace_one()`. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :phpmethod:`replaceOne() + `. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: ruby - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: perl + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :ruby-api:`replace_one()`. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :perl-api:`replace_one()`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: scala - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: ruby + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :scala-api:`replaceOne()` + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :ruby-api:`replace_one()`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: csharp - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: scala + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :csharp-api:`IMongoCollection.ReplaceOne() - `. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :scala-api:`replaceOne()` - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: go - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: csharp + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :go-api:`Collection.ReplaceOne `. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :csharp-api:`IMongoCollection.ReplaceOne() + `. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst + + .. tab:: + :tabid: go + + Replace a Document + ------------------ + + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :go-api:`Collection.ReplaceOne `. + + .. include:: /includes/fact-update-replace-example.rst .. include:: /includes/driver-examples/driver-example-update-54.rst @@ -880,198 +944,227 @@ Field Order .. tabs-drivers:: - tabs: - - id: shell - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :method:`~db.collection.updateOne()`, - :method:`~db.collection.updateMany()`, or - :method:`~db.collection.replaceOne()` includes ``upsert : true`` **and** - no documents match the specified filter, then the operation creates a - new document and inserts it. If there are matching documents, then the - operation modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: python - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :py:meth:`~pymongo.collection.Collection.update_one`, - :py:meth:`~pymongo.collection.Collection.update_many`, or - :py:meth:`~pymongo.collection.Collection.replace_one` includes - ``upsert : true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: motor - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one`, - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many`, or - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one` includes - ``upsert : true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: java-sync - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If the update and replace methods include the - com.mongodb.client.model.UpdateOptions_ parameter that - specifies `com.mongodb.client.model.UpdateOptions.upsert(true)`_ - **and** no documents match the specified filter, then the - operation creates a new document and inserts it. If there are - matching documents, then the operation modifies or replaces - the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: java-async - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If the update and replace methods include the - `UpdateOptions `_ - parameter that specifies `UpdateOptions.upsert(true) `_ - **and** no documents match the specified filter, then the - operation creates a new document and inserts it. If there are - matching documents, then the operation modifies or replaces - the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: nodejs - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :node-api:`updateOne() `, - :node-api:`updateMany() `, or - :node-api:`replaceOne() ` include - ``upsert : true`` in the ``options`` parameter document **and** - no documents match the specified filter, then the operation - creates a new document and inserts it. If there are matching - documents, then the operation modifies or replaces the matching - document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: php - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :phpmethod:`updateOne() `, - :phpmethod:`updateMany() `, - or :phpmethod:`replaceOne() ` - includes ``upsert => true`` **and** no documents match the - specified filter, then the operation creates a new document and - inserts it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: perl - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :perl-api:`update_one()`, - :perl-api:`update_many()`, or - :perl-api:`replace_one()` includes - ``upsert => true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: ruby - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :ruby-api:`update_one()`, - :ruby-api:`update_many()`, or - :ruby-api:`replace_one()` includes - ``upsert => true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: scala - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :scala-api:`updateOne()`, :scala-api:`updateMany()`, or :scala-api:`replaceOne()` - includes ``upsert => true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts it. If - there are matching documents, then the operation modifies or replaces - the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: csharp - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :csharp-api:`UpdateOne() `, - :csharp-api:`UpdateMany() `, or - :csharp-api:`ReplaceOne() ` - includes an :csharp-api:`UpdateOptions ` - argument instance with the ``IsUpsert`` option set to ``true`` - **and** no documents match the specified filter, then the - operation creates a new document and inserts it. If there are - matching documents, then the operation modifies or replaces the - matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: go - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :go-api:`Collection.UpdateOne` - includes the :go-api:`Upsert option set to true - ` **and** no documents match the - specified filter, then the operation creates a new document - and inserts it. If there are matching documents, then the - operation modifies or replaces the matching document or - documents. - - For details on the new document created, see the individual reference - pages for the methods. + .. tab:: + :tabid: compass + + .. tab:: + :tabid: shell + + Upsert Option + ~~~~~~~~~~~~~ + + If :method:`~db.collection.updateOne()`, + :method:`~db.collection.updateMany()`, or + :method:`~db.collection.replaceOne()` includes ``upsert : true`` + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: python + + Upsert Option + ~~~~~~~~~~~~~ + + If :py:meth:`~pymongo.collection.Collection.update_one`, + :py:meth:`~pymongo.collection.Collection.update_many`, or + :py:meth:`~pymongo.collection.Collection.replace_one` includes + ``upsert : true`` **and** no documents match the specified + filter, then the operation creates a new document and inserts + it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual reference + pages for the methods. + + .. tab:: + :tabid: motor + + Upsert Option + ~~~~~~~~~~~~~ + + If + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one`, + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many`, + or + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one` + includes ``upsert : true`` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: java-sync + + Upsert Option + ~~~~~~~~~~~~~ + + If the update and replace methods include the + com.mongodb.client.model.UpdateOptions_ parameter that + specifies `com.mongodb.client.model.UpdateOptions.upsert(true)`_ + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces + the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: java-async + + Upsert Option + ~~~~~~~~~~~~~ + + If the update and replace methods include the `UpdateOptions + `_ + parameter that specifies `UpdateOptions.upsert(true) + `_ + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: nodejs + + Upsert Option + ~~~~~~~~~~~~~ + + If :node-api:`updateOne() `, + :node-api:`updateMany() `, or + :node-api:`replaceOne() ` include + ``upsert : true`` in the ``options`` parameter document **and** + no documents match the specified filter, then the operation + creates a new document and inserts it. If there are matching + documents, then the operation modifies or replaces the matching + document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: php + + Upsert Option + ~~~~~~~~~~~~~ + + If :phpmethod:`updateOne() + `, + :phpmethod:`updateMany() + `, or + :phpmethod:`replaceOne() + ` includes ``upsert => + true`` **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: perl + + Upsert Option + ~~~~~~~~~~~~~ + + If :perl-api:`update_one()`, + :perl-api:`update_many()`, or + :perl-api:`replace_one()` includes + ``upsert => true`` **and** no documents match the specified + filter, then the operation creates a new document and inserts + it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: ruby + + Upsert Option + ~~~~~~~~~~~~~ + + If + :ruby-api:`update_one()`, + :ruby-api:`update_many()`, + or + :ruby-api:`replace_one()` + includes ``upsert => true`` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: scala + + Upsert Option + ~~~~~~~~~~~~~ + + If + :scala-api:`updateOne()`, + :scala-api:`updateMany()`, + or + :scala-api:`replaceOne()` + includes ``upsert => true`` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: csharp + + Upsert Option + ~~~~~~~~~~~~~ + + If :csharp-api:`UpdateOne() + `, + :csharp-api:`UpdateMany() + `, or + :csharp-api:`ReplaceOne() + ` includes an + :csharp-api:`UpdateOptions ` + argument instance with the ``IsUpsert`` option set to ``true`` + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: go + + Upsert Option + ~~~~~~~~~~~~~ + + If :go-api:`Collection.UpdateOne` + includes the :go-api:`Upsert option set to true + ` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. Write Acknowledgement ~~~~~~~~~~~~~~~~~~~~~ @@ -1082,164 +1175,173 @@ requested from MongoDB for write operations. For details, see .. tabs-drivers:: - tabs: - - id: shell - content: | + .. tab:: + :tabid: shell - .. seealso:: + .. seealso:: - - :doc:`/tutorial/update-documents-with-aggregation-pipeline` + - :doc:`/tutorial/update-documents-with-aggregation-pipeline` - - :method:`db.collection.updateOne()` + - :method:`db.collection.updateOne()` + + - :method:`db.collection.updateMany()` + + - :method:`db.collection.replaceOne()` - - :method:`db.collection.updateMany()` + - :ref:`additional-updates` - - :method:`db.collection.replaceOne()` + .. tab:: + :tabid: compass - - :ref:`additional-updates` + .. seealso:: - - id: compass - content: | - .. seealso:: + - `Compass Documents `_ - - `Compass Documents `_ + - :ref:`Compass Query Bar ` - - :ref:`Compass Query Bar ` + .. tab:: + :tabid: python - - id: python - content: | - .. seealso:: + .. seealso:: - - :py:meth:`pymongo.collection.Collection.update_one` + - :py:meth:`pymongo.collection.Collection.update_one` - - :py:meth:`pymongo.collection.Collection.update_many` + - :py:meth:`pymongo.collection.Collection.update_many` - - :py:meth:`pymongo.collection.Collection.replace_one` + - :py:meth:`pymongo.collection.Collection.replace_one` - - :ref:`additional-updates` + - :ref:`additional-updates` - - id: motor - content: | - .. seealso:: + .. tab:: + :tabid: motor - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` + .. seealso:: - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` - - :ref:`additional-updates` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` - - id: java-sync - content: | + - :ref:`additional-updates` - .. seealso:: + .. tab:: + :tabid: java-sync + + .. seealso:: + + - com.mongodb.client.MongoCollection.updateOne_ + + - com.mongodb.client.MongoCollection.updateMany_ - - com.mongodb.client.MongoCollection.updateOne_ + - com.mongodb.client.MongoCollection.replaceOne_ + + - `Additional Java Synchronous Driver Write Examples`_ + + .. tab:: + :tabid: java-async + + .. seealso:: + + - `com.mongodb.reactivestreams.client.MongoCollection.updateOne + `_ + + - `com.mongodb.reactivestreams.client.MongoCollection.updateMany + `_ - - com.mongodb.client.MongoCollection.updateMany_ + - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne + `_ - - com.mongodb.client.MongoCollection.replaceOne_ + - `Java Reactive Streams Driver Quick Tour `_ - - `Additional Java Synchronous Driver Write Examples`_ + .. tab:: + :tabid: nodejs - - id: java-async - content: | + .. seealso:: - .. seealso:: + - :node-api:`Collection.updateOne() ` - - `com.mongodb.reactivestreams.client.MongoCollection.updateOne - `_ + - :node-api:`Collection.updateMany() ` - - `com.mongodb.reactivestreams.client.MongoCollection.updateMany - `_ + - :node-api:`Collection.replaceOne() ` - - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne - `_ + - :ref:`additional-updates` - - `Java Reactive Streams Driver Quick Tour `_ + .. tab:: + :tabid: php - - id: nodejs - content: | - .. seealso:: + .. seealso:: - - :node-api:`Collection.updateOne() ` + - :phpmethod:`MongoDB\\Collection::updateOne() ` - - :node-api:`Collection.updateMany() ` + - :phpmethod:`MongoDB\\Collection::updateMany() ` - - :node-api:`Collection.replaceOne() ` + - :phpmethod:`MongoDB\\Collection::replaceOne() ` - - :ref:`additional-updates` + - :ref:`additional-updates` - - id: php - content: | - .. seealso:: + .. tab:: + :tabid: perl - - :phpmethod:`MongoDB\\Collection::updateOne() ` + .. seealso:: - - :phpmethod:`MongoDB\\Collection::updateMany() ` + - :perl-api:`MongoDB::Collection::update_one()` - - :phpmethod:`MongoDB\\Collection::replaceOne() ` + - :perl-api:`MongoDB::Collection::update_many()` - - :ref:`additional-updates` + - :perl-api:`MongoDB::Collection::replace_one()` - - id: perl - content: | - .. seealso:: + - :ref:`additional-updates` - - :perl-api:`MongoDB::Collection::update_one()` + .. tab:: + :tabid: ruby - - :perl-api:`MongoDB::Collection::update_many()` + .. seealso:: - - :perl-api:`MongoDB::Collection::replace_one()` + - :ruby-api:`Mongo::Collection#update_one()` - - :ref:`additional-updates` + - :ruby-api:`Mongo::Collection#update_many()` - - id: ruby - content: | - .. seealso:: + - :ruby-api:`Mongo::Collection#replace_one()` - - :ruby-api:`Mongo::Collection#update_one()` + .. tab:: + :tabid: scala - - :ruby-api:`Mongo::Collection#update_many()` + .. seealso:: - - :ruby-api:`Mongo::Collection#replace_one()` + - :scala-api:`collection.updateOne()` - - id: scala - content: | - .. seealso:: + - :scala-api:`collection.updateMany()` - - :scala-api:`collection.updateOne()` + - :scala-api:`collection.replaceOne()` - - :scala-api:`collection.updateMany()` + - :ref:`additional-updates` - - :scala-api:`collection.replaceOne()` + .. tab:: + :tabid: csharp - - :ref:`additional-updates` + .. seealso:: - - id: csharp - content: | - .. seealso:: + - :csharp-api:`IMongoCollection.UpdateOne() ` - - :csharp-api:`IMongoCollection.UpdateOne() ` + - :csharp-api:`IMongoCollection.UpdateMany() ` - - :csharp-api:`IMongoCollection.UpdateMany() ` + - :csharp-api:`IMongoCollection.ReplaceOne() ` - - :csharp-api:`IMongoCollection.ReplaceOne() ` + - :ref:`additional-updates` - - :ref:`additional-updates` + .. tab:: + :tabid: go - - id: go - content: | - .. seealso:: + .. seealso:: - - :go-api:`Collection.UpdateOne` + - :go-api:`Collection.UpdateOne` - - :go-api:`Collection.UpdateMany` + - :go-api:`Collection.UpdateMany` - - :go-api:`Collection.ReplaceOne ` + - :go-api:`Collection.ReplaceOne ` - - :ref:`additional-updates` + - :ref:`additional-updates` .. toctree:: :titlesonly: