Skip to content

DOCS-800 added dot notation documentation #433

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Nov 30, 2012
Merged

DOCS-800 added dot notation documentation #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ab47d24
DOCS-800 added dot notation documentation
kay-kim Nov 28, 2012
cbd983a
DOCS-800 dot-notation edits
kay-kim Nov 28, 2012
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
61 changes: 38 additions & 23 deletions source/applications/read.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ Consider the following examples that illustrate the use of the

- The following operation returns all documents in the ``bios``
collection where the array field ``contribs`` contains the element
``UNIX``:
``'UNIX'``:

.. code-block:: javascript

Expand All @@ -135,11 +135,30 @@ Consider the following examples that illustrate the use of the
contribs: 'UNIX'
}
)

- The following operation returns all documents in the ``bios``
collection where ``awards`` array contains a subdocument element
that contains the ``award`` field equal to ``'Turing Award'`` and the
``year`` field greater than 1980:

.. code-block:: javascript

db.bios.find(
{
awards: {
$elemMatch: {
award: 'Turing Award',
year: { $gt: 1980 }
}
}
}
)

- The following operation returns all documents in the ``bios``
collection where the subdocument ``name`` contains a field
``first`` with the value ``Yukihiro`` and a field ``last`` with the
value ``Matsumoto``:
``first`` with the value ``'Yukihiro'`` and a field ``last`` with
the value ``'Matsumoto'``; the query uses :term:`dot notation` to
access fields in a subdocument:

.. code-block:: javascript

Expand All @@ -151,8 +170,8 @@ Consider the following examples that illustrate the use of the
)

The query matches the document where the ``name`` field contains a
subdocument with the field ``first`` with the value ``Yukihiro``
and a field ``last`` with the value ``Matsumoto``. For instance,
subdocument with the field ``first`` with the value ``'Yukihiro'``
and a field ``last`` with the value ``'Matsumoto'``. For instance,
the query would match documents with ``name`` fields that
held either of the following values:

Expand Down Expand Up @@ -230,23 +249,10 @@ Consider the following examples that illustrate the use of the
}
)

- The following operation returns all documents in the ``bios``
collection where ``awards`` array contains a subdocument element
that contains the ``award`` field equal to ``Turing Award`` and the
``year`` field greater than 1980:

.. code-block:: javascript

db.bios.find(
{
awards: {
$elemMatch: {
award: 'Turing Award',
year: { $gt: 1980 }
}
}
}
)
The query uses the comma to specify the logical AND for criteria on
different fields ``contribs`` and ``name.first``. For multiple AND
criteria on the same field, use the :operator:`$and` operator
instead of the comma.

- If there is a ``<projection>`` argument, the :method:`find()
<db.collection.find()>` method returns only those fields as specified
Expand Down Expand Up @@ -282,7 +288,7 @@ Consider the following examples that illustrate the use of the

- The following operation finds the documents in the ``bios``
collection where the ``contribs`` field contains the element
``OOP`` and returns all fields *except* the ``_id`` field, the
``'OOP'`` and returns all fields *except* the ``_id`` field, the
``first`` field in the ``name`` subdocument, and the ``birth``
field from the matching documents:

Expand All @@ -308,6 +314,15 @@ Consider the following examples that illustrate the use of the
}
)

.. seealso::

- :term:`dot notation` for information on dot notation

- :ref:`read-operations-arrays` for more examples on accessing arrays

- :ref:`read-operations-subdocuments` for more examples on accessing
subdocuments

Cursor
~~~~~~

Expand Down
10 changes: 5 additions & 5 deletions source/applications/update.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,8 @@ Consider the following examples that illustrate the use of the
- If the ``<update>`` argument contains only :ref:`update operator
<update-operators>` expressions such as the :operator:`$set` operator
expression, the :method:`update() <db.collection.update()>` method
updates the corresponding fields in the document.
updates the corresponding fields in the document. To update fields in
subdocuments, MongoDB uses :term:`dot notation`.

