Skip to content

DOCS-5167: Move 3.0 dot notation change example out of API reference #2283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ description: |
.. include:: /includes/fact-mongodb30-upsert-id.rst
For an example, see :ref:`mongodb30-upsert-id`.
interface: method
name: query
operation: db.collection.update
Expand Down
10 changes: 10 additions & 0 deletions source/includes/fact-mongodb30-upsert-id-example.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
For example, consider the following update operation. Since the update
operation specifies ``upsert:true`` and the query specifies conditions on the
``_id`` field using dot notation, then the update will result in an error when
constructing the document to insert.

.. code-block:: javascript
db.collection.update( { "_id.name": "Robert Frost", "_id.uid": 0 },
{ "categories": ["poet", "playwright"] },
{ upsert: true } )
14 changes: 7 additions & 7 deletions source/includes/fact-mongodb30-upsert-id.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
When you execute an :method:`~db.collection.update()` with the ``upsert``
option, you can no longer use :ref:`document-dot-notation` to select only on
part of the ``_id`` field. For example, the following will raise an error:
When you execute an :method:`~db.collection.update()` with ``upsert: true`` and
the query matches no existing document, MongoDB will refuse to insert a new
document if the query specifies conditions on the ``_id`` field using
:ref:`dot notation <document-dot-notation>`.

.. code-block:: javascript
This restriction ensures that the order of fields embedded in the ``_id``
document is well-defined and not bound to the order specified in the query

db.collection.update( { "_id.authorID": 1 },
{ "name": "Robert Frost" },
{ upsert: true } )
If you attempt to insert a document in this way, MongoDB will raise an error.
10 changes: 10 additions & 0 deletions source/reference/method/db.collection.update.txt
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,16 @@ The remaining operations would either:
applications may retry the operation which will succeed as an update
operation.

.. _mongodb30-upsert-id:

``upsert:true`` with a Dotted ``_id`` Query
```````````````````````````````````````````

.. include:: /includes/fact-mongodb30-upsert-id.rst

.. include:: /includes/fact-mongodb30-upsert-id-example.rst


.. _multi-parameter:

Multi Parameter
Expand Down
2 changes: 2 additions & 0 deletions source/release-notes/3.0-compatibility.txt
Original file line number Diff line number Diff line change
Expand Up @@ -458,6 +458,8 @@ General Compatibility Changes

.. include:: /includes/fact-mongodb30-upsert-id.rst

.. include:: /includes/fact-mongodb30-upsert-id-example.rst

Deprecate Access to ``system.indexes`` and ``system.namespaces``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down