The following operation queries the ``bios`` collection for the first
document that has an ``_id`` field equal to ``1`` and sets the field
Expand Down Expand Up @@ -161,8 +162,8 @@ Consider the following examples that illustrate the use of the
field:

- The :method:`update() <db.collection.update()>` method can perform
the update using the position of the element. Arrays in MongoDB are
zero-based.
the update using the position of the element and
:term:`dot notation`. Arrays in MongoDB are zero-based.

The following operation queries the ``bios`` collection for
the first document with ``_id`` field equal to ``1`` and updates the
Expand Down Expand Up @@ -196,8 +197,7 @@ Consider the following examples that illustrate the use of the

- The :method:`update() <db.collection.update()>` method can perform
the update of an array that contains subdocuments by using the
:operator:`$` positional operator and the :wiki:`dot notation
<Dot+Notation+(Reaching+into+Objects)>`.
positional operator (i.e. :operator:`$`) and the :term:`dot notation`.

The following operation queries the ``bios`` collection for the first
document where the ``_id`` field equals ``6`` and the ``awards``
Expand Down
127 changes: 72 additions & 55 deletions source/core/document.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,10 @@ the following structure:
fieldN: valueN
}

Having support for the full range of :term:`BSON types`, MongoDB
documents may contain field and value pairs where the value can be
another document, an array, an array of documents as well as the basic
types such as ``Double``, ``String``, and ``Date``. See also
Having support for the full range of BSON types, MongoDB documents may
contain field and value pairs where the value can be another document,
an array, an array of documents as well as the basic types such as
``Double``, ``String``, and ``Date``. See also
:ref:`document-bson-type-considerations`.

Consider the following document that contains values of varying types:
Expand All @@ -79,7 +79,7 @@ The document contains the following fields:

- ``_id`` that holds an *ObjectId*.

- ``name`` that holds a *sub-document* that contains the fields
- ``name`` that holds a *subdocument* that contains the fields
``first`` and ``last``.

- ``birth`` and ``death``, which both have *Date* types.
Expand All @@ -88,6 +88,11 @@ The document contains the following fields:

- ``views`` that holds a value of *NumberLong* type.

.. _document-type-operators:

Type Operators
~~~~~~~~~~~~~~

To determine the type of fields, the :program:`mongo` shell provides
the following operators:

Expand Down Expand Up @@ -119,6 +124,24 @@ the following operators:
In this case ``typeof`` will return the more generic ``object``
type rather than ``ObjectId`` type.

.. _document-dot-notation:

Dot Notation
~~~~~~~~~~~~

.. include:: /includes/fact-dot-notation.rst

.. seealso::

- :ref:`read-operations-subdocuments` for dot notation examples
with subdocuments.

- :ref:`read-operations-arrays` for dot notation examples with
arrays.

- :ref:`read-operations-arrays-of-subdocuments` for dot notation
examples with arrays of subdocuments.

Document Types in MongoDB
-------------------------

Expand Down Expand Up @@ -215,44 +238,10 @@ Query Specification Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Query documents specify the conditions that determine which records to
select for read, update, and delete operations. You can use field and
value expressions to specify the equality condition and :doc:`query
operator </reference/operators>` expressions to specify additional
conditions. Refer to :doc:`read </applications/read>`, :doc:`update
</applications/update>`, and :doc:`delete </applications/delete>` pages
for more examples.

Consider the following examples of query documents:

- The following document specifies the query criteria where ``_id`` is
equal to ``1``:

.. code-block:: javascript

{ _id: 1 }

- The following document specifies the query criteria where ``_id`` is
greater than ``3``:

.. code-block:: javascript

{ _id: { $gt: 3 } }

- The following document specifies the compound query criteria where
``_id`` is equal to ``1`` **and** the ``name`` field equals the
document ``{ first: 'John', last: 'Backus' }``:

.. code-block:: javascript

{ _id: 1, name: { first: 'John', last: 'Backus' } }

- The following document specifies the compound query criteria where
``_id`` is equal to ``1`` **or** the ``name`` field equals the
document ``{ first: 'John', last: 'Backus' }``:

.. code-block:: javascript

{ $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] }
select for read, update, and delete operations. You can use
``<field>:<value>`` expressions to specify the equality condition and
:doc:`query operator </reference/operators>` expressions to specify
additional conditions.

When passed as an argument to methods such as the :method:`find()
<db.collection.find()>` method, the :method:`remove()
Expand All @@ -265,7 +254,20 @@ for MongoDB to return, remove, or update, as in the following:
db.bios.find( { _id: 1 } )
db.bios.remove( { _id: { $gt: 3 } } )
db.bios.update( { _id: 1, name: { first: 'John', last: 'Backus' } },
... )
<update>,
<options> )

.. seealso::

- :ref:`read-operations-query-argument` and
:doc:`/applications/read` for more examples on selecting documents
for reads.

- :doc:`/applications/update` for more examples on
selecting documents for updates.

- :doc:`/applications/delete` for more examples on selecting
documents for deletes.

.. _documents-update-actions:

Expand All @@ -276,14 +278,14 @@ Update documents specify the data modifications to perform during
an :method:`update() <db.collection.update()>` operation to modify
existing records in a collection. You can use :ref:`update operators
<update-operators>` to specify the exact actions to perform on the
document fields. See the :ref:`update operators <update-operators>`
page for the available update operators and syntax.
document fields.

Consider the update document example:

.. code-block:: javascript

{ $set: { 'name.middle': 'Warner' },
{
$set: { 'name.middle': 'Warner' },
$push: { awards: { award: 'IBM Fellow',
year: '1963',
by: 'IBM' }
Expand All @@ -295,7 +297,8 @@ When passed as an argument to the :method:`update()

- Modifies the field ``name`` whose value is another document.
Specifically, the :operator:`$set` operator updates the ``middle``
field in the ``name`` subdocument.
field in the ``name`` subdocument. The document uses :ref:`dot
notation <document-dot-notation>` to access a field in a subdocument.

- Adds an element to the field ``awards`` whose value is an array.
Specifically, the :operator:`$push` operator adds another document as
Expand All @@ -305,7 +308,8 @@ When passed as an argument to the :method:`update()

db.bios.update(
{ _id: 1 },
{ $set: { 'name.middle': 'Warner' },
{
$set: { 'name.middle': 'Warner' },
$push: { awards: {
award: 'IBM Fellow',
year: '1963',
Expand All @@ -315,6 +319,18 @@ When passed as an argument to the :method:`update()
}
)

.. seealso::

- :ref:`update operators <update-operators>` page for the available
update operators and syntax.

- :doc:`update </applications/update>` for more examples on
update documents.

For additional examples of updates that involve array elements,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think burrying the cross reference at the end of pargraphs like this is probably less than ideal, and is probably a little wordy.

including where the elements are documents, see the :operator:`$`
positional operator.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see the positional operatior (i.e. $)


.. _documents-index:
.. _document-index-specification:

Expand All @@ -335,9 +351,11 @@ Index documents contain field and value pairs, in the following form:

- ``value`` is either 1 for ascending or -1 for descending.

The following document specifies the :ref:`multi-key index <index-type-multi-key>` on the ``_id``
field and the ``last`` field contained in the subdocument ``name``
field:
The following document specifies the :ref:`multi-key index
<index-type-multi-key>` on the ``_id`` field and the ``last`` field
contained in the subdocument ``name`` field. The document uses
:ref:`dot notation <document-dot-notation>` to access a field in a
subdocument:

.. code-block:: javascript

Expand All @@ -355,7 +373,6 @@ the index to create:
</core/read-operations>` and :doc:`write </core/write-operations>`
operations.


.. _documents-sort-order:

Sort Order Specification Documents
Expand Down Expand Up @@ -397,8 +414,8 @@ method, the sort order document sorts the results of the
.. _document-mongodb-type-considerations:
.. _document-bson-type-considerations:

BSON Types
----------
BSON Type Considerations
------------------------

The following BSON types require special consideration:

Expand Down
Loading