From 8f4b0a2d8d63d46d46833e910869227cf7dc6707 Mon Sep 17 00:00:00 2001 From: jonathan Date: Wed, 5 Apr 2017 11:30:38 -0400 Subject: [PATCH] DOCSP-565 - Implemented tabbed layout on CRUD pages. Included Python examples. --- .gitignore | 1 + Makefile | 13 +- conf.py | 3 +- config/intersphinx.yaml | 4 + source/includes/driver-example-delete-55.rst | 32 +++ source/includes/driver-example-delete-56.rst | 20 ++ source/includes/driver-example-delete-57.rst | 20 ++ source/includes/driver-example-delete-58.rst | 20 ++ .../includes/driver-example-delete-result.rst | 15 ++ source/includes/driver-example-insert-1.rst | 28 +++ source/includes/driver-example-insert-2.rst | 20 ++ source/includes/driver-example-insert-3.rst | 30 +++ source/includes/driver-example-query-10.rst | 20 ++ source/includes/driver-example-query-11.rst | 21 ++ source/includes/driver-example-query-12.rst | 21 ++ source/includes/driver-example-query-13.rst | 24 ++ source/includes/driver-example-query-14.rst | 32 +++ source/includes/driver-example-query-15.rst | 20 ++ source/includes/driver-example-query-16.rst | 20 ++ source/includes/driver-example-query-17.rst | 20 ++ source/includes/driver-example-query-18.rst | 20 ++ source/includes/driver-example-query-19.rst | 20 ++ source/includes/driver-example-query-20.rst | 32 +++ source/includes/driver-example-query-21.rst | 20 ++ source/includes/driver-example-query-22.rst | 20 ++ source/includes/driver-example-query-23.rst | 20 ++ source/includes/driver-example-query-24.rst | 20 ++ source/includes/driver-example-query-25.rst | 20 ++ source/includes/driver-example-query-26.rst | 20 ++ source/includes/driver-example-query-27.rst | 20 ++ source/includes/driver-example-query-28.rst | 20 ++ source/includes/driver-example-query-29.rst | 32 +++ source/includes/driver-example-query-30.rst | 20 ++ source/includes/driver-example-query-31.rst | 20 ++ source/includes/driver-example-query-32.rst | 20 ++ source/includes/driver-example-query-33.rst | 20 ++ source/includes/driver-example-query-34.rst | 20 ++ source/includes/driver-example-query-35.rst | 20 ++ source/includes/driver-example-query-36.rst | 20 ++ source/includes/driver-example-query-37.rst | 20 ++ source/includes/driver-example-query-38.rst | 29 +++ source/includes/driver-example-query-39.rst | 20 ++ source/includes/driver-example-query-40.rst | 20 ++ source/includes/driver-example-query-41.rst | 20 ++ source/includes/driver-example-query-42.rst | 32 +++ source/includes/driver-example-query-43.rst | 20 ++ source/includes/driver-example-query-44.rst | 20 ++ source/includes/driver-example-query-45.rst | 20 ++ source/includes/driver-example-query-46.rst | 20 ++ source/includes/driver-example-query-47.rst | 23 ++ source/includes/driver-example-query-48.rst | 23 ++ source/includes/driver-example-query-49.rst | 20 ++ source/includes/driver-example-query-50.rst | 20 ++ source/includes/driver-example-query-6.rst | 32 +++ source/includes/driver-example-query-7.rst | 20 ++ source/includes/driver-example-query-9.rst | 20 ++ .../includes/driver-example-query-intro.rst | 22 ++ source/includes/driver-example-update-51.rst | 37 +++ source/includes/driver-example-update-52.rst | 26 +++ source/includes/driver-example-update-53.rst | 26 +++ source/includes/driver-example-update-54.rst | 23 ++ source/includes/templates/tabs.rst | 76 ++++++ source/tutorial/insert-documents.txt | 193 +++++++++------- .../project-fields-from-query-results.txt | 98 +++----- source/tutorial/query-array-of-documents.txt | 71 +----- source/tutorial/query-arrays.txt | 71 +----- source/tutorial/query-documents.txt | 162 ++++++------- source/tutorial/query-embedded-documents.txt | 53 +---- source/tutorial/query-for-null-fields.txt | 54 ++--- source/tutorial/remove-documents.txt | 158 +++++++------ source/tutorial/update-documents.txt | 216 ++++++++++-------- 71 files changed, 1863 insertions(+), 590 deletions(-) create mode 100644 source/includes/driver-example-delete-55.rst create mode 100644 source/includes/driver-example-delete-56.rst create mode 100644 source/includes/driver-example-delete-57.rst create mode 100644 source/includes/driver-example-delete-58.rst create mode 100644 source/includes/driver-example-delete-result.rst create mode 100644 source/includes/driver-example-insert-1.rst create mode 100644 source/includes/driver-example-insert-2.rst create mode 100644 source/includes/driver-example-insert-3.rst create mode 100644 source/includes/driver-example-query-10.rst create mode 100644 source/includes/driver-example-query-11.rst create mode 100644 source/includes/driver-example-query-12.rst create mode 100644 source/includes/driver-example-query-13.rst create mode 100644 source/includes/driver-example-query-14.rst create mode 100644 source/includes/driver-example-query-15.rst create mode 100644 source/includes/driver-example-query-16.rst create mode 100644 source/includes/driver-example-query-17.rst create mode 100644 source/includes/driver-example-query-18.rst create mode 100644 source/includes/driver-example-query-19.rst create mode 100644 source/includes/driver-example-query-20.rst create mode 100644 source/includes/driver-example-query-21.rst create mode 100644 source/includes/driver-example-query-22.rst create mode 100644 source/includes/driver-example-query-23.rst create mode 100644 source/includes/driver-example-query-24.rst create mode 100644 source/includes/driver-example-query-25.rst create mode 100644 source/includes/driver-example-query-26.rst create mode 100644 source/includes/driver-example-query-27.rst create mode 100644 source/includes/driver-example-query-28.rst create mode 100644 source/includes/driver-example-query-29.rst create mode 100644 source/includes/driver-example-query-30.rst create mode 100644 source/includes/driver-example-query-31.rst create mode 100644 source/includes/driver-example-query-32.rst create mode 100644 source/includes/driver-example-query-33.rst create mode 100644 source/includes/driver-example-query-34.rst create mode 100644 source/includes/driver-example-query-35.rst create mode 100644 source/includes/driver-example-query-36.rst create mode 100644 source/includes/driver-example-query-37.rst create mode 100644 source/includes/driver-example-query-38.rst create mode 100644 source/includes/driver-example-query-39.rst create mode 100644 source/includes/driver-example-query-40.rst create mode 100644 source/includes/driver-example-query-41.rst create mode 100644 source/includes/driver-example-query-42.rst create mode 100644 source/includes/driver-example-query-43.rst create mode 100644 source/includes/driver-example-query-44.rst create mode 100644 source/includes/driver-example-query-45.rst create mode 100644 source/includes/driver-example-query-46.rst create mode 100644 source/includes/driver-example-query-47.rst create mode 100644 source/includes/driver-example-query-48.rst create mode 100644 source/includes/driver-example-query-49.rst create mode 100644 source/includes/driver-example-query-50.rst create mode 100644 source/includes/driver-example-query-6.rst create mode 100644 source/includes/driver-example-query-7.rst create mode 100644 source/includes/driver-example-query-9.rst create mode 100644 source/includes/driver-example-query-intro.rst create mode 100644 source/includes/driver-example-update-51.rst create mode 100644 source/includes/driver-example-update-52.rst create mode 100644 source/includes/driver-example-update-53.rst create mode 100644 source/includes/driver-example-update-54.rst create mode 100644 source/includes/templates/tabs.rst diff --git a/.gitignore b/.gitignore index cf3ab5cc341..4e87c354312 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,7 @@ composite-pages.yaml !bin/*/mongodb-domain.yaml meta.yaml build +driver-examples/ *~ source/reference/*/*.rst source/reference/*/*/*.rst diff --git a/Makefile b/Makefile index 9fa7d22a3c2..7a8e8b4a08f 100644 --- a/Makefile +++ b/Makefile @@ -9,6 +9,8 @@ PRODUCTION_BUCKET=docs-mongodb-org-prod # within one bucket. For the manual it is empty. PROJECT= +DRIVERS_PATH=source/driver-examples + BLOCKS_FILE=./build/${GIT_BRANCH}/tests.blocks TEST_FILE=./build/${GIT_BRANCH}/tests.js .PHONY: help lint html stage deploy @@ -27,10 +29,10 @@ test: html ## Runs test framework over the corpus node ./build/docs-tools/tools/rst-testing/compile-blocks.js ${BLOCKS_FILE} > ${TEST_FILE} ./build/docs-tools/tools/rst-testing/rst_tester.py ${TEST_FILE} -html: ## Builds this branch's HTML under build//html +html: examples ## Builds this branch's HTML under build//html giza make html -publish: ## Builds this branch's publishable HTML and other artifacts under build/public +publish: examples ## Builds this branch's publishable HTML and other artifacts under build/public giza make publish # - Enter build//html, and recurse over each regular file @@ -62,3 +64,10 @@ deploy: build/public ## Deploy to the production bucket mut-publish build/public ${PRODUCTION_BUCKET} --prefix=${PROJECT} --deploy --redirect-prefix='v[0-9]\.[0-9]' --redirect-prefix='manual' --redirect-prefix='master' ${ARGS} @echo "Hosted at ${PRODUCTION_URL}/index.html" + +examples: examples-python + +# Something about Python example +examples-python: + mkdir -p ${DRIVERS_PATH} + curl -SfL https://raw.githubusercontent.com/mongodb/mongo-python-driver/master/test/test_examples.py -o ${DRIVERS_PATH}/test_examples.py diff --git a/conf.py b/conf.py index 2ea6752064c..cae7eee5346 100644 --- a/conf.py +++ b/conf.py @@ -38,7 +38,8 @@ def has(self, *args): 'mongodb', 'directives', 'intermanual', - 'testcode' + 'testcode', + 'template' ] locale_dirs = [ os.path.join(conf.paths.projectroot, conf.paths.locale) ] diff --git a/config/intersphinx.yaml b/config/intersphinx.yaml index 19276f4fb59..0e5f5f83f49 100644 --- a/config/intersphinx.yaml +++ b/config/intersphinx.yaml @@ -1,4 +1,8 @@ name: python2 url: https://docs.python.org/2/ path: python2.inv +--- +name: pymongo +url: http://api.mongodb.com/python/current/ +path: pymongo.inv ... diff --git a/source/includes/driver-example-delete-55.rst b/source/includes/driver-example-delete-55.rst new file mode 100644 index 00000000000..d1824df20b2 --- /dev/null +++ b/source/includes/driver-example-delete-55.rst @@ -0,0 +1,32 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany( [ + { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, + { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" }, + { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, + { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, + { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }, + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 55 + :end-before: End Example 55 diff --git a/source/includes/driver-example-delete-56.rst b/source/includes/driver-example-delete-56.rst new file mode 100644 index 00000000000..08f5f5e47a2 --- /dev/null +++ b/source/includes/driver-example-delete-56.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.deleteMany({}) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 56 + :end-before: End Example 56 diff --git a/source/includes/driver-example-delete-57.rst b/source/includes/driver-example-delete-57.rst new file mode 100644 index 00000000000..bc2850f4d7d --- /dev/null +++ b/source/includes/driver-example-delete-57.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.deleteMany({ status : "A" }) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 57 + :end-before: End Example 57 diff --git a/source/includes/driver-example-delete-58.rst b/source/includes/driver-example-delete-58.rst new file mode 100644 index 00000000000..1986b1db5ea --- /dev/null +++ b/source/includes/driver-example-delete-58.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.deleteOne( { status: "D" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 58 + :end-before: End Example 58 diff --git a/source/includes/driver-example-delete-result.rst b/source/includes/driver-example-delete-result.rst new file mode 100644 index 00000000000..2bc8fed29c2 --- /dev/null +++ b/source/includes/driver-example-delete-result.rst @@ -0,0 +1,15 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + The method returns a document with the status of the operation. For + more information and examples, see :method:`~db.collection.deleteMany()`. + + - id: python + content: | + The :py:meth:`~pymongo.collection.Collection.delete_many` + method returns an instance of + :py:class:`pymongo.results.DeleteResult` with the status of the operation. \ No newline at end of file diff --git a/source/includes/driver-example-insert-1.rst b/source/includes/driver-example-insert-1.rst new file mode 100644 index 00000000000..ce1736dca47 --- /dev/null +++ b/source/includes/driver-example-insert-1.rst @@ -0,0 +1,28 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertOne( + { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } + ) + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 1 + :end-before: End Example 1 diff --git a/source/includes/driver-example-insert-2.rst b/source/includes/driver-example-insert-2.rst new file mode 100644 index 00000000000..e1c1ef2f275 --- /dev/null +++ b/source/includes/driver-example-insert-2.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { item: "canvas" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 2 + :end-before: End Example 2 diff --git a/source/includes/driver-example-insert-3.rst b/source/includes/driver-example-insert-3.rst new file mode 100644 index 00000000000..09262a75053 --- /dev/null +++ b/source/includes/driver-example-insert-3.rst @@ -0,0 +1,30 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany([ + { 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" } } + ]) + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 3 + :end-before: End Example 3 diff --git a/source/includes/driver-example-query-10.rst b/source/includes/driver-example-query-10.rst new file mode 100644 index 00000000000..53ece0d920a --- /dev/null +++ b/source/includes/driver-example-query-10.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: { $in: [ "A", "D" ] } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 10 + :end-before: End Example 10 diff --git a/source/includes/driver-example-query-11.rst b/source/includes/driver-example-query-11.rst new file mode 100644 index 00000000000..5af34572d03 --- /dev/null +++ b/source/includes/driver-example-query-11.rst @@ -0,0 +1,21 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A", qty: { $lt: 30 } } ) + + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 11 + :end-before: End Example 11 diff --git a/source/includes/driver-example-query-12.rst b/source/includes/driver-example-query-12.rst new file mode 100644 index 00000000000..c55def8a35b --- /dev/null +++ b/source/includes/driver-example-query-12.rst @@ -0,0 +1,21 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { $or: [ { status: "A" }, { qty: { $lt: 30 } } ] } ) + + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 12 + :end-before: End Example 12 diff --git a/source/includes/driver-example-query-13.rst b/source/includes/driver-example-query-13.rst new file mode 100644 index 00000000000..0ac78818105 --- /dev/null +++ b/source/includes/driver-example-query-13.rst @@ -0,0 +1,24 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { + status: "A", + $or: [ { qty: { $lt: 30 } }, { item: /^p/ } ] + } ) + + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 13 + :end-before: End Example 13 \ No newline at end of file diff --git a/source/includes/driver-example-query-14.rst b/source/includes/driver-example-query-14.rst new file mode 100644 index 00000000000..d934a2695a0 --- /dev/null +++ b/source/includes/driver-example-query-14.rst @@ -0,0 +1,32 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany( [ + { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, + { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "A" }, + { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, + { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, + { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" } + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 14 + :end-before: End Example 14 diff --git a/source/includes/driver-example-query-15.rst b/source/includes/driver-example-query-15.rst new file mode 100644 index 00000000000..eaeaa81f817 --- /dev/null +++ b/source/includes/driver-example-query-15.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 15 + :end-before: End Example 15 diff --git a/source/includes/driver-example-query-16.rst b/source/includes/driver-example-query-16.rst new file mode 100644 index 00000000000..df1bdc9c9a2 --- /dev/null +++ b/source/includes/driver-example-query-16.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { size: { w: 21, h: 14, uom: "cm" } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 16 + :end-before: End Example 16 diff --git a/source/includes/driver-example-query-17.rst b/source/includes/driver-example-query-17.rst new file mode 100644 index 00000000000..c80a8b9d0a8 --- /dev/null +++ b/source/includes/driver-example-query-17.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "size.uom": "in" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 17 + :end-before: End Example 17 diff --git a/source/includes/driver-example-query-18.rst b/source/includes/driver-example-query-18.rst new file mode 100644 index 00000000000..97fadfee5a2 --- /dev/null +++ b/source/includes/driver-example-query-18.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "size.h": { $lt: 15 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 18 + :end-before: End Example 18 diff --git a/source/includes/driver-example-query-19.rst b/source/includes/driver-example-query-19.rst new file mode 100644 index 00000000000..dab53057b1b --- /dev/null +++ b/source/includes/driver-example-query-19.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "size.h": { $lt: 15 }, "size.uom": "in", status: "D" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 19 + :end-before: End Example 19 diff --git a/source/includes/driver-example-query-20.rst b/source/includes/driver-example-query-20.rst new file mode 100644 index 00000000000..8cd80d79318 --- /dev/null +++ b/source/includes/driver-example-query-20.rst @@ -0,0 +1,32 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany([ + { item: "journal", qty: 25, tags: ["blank", "red"], dim_cm: [ 14, 21 ] }, + { item: "notebook", qty: 50, tags: ["red", "blank"], dim_cm: [ 14, 21 ] }, + { item: "paper", qty: 100, tags: ["red", "blank", "plain"], dim_cm: [ 14, 21 ] }, + { item: "planner", qty: 75, tags: ["blank", "red"], dim_cm: [ 22.85, 30 ] }, + { item: "postcard", qty: 45, tags: ["blue"], dim_cm: [ 10, 15.25 ] } + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 20 + :end-before: End Example 20 diff --git a/source/includes/driver-example-query-21.rst b/source/includes/driver-example-query-21.rst new file mode 100644 index 00000000000..5e68403c9a4 --- /dev/null +++ b/source/includes/driver-example-query-21.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { tags: ["red", "blank"] } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 21 + :end-before: End Example 21 diff --git a/source/includes/driver-example-query-22.rst b/source/includes/driver-example-query-22.rst new file mode 100644 index 00000000000..99f420a3dcf --- /dev/null +++ b/source/includes/driver-example-query-22.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { tags: { $all: ["red", "blank"] } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 22 + :end-before: End Example 22 diff --git a/source/includes/driver-example-query-23.rst b/source/includes/driver-example-query-23.rst new file mode 100644 index 00000000000..141ceb98152 --- /dev/null +++ b/source/includes/driver-example-query-23.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { tags: "red" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 23 + :end-before: End Example 23 diff --git a/source/includes/driver-example-query-24.rst b/source/includes/driver-example-query-24.rst new file mode 100644 index 00000000000..b460738e7dd --- /dev/null +++ b/source/includes/driver-example-query-24.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { dim_cm: { $gt: 25 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 24 + :end-before: End Example 24 diff --git a/source/includes/driver-example-query-25.rst b/source/includes/driver-example-query-25.rst new file mode 100644 index 00000000000..285fb167f3b --- /dev/null +++ b/source/includes/driver-example-query-25.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { dim_cm: { $gt: 15, $lt: 20 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 25 + :end-before: End Example 25 diff --git a/source/includes/driver-example-query-26.rst b/source/includes/driver-example-query-26.rst new file mode 100644 index 00000000000..45af5cae8cf --- /dev/null +++ b/source/includes/driver-example-query-26.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { dim_cm: { $elemMatch: { $gt: 22, $lt: 30 } } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 26 + :end-before: End Example 26 diff --git a/source/includes/driver-example-query-27.rst b/source/includes/driver-example-query-27.rst new file mode 100644 index 00000000000..b83fbb545e4 --- /dev/null +++ b/source/includes/driver-example-query-27.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "dim_cm.1": { $gt: 25 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 27 + :end-before: End Example 27 diff --git a/source/includes/driver-example-query-28.rst b/source/includes/driver-example-query-28.rst new file mode 100644 index 00000000000..04792cf34e6 --- /dev/null +++ b/source/includes/driver-example-query-28.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "tags": { $size: 3 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 28 + :end-before: End Example 28 diff --git a/source/includes/driver-example-query-29.rst b/source/includes/driver-example-query-29.rst new file mode 100644 index 00000000000..5357c5a88b1 --- /dev/null +++ b/source/includes/driver-example-query-29.rst @@ -0,0 +1,32 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany( [ + { item: "journal", instock: [ { warehouse: "A", qty: 5 }, { warehouse: "C", qty: 15 } ] }, + { item: "notebook", instock: [ { warehouse: "C", qty: 5 } ] }, + { item: "paper", instock: [ { warehouse: "A", qty: 60 }, { warehouse: "B", qty: 15 } ] }, + { item: "planner", instock: [ { warehouse: "A", qty: 40 }, { warehouse: "B", qty: 5 } ] }, + { item: "postcard", instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 29 + :end-before: End Example 29 diff --git a/source/includes/driver-example-query-30.rst b/source/includes/driver-example-query-30.rst new file mode 100644 index 00000000000..d28f255e985 --- /dev/null +++ b/source/includes/driver-example-query-30.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "instock": { warehouse: "A", qty: 5 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 30 + :end-before: End Example 30 diff --git a/source/includes/driver-example-query-31.rst b/source/includes/driver-example-query-31.rst new file mode 100644 index 00000000000..4e699de44f0 --- /dev/null +++ b/source/includes/driver-example-query-31.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "instock": { qty: 5, warehouse: "A" } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 31 + :end-before: End Example 31 diff --git a/source/includes/driver-example-query-32.rst b/source/includes/driver-example-query-32.rst new file mode 100644 index 00000000000..431434ab9a4 --- /dev/null +++ b/source/includes/driver-example-query-32.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { 'instock.0.qty': { $lte: 20 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 32 + :end-before: End Example 32 diff --git a/source/includes/driver-example-query-33.rst b/source/includes/driver-example-query-33.rst new file mode 100644 index 00000000000..8f8774a7761 --- /dev/null +++ b/source/includes/driver-example-query-33.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { 'instock.qty': { $lte: 20 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 33 + :end-before: End Example 33 diff --git a/source/includes/driver-example-query-34.rst b/source/includes/driver-example-query-34.rst new file mode 100644 index 00000000000..731dafede05 --- /dev/null +++ b/source/includes/driver-example-query-34.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "instock": { $elemMatch: { qty: 5, warehouse: "A" } } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 34 + :end-before: End Example 34 diff --git a/source/includes/driver-example-query-35.rst b/source/includes/driver-example-query-35.rst new file mode 100644 index 00000000000..2ccf08e5c46 --- /dev/null +++ b/source/includes/driver-example-query-35.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "instock": { $elemMatch: { qty: { $gt: 10, $lte: 20 } } } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 35 + :end-before: End Example 35 diff --git a/source/includes/driver-example-query-36.rst b/source/includes/driver-example-query-36.rst new file mode 100644 index 00000000000..d133cbadac2 --- /dev/null +++ b/source/includes/driver-example-query-36.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "instock.qty": { $gt: 10, $lte: 20 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 36 + :end-before: End Example 36 diff --git a/source/includes/driver-example-query-37.rst b/source/includes/driver-example-query-37.rst new file mode 100644 index 00000000000..6a8ed58d1cf --- /dev/null +++ b/source/includes/driver-example-query-37.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { "instock.qty": 5, "instock.warehouse": "A" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 37 + :end-before: End Example 37 diff --git a/source/includes/driver-example-query-38.rst b/source/includes/driver-example-query-38.rst new file mode 100644 index 00000000000..0457e092445 --- /dev/null +++ b/source/includes/driver-example-query-38.rst @@ -0,0 +1,29 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany([ + { _id: 1, item: null }, + { _id: 2 } + ]) + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 38 + :end-before: End Example 38 diff --git a/source/includes/driver-example-query-39.rst b/source/includes/driver-example-query-39.rst new file mode 100644 index 00000000000..5e0a6556be1 --- /dev/null +++ b/source/includes/driver-example-query-39.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { item: null } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 39 + :end-before: End Example 39 diff --git a/source/includes/driver-example-query-40.rst b/source/includes/driver-example-query-40.rst new file mode 100644 index 00000000000..f0bec6f02dd --- /dev/null +++ b/source/includes/driver-example-query-40.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { item : { $type: 10 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 40 + :end-before: End Example 40 diff --git a/source/includes/driver-example-query-41.rst b/source/includes/driver-example-query-41.rst new file mode 100644 index 00000000000..8bf57f2fc5b --- /dev/null +++ b/source/includes/driver-example-query-41.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { item : { $exists: false } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 41 + :end-before: End Example 41 diff --git a/source/includes/driver-example-query-42.rst b/source/includes/driver-example-query-42.rst new file mode 100644 index 00000000000..dcee69587bf --- /dev/null +++ b/source/includes/driver-example-query-42.rst @@ -0,0 +1,32 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany( [ + { item: "journal", status: "A", size: { h: 14, w: 21, uom: "cm" }, instock: [ { warehouse: "A", qty: 5 } ] }, + { item: "notebook", status: "A", size: { h: 8.5, w: 11, uom: "in" }, instock: [ { warehouse: "C", qty: 5 } ] }, + { item: "paper", status: "D", size: { h: 8.5, w: 11, uom: "in" }, instock: [ { warehouse: "A", qty: 60 } ] }, + { item: "planner", status: "D", size: { h: 22.85, w: 30, uom: "cm" }, instock: [ { warehouse: "A", qty: 40 } ] }, + { item: "postcard", status: "A", size: { h: 10, w: 15.25, uom: "cm" }, instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 42 + :end-before: End Example 42 diff --git a/source/includes/driver-example-query-43.rst b/source/includes/driver-example-query-43.rst new file mode 100644 index 00000000000..48a7ae09b0e --- /dev/null +++ b/source/includes/driver-example-query-43.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 43 + :end-before: End Example 43 diff --git a/source/includes/driver-example-query-44.rst b/source/includes/driver-example-query-44.rst new file mode 100644 index 00000000000..e0add8e2bca --- /dev/null +++ b/source/includes/driver-example-query-44.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A" }, { item: 1, status: 1 } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 44 + :end-before: End Example 44 diff --git a/source/includes/driver-example-query-45.rst b/source/includes/driver-example-query-45.rst new file mode 100644 index 00000000000..2e0c0cd9ceb --- /dev/null +++ b/source/includes/driver-example-query-45.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A" }, { item: 1, status: 1, _id: 0 } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 45 + :end-before: End Example 45 diff --git a/source/includes/driver-example-query-46.rst b/source/includes/driver-example-query-46.rst new file mode 100644 index 00000000000..63adc1b167d --- /dev/null +++ b/source/includes/driver-example-query-46.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A" }, { status: 0, instock: 0 } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 46 + :end-before: End Example 46 diff --git a/source/includes/driver-example-query-47.rst b/source/includes/driver-example-query-47.rst new file mode 100644 index 00000000000..5426ccf849b --- /dev/null +++ b/source/includes/driver-example-query-47.rst @@ -0,0 +1,23 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( + { status: "A" }, + { item: 1, status: 1, "size.uom": 1 } + ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 47 + :end-before: End Example 47 diff --git a/source/includes/driver-example-query-48.rst b/source/includes/driver-example-query-48.rst new file mode 100644 index 00000000000..85a8e537e0f --- /dev/null +++ b/source/includes/driver-example-query-48.rst @@ -0,0 +1,23 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( + { status: "A" }, + { "size.uom": 0 } + ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 48 + :end-before: End Example 48 diff --git a/source/includes/driver-example-query-49.rst b/source/includes/driver-example-query-49.rst new file mode 100644 index 00000000000..94d22f1c0c0 --- /dev/null +++ b/source/includes/driver-example-query-49.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A" }, { item: 1, status: 1, "instock.qty": 1 } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 49 + :end-before: End Example 49 diff --git a/source/includes/driver-example-query-50.rst b/source/includes/driver-example-query-50.rst new file mode 100644 index 00000000000..a29af1360cd --- /dev/null +++ b/source/includes/driver-example-query-50.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "A" }, { name: 1, status: 1, instock: { $slice: -1 } } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 50 + :end-before: End Example 50 diff --git a/source/includes/driver-example-query-6.rst b/source/includes/driver-example-query-6.rst new file mode 100644 index 00000000000..78c478b843e --- /dev/null +++ b/source/includes/driver-example-query-6.rst @@ -0,0 +1,32 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany([ + { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, + { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "A" }, + { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, + { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, + { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" } + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 6 + :end-before: End Example 6 diff --git a/source/includes/driver-example-query-7.rst b/source/includes/driver-example-query-7.rst new file mode 100644 index 00000000000..c82e7723505 --- /dev/null +++ b/source/includes/driver-example-query-7.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( {} ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 7 + :end-before: End Example 7 diff --git a/source/includes/driver-example-query-9.rst b/source/includes/driver-example-query-9.rst new file mode 100644 index 00000000000..8e22af95cc4 --- /dev/null +++ b/source/includes/driver-example-query-9.rst @@ -0,0 +1,20 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.find( { status: "D" } ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 9 + :end-before: End Example 9 diff --git a/source/includes/driver-example-query-intro.rst b/source/includes/driver-example-query-intro.rst new file mode 100644 index 00000000000..7e22632c04d --- /dev/null +++ b/source/includes/driver-example-query-intro.rst @@ -0,0 +1,22 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + This page provides examples of |query_operations| using the + :method:`db.collection.find()` method in the + :program:`mongo` shell. The examples on this page use the + ``inventory`` collection. To populate the ``inventory`` + collection, run the following: + + + - id: python + content: | + This page provides examples of |query_operations| using the + :py:meth:`pymongo.collection.Collection.find` method in the + `PyMongo `_ + Python driver. The examples on this page use the ``inventory`` + collection. To populate the ``inventory`` collection, run the + following: diff --git a/source/includes/driver-example-update-51.rst b/source/includes/driver-example-update-51.rst new file mode 100644 index 00000000000..84c97f9083e --- /dev/null +++ b/source/includes/driver-example-update-51.rst @@ -0,0 +1,37 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.insertMany( [ + { item: "canvas", qty: 100, size: { h: 28, w: 35.5, uom: "cm" }, status: "A" }, + { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, + { item: "mat", qty: 85, size: { h: 27.9, w: 35.5, uom: "cm" }, status: "A" }, + { item: "mousepad", qty: 25, size: { h: 19, w: 22.85, uom: "cm" }, status: "P" }, + { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" }, + { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, + { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, + { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }, + { item: "sketchbook", qty: 80, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, + { item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" } + ]); + + .. only:: website + + You can run the operation in the web shell below: + + .. include:: /includes/fact-mws.rst + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 51 + :end-before: End Example 51 diff --git a/source/includes/driver-example-update-52.rst b/source/includes/driver-example-update-52.rst new file mode 100644 index 00000000000..5f85e57edf2 --- /dev/null +++ b/source/includes/driver-example-update-52.rst @@ -0,0 +1,26 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.updateOne( + { item: "paper" }, + { + $set: { "size.uom": "cm", status: "P" }, + $currentDate: { lastModified: true } + } + ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 52 + :end-before: End Example 52 diff --git a/source/includes/driver-example-update-53.rst b/source/includes/driver-example-update-53.rst new file mode 100644 index 00000000000..28a1082dc5c --- /dev/null +++ b/source/includes/driver-example-update-53.rst @@ -0,0 +1,26 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.updateMany( + { "qty": { $lt: 50 } }, + { + $set: { "size.uom": "in", status: "P" }, + $currentDate: { lastModified: true } + } + ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 53 + :end-before: End Example 53 diff --git a/source/includes/driver-example-update-54.rst b/source/includes/driver-example-update-54.rst new file mode 100644 index 00000000000..55a2b96c6c7 --- /dev/null +++ b/source/includes/driver-example-update-54.rst @@ -0,0 +1,23 @@ +.. include:: /includes/templates/tabs.rst + +.. tabs:: + + tabs: + - id: shell + content: | + .. class:: copyable-code + .. code-block:: javascript + + db.inventory.replaceOne( + { item: "paper" }, + { item: "paper", instock: [ { warehouse: "A", qty: 60 }, { warehouse: "B", qty: 40 } ] } + ) + + - id: python + content: | + .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Example 54 + :end-before: End Example 54 diff --git a/source/includes/templates/tabs.rst b/source/includes/templates/tabs.rst new file mode 100644 index 00000000000..4016dd5d0cb --- /dev/null +++ b/source/includes/templates/tabs.rst @@ -0,0 +1,76 @@ +.. Create a directive that inserts a tabbed set of subdocuments. +.. Each subdocument CANNOT use structural elements such as sections. For this reason, +.. sections must be turned into the h1, h2, h3, ... directives below. + +.. Caveat: these header tags do not create wrapping sections, and do not have permalinks. + +.. (All of this is necessary because docutils "container" directive cannot contain sections, +.. and because sphinx section tags interfere with manual HTML markup.) + +.. If you rename or modify the h1/h2/h3/h4... directives, make sure to change the template +.. extension appropriately. + +.. register-template:: tabs + :yaml: + + .. raw:: html + +
+
    + {{ for tab in tabs sortLanguages }} + {{ # Only render the tab here if i < 5 }} + {{ if i lessThan(5) }} + {{ tab.name }} + {{ end }} + {{ end }} + {{ if tabs len greaterThan(4) }} +
  • + Other + +
    • + {{ end }} +
+
+ {{ for tab in tabs sortLanguages}} +
+ + {{ tab.content convertSections }} + + .. raw:: html + +
+ {{ end }} +
+
+ + +.. register-template:: h1 + + .. raw:: html + +

{{ title }}

+ +.. register-template:: h2 + + .. raw:: html + +

{{ title }}

+ +.. register-template:: h3 + + .. raw:: html + +

{{ title }}

+ +.. register-template:: h4 + + .. raw:: html + +

{{ title }}

diff --git a/source/tutorial/insert-documents.txt b/source/tutorial/insert-documents.txt index 39c4d80045f..abd77e36c18 100644 --- a/source/tutorial/insert-documents.txt +++ b/source/tutorial/insert-documents.txt @@ -1,3 +1,5 @@ +.. include:: /includes/templates/tabs.rst + .. _write-op-insert: ================ @@ -10,8 +12,7 @@ Insert Documents :description: Insert documents using MongoDB. Creates collection upon first insert. :keywords: insert documents, create documents, insert into collection, create collection, MongoDB 3.4, version 3.4 -This page provides examples of insert operations in the -:program:`mongo` shell. +This page provides examples of insert operations in MongoDB. .. admonition:: Creating a Collection :class: note @@ -21,96 +22,115 @@ This page provides examples of insert operations in the .. _write-op-insertOne: -Insert a Document via ``db.collection.insertOne()`` ---------------------------------------------------- +Insert a Single Document +------------------------ .. versionadded:: 3.2 -:method:`db.collection.insertOne()` inserts a *single* :ref:`document -` into a collection. - -The following example inserts a new document into the ``inventory`` -collection. Since 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`. - - -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.insertOne( - { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } - ) - -.. only:: website - - You can run this method in the web shell below: - - .. include:: /includes/fact-mws.rst - -:method:`~db.collection.insertOne()` will return 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 -`. +.. tabs:: + + 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. Since 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: 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. Since 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`. + +.. include:: /includes/driver-example-insert-1.rst + +.. tabs:: + + 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: 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. To retrieve the document that you just inserted, :ref:`query the collection `: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { item: "canvas" } ) - -For more information and examples, see -:method:`db.collection.insertOne()`. +.. include:: /includes/driver-example-insert-2.rst .. _write-op-insertMany: -Insert Multiple Documents via ``db.collection.insertMany()`` ------------------------------------------------------------- +Insert Multiple Documents +------------------------- .. 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. Since 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`. - -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.insertMany([ - { 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" } } - ]) - -.. only:: website - - You can run this method in the web shell below: - - .. include:: /includes/fact-mws.rst - -:method:`~db.collection.insertMany()` will return a document that -includes the newly inserted documents ``_id`` field values. See the -:ref:`reference ` for an example. +.. tabs:: + + tabs: + - id: shell + content: | + :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. Since 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: python + content: | + :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. Since 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`. + +.. include:: /includes/driver-example-insert-3.rst + +.. tabs:: + + 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. + + - 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 `: -.. code-block:: javascript - - db.inventory.find() - -For more information and examples, see -:method:`db.collection.insertMany()`. +.. include:: /includes/driver-example-query-7.rst .. _write-op-insert-behavior: @@ -142,13 +162,28 @@ With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see :doc:`/reference/write-concern`. -.. seealso:: +.. tabs:: + + tabs: + - id: shell + content: | + .. seealso:: + + - :method:`db.collection.insertOne()` + + - :method:`db.collection.insertMany()` + + - :ref:`additional-inserts` + + - id: python + content: | + .. seealso:: - - :method:`db.collection.insertOne()` + - :py:meth:`pymongo.collection.Collection.insert_one` - - :method:`db.collection.insertMany()` + - :py:meth:`pymongo.collection.Collection.insert_many` - - :ref:`additional-inserts` + - :ref:`additional-inserts` .. class:: hidden diff --git a/source/tutorial/project-fields-from-query-results.txt b/source/tutorial/project-fields-from-query-results.txt index 5999536550c..477a0a84b06 100644 --- a/source/tutorial/project-fields-from-query-results.txt +++ b/source/tutorial/project-fields-from-query-results.txt @@ -11,41 +11,36 @@ Project Fields to Return from Query By default, queries in MongoDB return all fields in matching documents. To limit the amount of data that MongoDB sends to applications, you can include a :term:`projection` document to specify or restrict fields to -return. This page provides examples of how to use projection in -MongoDB. The examples on this page use the inventory collection. To -populate the inventory collection, run the following in the mongo shell: +return. -.. class:: copyable-code -.. code-block:: javascript +.. |query_operations| replace:: query operations with projection - db.inventory.insertMany( [ - { item: "journal", status: "A", size: { h: 14, w: 21, uom: "cm" }, instock: [ { warehouse: "A", qty: 5 } ] }, - { item: "notebook", status: "A", size: { h: 8.5, w: 11, uom: "in" }, instock: [ { warehouse: "C", qty: 5 } ] }, - { item: "paper", status: "D", size: { h: 8.5, w: 11, uom: "in" }, instock: [ { warehouse: "A", qty: 60 } ] }, - { item: "planner", status: "D", size: { h: 22.85, w: 30, uom: "cm" }, instock: [ { warehouse: "A", qty: 40 } ] }, - { item: "postcard", status: "A", size: { h: 10, w: 15.25, uom: "cm" }, instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } - ]); +.. include:: /includes/driver-example-query-intro.rst -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-query-42.rst Return All Fields in Matching Documents --------------------------------------- -If you specify no projection, the :method:`db.collection.find()` method -returns all fields in the matching documents. +.. tabs:: -The following example returns all fields from all documents in the -``inventory`` collection where the ``status`` equals ``"A"``: + tabs: + - id: shell + content: | + If you do not specify a :term:`projection` document, the + :method:`db.collection.find()` method returns all fields in the + matching documents. -.. class:: copyable-code + - id: python + content: | + If you do not specify a :term:`projection` document, the + :py:meth:`~pymongo.collection.Collection.find` method returns + all fields in the matching documents. -.. code-block:: javascript +The following example returns all fields from all documents in the +``inventory`` collection where the ``status`` equals ``"A"``: - db.inventory.find( { status: "A" } ) +.. include:: /includes/driver-example-query-43.rst The operation corresponds to the following SQL statement: @@ -62,11 +57,7 @@ returns all documents that match the query. In the result set, only the ``item``, ``status`` and, by default, the ``_id`` fields return in the matching documents. -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { status: "A" }, { item: 1, status: 1 } ) +.. include:: /includes/driver-example-query-44.rst The operation corresponds to the following SQL statement: @@ -80,11 +71,7 @@ Suppress ``_id`` Field You can remove the ``_id`` field from the results by specifying its exclusion ``: 0`` in the projection, as in the following example: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { status: "A" }, { item: 1, status: 1, _id: 0 } ) +.. include:: /includes/driver-example-query-45.rst The operation corresponds to the following SQL statement: @@ -100,11 +87,7 @@ can use a projection to exclude specific fields. The following example which returns all fields except for the ``status`` and the ``instock`` fields in the matching documents: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { status: "A" }, { status: 0, instock: 0 } ) +.. include:: /includes/driver-example-query-46.rst With the exception of the ``_id`` field, you cannot combine inclusion and exclusion statements in projection documents. @@ -120,14 +103,7 @@ The following example returns: the ``_id`` field (returned by default), ``item`` field, ``status`` field, and the ``uom`` field in the ``size`` document; the ``uom`` field remains embedded in the ``size`` document. -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( - { status: "A" }, - { item: 1, status: 1, "size.uom": 1 } - ) +.. include:: /includes/driver-example-query-47.rst Suppress Specific Fields in Embedded Documents ---------------------------------------------- @@ -140,14 +116,7 @@ The following example specifies a projection to exclude the ``uom`` field inside the ``size`` document. All other fields are returned in the matching documents: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( - { status: "A" }, - { "size.uom": 0 } - ) +.. include:: /includes/driver-example-query-48.rst Projection on Embedded Documents in an Array -------------------------------------------- @@ -160,11 +129,7 @@ field, the ``status`` field, and the ``qty`` field in the documents embedded in the ``instock`` array. The ``_id`` field is returned by default. -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { status: "A" }, { item: 1, status: 1, "instock.qty": 1 } ) +.. include:: /includes/driver-example-query-49.rst Project Specific Array Elements in the Returned Array @@ -177,11 +142,7 @@ and :projection:`$`. The following example uses the :projection:`$slice` projection operator to return just the last element in the ``instock`` array. -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { status: "A" }, { name: 1, status: 1, instock: { $slice: -1 } } ) +.. include:: /includes/driver-example-query-50.rst :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned @@ -191,4 +152,9 @@ project the array with the first element. .. seealso:: :doc:`/tutorial/query-documents` -.. include:: /includes/footnote-set-shell-batch-size.rst +.. tabs:: + + tabs: + - id: shell + content: | + .. include:: /includes/footnote-set-shell-batch-size.rst diff --git a/source/tutorial/query-array-of-documents.txt b/source/tutorial/query-array-of-documents.txt index 5e117bb164e..664f5e143b3 100644 --- a/source/tutorial/query-array-of-documents.txt +++ b/source/tutorial/query-array-of-documents.txt @@ -11,28 +11,11 @@ Query an Array of Embedded Documents :description: MongoDB Manual - how to query an array of documents, how to query an array of nested documents, how to query an array of embedded documents. :keywords: array of nested documents, array of embedded documents, array of documents, nested documents, array index, select, array, array elements, array items -This page provides examples of how to query on array of nested -documents in MongoDB. The examples on this page use the ``inventory`` -collection. To populate the ``inventory`` collection, run the following -in the :program:`mongo` shell: +.. |query_operations| replace:: query operations on an array of nested documents -.. class:: copyable-code +.. include:: /includes/driver-example-query-intro.rst -.. code-block:: javascript - - db.inventory.insertMany( [ - { item: "journal", instock: [ { warehouse: "A", qty: 5 }, { warehouse: "C", qty: 15 } ] }, - { item: "notebook", instock: [ { warehouse: "C", qty: 5 } ] }, - { item: "paper", instock: [ { warehouse: "A", qty: 60 }, { warehouse: "B", qty: 15 } ] }, - { item: "planner", instock: [ { warehouse: "A", qty: 40 }, { warehouse: "B", qty: 5 } ] }, - { item: "postcard", instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } - ]); - -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-query-29.rst Query for a Document Nested in an Array --------------------------------------- @@ -40,22 +23,14 @@ Query for a Document Nested in an Array The following examples selects all documents where an element in the ``instock`` array matches the specified document: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "instock": { warehouse: "A", qty: 5 } } ) +.. include:: /includes/driver-example-query-30.rst Equality matches on the whole embedded/nested document require an *exact* match of the specified document, including the field order. For example, the following query does not match any documents in the ``inventory`` collection: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "instock": { qty: 5, warehouse: "A" } } ) +.. include:: /includes/driver-example-query-31.rst Specify a Query Condition on a Field in an Array of Documents ------------------------------------------------------------- @@ -71,11 +46,7 @@ The following example selects all documents where the ``instock`` array has as its first element a document that contains the field ``qty`` whose value is less than or equal to ``20``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { 'instock.0.qty': { $lte: 20 } } ) +.. include:: /includes/driver-example-query-32.rst Specify a Query Condition on a Field Embedded in an Array of Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -88,11 +59,7 @@ The following example selects all documents where the ``instock`` array has at least one embedded document that contains the field ``qty`` whose value is less than or equal to ``20``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { 'instock.qty': { $lte: 20 } } ) +.. include:: /includes/driver-example-query-33.rst Specify Multiple Conditions for Array of Documents -------------------------------------------------- @@ -114,21 +81,13 @@ has at least one embedded document that contains both the field ``qty`` equal to ``5`` and the field ``warehouse`` equal to ``A``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "instock": { $elemMatch: { qty: 5, warehouse: "A" } } } ) +.. include:: /includes/driver-example-query-34.rst The following example queries for documents where the ``instock`` array has at least one embedded document that contains the field ``qty`` that is greater than ``10`` and less than or equal to ``20``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "instock": { $elemMatch: { qty: { $gt: 10, $lte: 20 } } } } ) +.. include:: /includes/driver-example-query-35.rst Combination of Elements Satisfies the Criteria ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -144,11 +103,7 @@ nested in the ``instock`` array has the ``qty`` field greater than document) in the array has the ``qty`` field less than or equal to ``20``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "instock.qty": { $gt: 10, $lte: 20 } } ) +.. include:: /includes/driver-example-query-36.rst The following example queries for documents where the ``instock`` array has at least one embedded document that contains the field ``qty`` @@ -156,11 +111,7 @@ equal to ``5`` and at least one embedded document (but not necessarily the same embedded document) that contains the field ``warehouse`` equal to ``A``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "instock.qty": 5, "instock.warehouse": "A" } ) +.. include:: /includes/driver-example-query-37.rst Additional Query Tutorials -------------------------- diff --git a/source/tutorial/query-arrays.txt b/source/tutorial/query-arrays.txt index 138b854d66f..90de116c722 100644 --- a/source/tutorial/query-arrays.txt +++ b/source/tutorial/query-arrays.txt @@ -11,28 +11,11 @@ Query an Array :description: MongoDB Manual - How to query an array: query on the array field as a whole, check if element in array, query for array element, query if field in array, query by array size. :keywords: array, array elements, array items, queries, select, MongoDB Manual, query an array, query for items in array -This page provides examples of how to query on array fields in MongoDB. -The examples on this page use the ``inventory`` collection. To populate -the ``inventory`` collection, run the following in the :program:`mongo` -shell: +.. |query_operations| replace:: query operations on array fields -.. class:: copyable-code +.. include:: /includes/driver-example-query-intro.rst -.. code-block:: javascript - - db.inventory.insertMany([ - { item: "journal", qty: 25, tags: ["blank", "red"], dim_cm: [ 14, 21 ] }, - { item: "notebook", qty: 50, tags: ["red", "blank"], dim_cm: [ 14, 21 ] }, - { item: "paper", qty: 100, tags: ["red", "blank", "plain"], dim_cm: [ 14, 21 ] }, - { item: "planner", qty: 75, tags: ["blank", "red"], dim_cm: [ 22.85, 30 ] }, - { item: "postcard", qty: 45, tags: ["blue"], dim_cm: [ 10, 15.25 ] } - ]); - -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-query-20.rst .. _array-match-exact: @@ -45,21 +28,13 @@ including the order of the elements. The following example queries for all documents where the field ``tags`` value is an array with exactly two elements, ``"red"`` and ``"blank"``, in the specified order: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { tags: ["red", "blank"] } ) +.. include:: /includes/driver-example-query-21.rst If, instead, you wish to find an array that contains both the elements ``"red"`` and ``"blank"``, without regard to order or other elements in the array, use the :query:`$all` operator: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { tags: { $all: ["red", "blank"] } } ) +.. include:: /includes/driver-example-query-22.rst .. _array-match-single-element: @@ -72,11 +47,7 @@ the element value. The following example queries for all documents where ``tags`` is an array that contains the string ``"red"`` as one of its elements: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { tags: "red" } ) +.. include:: /includes/driver-example-query-23.rst To specify conditions on the elements in the array field, use the query filter document: @@ -89,11 +60,7 @@ For example, the following operation queries for all documents where the array ``dim_cm`` contains at least one element whose value is greater than ``25``. -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { dim_cm: { $gt: 25 } } ) +.. include:: /includes/driver-example-query-24.rst .. _specify-multiple-criteria-for-array-elements: @@ -115,11 +82,7 @@ conditions; e.g., one element can satisfy the greater than ``15`` condition and another element can satisfy the less than ``20`` condition, or a single element can satisfy both: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { dim_cm: { $gt: 15, $lt: 20 } } ) +.. include:: /includes/driver-example-query-25.rst .. _single-element-satisfies-criteria: @@ -134,11 +97,7 @@ The following example queries for documents where the ``dim_cm`` array contains at least one element that is both greater than (:query:`$gt`) ``22`` and less than (:query:`$lt`) ``30``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { dim_cm: { $elemMatch: { $gt: 22, $lt: 30 } } } ) +.. include:: /includes/driver-example-query-26.rst Query for an Element by the Array Index Position ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,11 +109,7 @@ zero-based indexing. The following example queries for all documents where the second element in the array ``dim_cm`` is greater than ``25``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "dim_cm.1": { $gt: 25 } } ) +.. include:: /includes/driver-example-query-27.rst Query an Array by Array Length ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -163,11 +118,7 @@ Use the :query:`$size` operator to query for arrays by number of elements. For example, the following selects documents where the array ``tags`` has 3 elements. -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "tags": { $size: 3 } } ) +.. include:: /includes/driver-example-query-28.rst Additional Query Tutorials diff --git a/source/tutorial/query-documents.txt b/source/tutorial/query-documents.txt index 2335685071f..7c17400b7f0 100644 --- a/source/tutorial/query-documents.txt +++ b/source/tutorial/query-documents.txt @@ -1,3 +1,5 @@ +.. include:: /includes/templates/tabs.rst + .. _read-operations-query-document: .. _read-operations-queries: @@ -11,62 +13,38 @@ Query Documents :description: MongoDB Manual. How do I query documents, query top level fields, perform equality match, query with query operators, specify compound query conditions. :keywords: query, select from collection, select all, select conditions, filters, select where, criteria, greater than, less than, MongoDB Manual -This page provides examples of query operations using the -``db.collection.find()`` method in the :program:`mongo` shell. The -examples on this page use the ``inventory`` collection. To populate the -``inventory`` collection, run the following in the :program:`mongo` -shell: - -.. class:: copyable-code - -.. code-block:: javascript +.. |query_operations| replace:: query operations - db.inventory.insertMany([ - { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, - { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "A" }, - { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, - { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, - { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" } - ]); +.. include:: /includes/driver-example-query-intro.rst -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-query-6.rst Select All Documents in a Collection ------------------------------------ To select all documents in the collection, pass an empty document -``{}`` as the query filter parameter to the -:method:`db.collection.find()` method. The query filter parameter -determines the select criteria: - -.. class:: copyable-code +``{}`` as the query filter parameter to the find method. The query +filter parameter determines the select criteria: -.. code-block:: javascript +.. include:: /includes/driver-example-query-7.rst - db.inventory.find( {} ) - -Omitting a query filter parameter is equivalent to specifying an empty -query document. As such, the following operation is equivalent to the -previous operation: - -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find() - -These operations correspond to the following SQL statement: +These operation corresponds to the following SQL statement: .. code-block:: sql SELECT * FROM inventory -For more information on the syntax of the method, see -:method:`db.collection.find()`. +.. tabs:: + + tabs: + - id: shell + content: | + For more information on the syntax of the method, see + :method:`~db.collection.find()`. + - id: python + content: | + For more information on the syntax of the method, see + :py:meth:`~pymongo.collection.Collection.find`. .. _read-operations-query-argument: @@ -78,11 +56,7 @@ Specify Equality Condition The following example selects from the ``inventory`` collection all documents where the ``status`` equals ``"D"``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { status: "D" } ) +.. include:: /includes/driver-example-query-9.rst This operation corresponds to the following SQL statement: @@ -96,14 +70,9 @@ Specify Conditions Using Query Operators .. include:: /includes/extracts/filter-query-operators.rst The following example retrieves all documents from the ``inventory`` -collection where ``status`` equals either ``"A"`` or -``"D"``: - -.. class:: copyable-code +collection where ``status`` equals either ``"A"`` or ``"D"``: -.. code-block:: javascript - - db.inventory.find( { status: { $in: [ "A", "D" ] } } ) +.. include:: /includes/driver-example-query-10.rst Although you can express this query using the :query:`$or` operator, use the :query:`$in` operator rather than the :query:`$or` @@ -127,14 +96,10 @@ connects the clauses of a compound query so that the query selects the documents in the collection that match all the conditions. The following example retrieves all documents in the ``inventory`` -collection where the ``status`` equals ``"A"`` **and** ``qty`` -is less than (:query:`$lt`) ``30``: - -.. class:: copyable-code - -.. code-block:: javascript +collection where the ``status`` equals ``"A"`` **and** ``qty`` is less +than (:query:`$lt`) ``30``: - db.inventory.find( { status: "A", qty: { $lt: 30 } } ) +.. include:: /includes/driver-example-query-11.rst The operation corresponds to the following SQL statement: @@ -157,11 +122,7 @@ The following example retrieves all documents in the collection where the ``status`` equals ``"A"`` **or** ``qty`` is less than (:query:`$lt`) ``30``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { $or: [ { status: "A" }, { qty: { $lt: 30 } } ] } ) +.. include:: /includes/driver-example-query-12.rst The operation corresponds to the following SQL statement: @@ -181,14 +142,7 @@ documents in the collection where the ``status`` equals ``"A"`` **and** *either* ``qty`` is less than (:query:`$lt`) ``30`` *or* ``item`` starts with the character ``p``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { - status: "A", - $or: [ { qty: { $lt: 30 } }, { item: /^p/ } ] - } ) +.. include:: /includes/driver-example-query-13.rst The operation corresponds to the following SQL statement: @@ -222,9 +176,20 @@ Behavior Cursor ~~~~~~ -The :method:`db.collection.find()` method -returns a :doc:`cursor ` to the matching -documents. +.. tabs:: + + tabs: + - id: shell + content: | + The :method:`db.collection.find()` method + returns a :doc:`cursor ` to the matching + documents. + - id: python + content: | + The :py:meth:`pymongo.collection.Collection.find` method + returns a :doc:`cursor ` to the + matching documents. See the PyMongo documentation for + `iterating over a cursor `_. Read Isolation ~~~~~~~~~~~~~~ @@ -253,14 +218,35 @@ Additional Methods The following methods can also read documents from a collection: -- :method:`db.collection.findOne` [#findOne]_ - -- In :doc:`aggregation pipeline `, the - :pipeline:`$match` pipeline stage provides access to MongoDB - queries. - -.. [#findOne] - The :method:`db.collection.findOne()` method also performs a read - operation to return a single document. Internally, the - :method:`db.collection.findOne()` method is the - :method:`db.collection.find()` method with a limit of 1. +.. tabs:: + + tabs: + - id: shell + content: | + - :method:`db.collection.findOne` + + - In :doc:`aggregation pipeline `, the + :pipeline:`$match` pipeline stage provides access to MongoDB + queries. + + .. note:: + The :method:`db.collection.findOne()` method also performs a read + operation to return a single document. Internally, the + :method:`db.collection.findOne()` method is the + :method:`db.collection.find()` method with a limit of 1. + + - id: python + content: | + - :py:meth:`pymongo.collection.Collection.find_one` + + - In :doc:`aggregation pipeline `, the + :pipeline:`$match` pipeline stage provides access to MongoDB + queries. See the `PyMongo Aggregation Examples `_. + + .. note:: + The :py:meth:`pymongo.collection.Collection.find_one` + method also performs a read operation to return a single + document. Internally, the + :py:meth:`pymongo.collection.Collection.find_one` method is + the :py:meth:`pymongo.collection.Collection.find` method + with a limit of 1. diff --git a/source/tutorial/query-embedded-documents.txt b/source/tutorial/query-embedded-documents.txt index 303cf2a20b8..158ab73c55b 100644 --- a/source/tutorial/query-embedded-documents.txt +++ b/source/tutorial/query-embedded-documents.txt @@ -11,28 +11,11 @@ Query on Embedded/Nested Documents :description: MongoDB Manual: How to query on embedded documents/nested documents/subdocuments/nested fields. Query/select by embedded documents/nested fields/subdocuments. :keywords: filter on embedded documents, nested documents, subdocuments, nested fields, field is embedded document, queries, select, MongoDB, greater than, logical AND, compound conditions, select from collection -This page provides examples of how to query on embedded/nested -documents in MongoDB. The examples on this page use the ``inventory`` -collection. To populate the ``inventory`` collection, run the following -in the :program:`mongo` shell: +.. |query_operations| replace:: query operations on embedded/nested documents -.. class:: copyable-code +.. include:: /includes/driver-example-query-intro.rst -.. code-block:: javascript - - db.inventory.insertMany( [ - { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, - { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "A" }, - { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, - { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, - { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" } - ]); - -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-query-14.rst Match an Embedded/Nested Document --------------------------------- @@ -44,22 +27,14 @@ document, use the query filter document ``{ : }`` where For example, the following query selects all documents where the field ``size`` equals the document ``{ h: 14, w: 21, uom: "cm" }``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) +.. include:: /includes/driver-example-query-15.rst Equality matches on the whole embedded document require an *exact* match of the specified ```` document, including the field order. For example, the following query does not match any documents in the ``inventory`` collection: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { size: { w: 21, h: 14, uom: "cm" } } ) +.. include:: /includes/driver-example-query-16.rst Query on Nested Field --------------------- @@ -73,11 +48,7 @@ Specify Equality Match on a Nested Field The following example selects all documents where the field ``uom`` nested in the ``size`` field equals ``"in"``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "size.uom": "in" } ) +.. include:: /includes/driver-example-query-17.rst Specify Match using Query Operator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -87,11 +58,7 @@ Specify Match using Query Operator The following query uses the less than operator (:query:`$lt`) on the field ``h`` embedded in the ``size`` field: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "size.h": { $lt: 15 } } ) +.. include:: /includes/driver-example-query-18.rst Specify ``AND`` Condition ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -100,11 +67,7 @@ The following query selects all documents where the nested field ``h`` is less than ``15``, the nested field ``uom`` equals ``"in"``, and the ``status`` field equals ``"D"``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { "size.h": { $lt: 15 }, "size.uom": "in", status: "D" } ) +.. include:: /includes/driver-example-query-19.rst Additional Query Tutorials -------------------------- diff --git a/source/tutorial/query-for-null-fields.txt b/source/tutorial/query-for-null-fields.txt index ea64ef8b60e..d9a56856345 100644 --- a/source/tutorial/query-for-null-fields.txt +++ b/source/tutorial/query-for-null-fields.txt @@ -14,26 +14,20 @@ Query for Null or Missing Fields Different query operators in MongoDB treat ``null`` values differently. -The examples on this page use the :method:`db.collection.find()` method -in the :program:`mongo` shell to query for ``null`` values. The -examples on this page use the ``inventory`` collection. To populate the -``inventory`` collection, run the following in the :program:`mongo` -shell: +.. |query_operations| replace:: operations that query for ``null`` values -.. class:: copyable-code +.. include:: /includes/driver-example-query-intro.rst -.. code-block:: javascript +.. tabs:: - db.inventory.insertMany([ - { _id: 1, item: null }, - { _id: 2 } - ]) + tabs: + - id: python + content: | + .. important:: + You must use ``None`` with the PyMongo Python driver to + query for ``null`` or missing fields in MongoDB. -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-query-38.rst .. _faq-comparison-with-null: @@ -46,11 +40,7 @@ do not contain the ``item`` field. For example, the following query returns both documents: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { item: null } ) +.. include:: /includes/driver-example-query-39.rst Type Check ---------- @@ -60,11 +50,7 @@ contains the ``item`` field whose value is ``null`` *only*; i.e. the value of the ``item`` field is of BSON Type ``Null`` (i.e. ``10``) : -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.find( { item : { $type: 10 } } ) +.. include:: /includes/driver-example-query-40.rst The query returns only the document where the ``item`` field has a ``null`` value. @@ -72,14 +58,20 @@ The query returns only the document where the ``item`` field has a Existence Check --------------- -The ``{ item : { $exists: false } }`` query matches documents -that do not contain the ``item`` field: +.. tabs:: -.. class:: copyable-code + tabs: + - id: shell + content: | + The ``{ item : { $exists: false } }`` query matches documents + that do not contain the ``item`` field: -.. code-block:: javascript + - id: python + content: | + The ``{ item : { $exists: False } }`` query matches documents + that do not contain the ``item`` field: - db.inventory.find( { item : { $exists: false } } ) +.. include:: /includes/driver-example-query-41.rst The query returns only the document that does *not* contain the ``item`` field: diff --git a/source/tutorial/remove-documents.txt b/source/tutorial/remove-documents.txt index adbb84e2e95..1f7d3f7d4ca 100644 --- a/source/tutorial/remove-documents.txt +++ b/source/tutorial/remove-documents.txt @@ -1,3 +1,5 @@ +.. include:: /includes/templates/tabs.rst + .. _write-op-delete: ================ @@ -10,54 +12,57 @@ Delete Documents :description: MongoDB Manual: How to delete documents in MongoDB. How to remove documents in MongoDB. How to specify conditions for removing or deleting documents in MongoDB. :keywords: delete from collection, remove documents from collection, delete documents from collection, MongoDB Manual -This page provides examples of delete operations in the -:program:`mongo` shell. - -The examples on this page use the ``inventory`` collection. To create -and/or populate the ``inventory`` collection, run the following in the -:program:`mongo` shell: - -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.insertMany( [ - { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, - { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" }, - { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, - { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, - { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }, - ]); - -.. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst +.. tabs:: + + tabs: + - id: shell + content: | + This page provides examples of delete operations using the + following methods in the :program:`mongo` shell: + + - :method:`db.collection.deleteMany()` + - :method:`db.collection.deleteOne()` + + - id: python + content: | + This page provides examples of delete operations using the + following methods in the `PyMongo `_ + Python driver: + + - :py:meth:`pymongo.collection.Collection.delete_many` + - :py:meth:`pymongo.collection.Collection.delete_one` + +The examples on this page use the ``inventory`` collection. To populate +the ``inventory`` collection, run the following: + +.. include:: /includes/driver-example-delete-55.rst .. _write-op-deleteMany: Delete All Documents -------------------- -To remove all documents from a collection, pass an empty :ref:`filter -` document ``{}`` to the -:method:`db.collection.deleteMany()` method. - -``db.collection.deleteMany()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs:: -The following example uses the :method:`db.collection.deleteMany()` -method to delete *all* documents from the ``inventory`` collection: + tabs: + - id: shell + content: | + To remove all documents from a collection, pass an empty + :ref:`filter` document ``{}`` to the + :method:`db.collection.deleteMany()` method. -.. class:: copyable-code + - id: python + content: | + To remove all documents from a collection, pass an empty + :ref:`filter` document ``{}`` to the + :py:meth:`pymongo.collection.Collection.delete_many` method. -.. code-block:: javascript +The following example deletes *all* documents from the ``inventory`` +collection: - db.inventory.deleteMany({}) +.. include:: /includes/driver-example-delete-56.rst -The method returns a document with the status of the operation. For -more information and examples, see :method:`db.collection.deleteMany()`. +.. include:: /includes/driver-example-delete-result.rst Delete All Documents that Match a Condition ------------------------------------------- @@ -70,43 +75,51 @@ syntax as read operations: - .. include:: /includes/extracts/filter-query-operators.rst -To delete all documents that match a deletion criteria, pass a -:ref:`filter ` parameter to the -:method:`db.collection.deleteMany()` method. +.. tabs:: -``db.collection.deleteMany()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + tabs: + - id: shell + content: | + To delete all documents that match a deletion criteria, pass a + :ref:`filter ` parameter to the + :method:`~db.collection.deleteMany()` method. -The following example uses :method:`db.collection.deleteMany()` to -remove all documents from the ``inventory`` collection where the ``status`` -field equals ``"A"``: + - id: python + content: | + To delete all documents that match a deletion criteria, pass a + :ref:`filter ` parameter to the + :py:meth:`~pymongo.collection.Collection.delete_many` method. -.. class:: copyable-code +The following example removes all documents from the ``inventory`` +collection where the ``status`` field equals ``"A"``: -.. code-block:: javascript +.. include:: /includes/driver-example-delete-57.rst - db.inventory.deleteMany({ status : "A" }) - -The method returns a document with the status of the operation. +.. include:: /includes/driver-example-delete-result.rst Remove Only One Document that Matches a Condition ------------------------------------------------- -To delete at most a single document that match a specified filter,even -though multiple documents may match the specified filter, use the -:method:`db.collection.deleteOne()` method. - -``db.collection.deleteOne()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs:: -The following example uses :method:`db.collection.deleteOne()` to -delete the *first* document where ``status`` is ``"D"``. + tabs: + - id: shell + content: | + To delete at most a single document that matches a specified + filter (even though multiple documents may match the specified + filter) use the :method:`db.collection.deleteOne()` method. -.. class:: copyable-code + - id: python + content: | + To delete at most a single document that matches a specified + filter (even though multiple documents may match the specified + filter) use the + :py:meth:`pymongo.collection.Collection.delete_one` method. -.. code-block:: javascript +The following example deletes the *first* document where ``status`` is +``"D"``. - db.inventory.deleteOne( { status: "D" } ) +.. include:: /includes/driver-example-delete-58.rst .. _write-op-delete-behavior: .. _write-op-remove-behavior: @@ -134,13 +147,28 @@ With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see :doc:`/reference/write-concern`. -.. seealso:: +.. tabs:: + + tabs: + - id: shell + content: | + .. seealso:: + + - :method:`db.collection.deleteMany()` + + - :method:`db.collection.deleteOne()` - - :method:`db.collection.deleteMany()` + - :ref:`additional-deletes` - - :method:`db.collection.deleteOne()` + - id: python + content: | + .. seealso:: + + - :py:meth:`pymongo.collection.Collection.delete_many` + + - :py:meth:`pymongo.collection.Collection.delete_one` - - :ref:`additional-deletes` + - :ref:`additional-deletes` .. class:: hidden diff --git a/source/tutorial/update-documents.txt b/source/tutorial/update-documents.txt index 8cc1e0388d7..6eaf1babdf0 100644 --- a/source/tutorial/update-documents.txt +++ b/source/tutorial/update-documents.txt @@ -1,3 +1,5 @@ +.. include:: /includes/templates/tabs.rst + .. _write-op-update: ================ @@ -10,41 +12,36 @@ Update Documents :description: How to update documents in MongoDB. How to update a single document in MongoDB. How to update multiple documents in MongoDB. How to update all documents in MongoDB. How to update fields in documents in MongoDB. How to replace documents. :keywords: update documents, update all documents, update single document, modify documents, update fields in documents, update collection, MongoDB Manual -This page provides examples of how to update documents in MongoDB. The -examples use the following methods in the :program:`mongo` shell: - -- ``db.collection.updateOne(, , )`` - -- ``db.collection.updateMany(, , )`` +.. tabs:: -- ``db.collection.replaceOne(, , )`` - -The examples on this page use the ``inventory`` collection. To create -and/or populate the ``inventory`` collection, run the following in the -:program:`mongo` shell: + tabs: + - id: shell + content: | + This page provides examples of how to update documents in + using the following methods in the :program:`mongo` shell: -.. class:: copyable-code + - ``db.collection.updateOne(, , )`` -.. code-block:: javascript + - ``db.collection.updateMany(, , )`` - db.inventory.insertMany( [ - { item: "canvas", qty: 100, size: { h: 28, w: 35.5, uom: "cm" }, status: "A" }, - { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, - { item: "mat", qty: 85, size: { h: 27.9, w: 35.5, uom: "cm" }, status: "A" }, - { item: "mousepad", qty: 25, size: { h: 19, w: 22.85, uom: "cm" }, status: "P" }, - { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" }, - { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }, - { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }, - { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }, - { item: "sketchbook", qty: 80, size: { h: 14, w: 21, uom: "cm" }, status: "A" }, - { item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" } - ]); + - ``db.collection.replaceOne(, , )`` -.. only:: website + - id: python + content: | + This page provides examples of how to update documents using the + following methods in the `PyMongo `_ + Python driver: + + - :py:meth:`pymongo.collection.Collection.update_one` + + - :py:meth:`pymongo.collection.Collection.update_many` + + - :py:meth:`pymongo.collection.Collection.replace_one` - You can run the operation in the web shell below: +The examples on this page use the ``inventory`` collection. To create +and/or populate the ``inventory`` collection, run the following: - .. include:: /includes/fact-mws.rst +.. include:: /includes/driver-example-update-51.rst .. _update-documents-modifiers: @@ -70,24 +67,27 @@ the field does not exist. See the individual :manual:`update operator .. _write-op-updateOne: -Update Documents via ``db.collection.updateOne()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Update a Single Document +~~~~~~~~~~~~~~~~~~~~~~~~ -The following example uses the :method:`db.collection.updateOne()` -method on the ``inventory`` collection to update the *first* document -where ``item`` equals ``"paper"``. +.. tabs:: -.. class:: copyable-code + 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"``: -.. code-block:: javascript + - 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"``: - db.inventory.updateOne( - { item: "paper" }, - { - $set: { "size.uom": "cm", status: "P" }, - $currentDate: { lastModified: true } - } - ) +.. include:: /includes/driver-example-update-52.rst The update operation: @@ -100,32 +100,31 @@ The update operation: does not exist, :update:`$currentDate` will create the field. See :update:`$currentDate` for details. -For more information and examples, see -:method:`db.collection.updateOne()`. - .. _update-multiple-documents: .. _write-op-updateMany: -Update Documents via ``db.collection.updateMany()`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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``. +.. tabs:: -.. class:: copyable-code + tabs: + - id: shell + content: | + The following example uses the :method:`db.collection.updateMany()` + method on the ``inventory`` collection to update all documents where + ``qty`` is less than ``50``: -.. code-block:: javascript + - id: python + content: | + 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``: - db.inventory.updateMany( - { "qty": { $lt: 50 } }, - { - $set: { "size.uom": "in", status: "P" }, - $currentDate: { lastModified: true } - } - ) +.. include:: /includes/driver-example-update-53.rst The update operation: @@ -138,15 +137,25 @@ The update operation: does not exist, :update:`$currentDate` will create the field. See :update:`$currentDate` for details. -For more information and examples, see -:method:`db.collection.updateMany()`. - -Replace the 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 -:method:`db.collection.replaceOne()`. When replacing a document, the +.. tabs:: + + tabs: + - id: shell + content: | + 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()`. + + - id: python + content: | + 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`. + +When replacing a document, the replacement document must consist of only `` : `` pairs; i.e. do not include :manual:`update operators ` expressions. @@ -158,21 +167,11 @@ since the ``_id`` field is immutable; however, if you do include the .. _write-op-replaceOne: -Replace a Document via ``db.collection.replaceOne`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following example uses the :method:`db.collection.replaceOne()` -method on the ``inventory`` collection to replace the *first* document -matches the filter ``item`` equals ``"paper"``: +The following example replaces the *first* document from the +``inventory`` collection that matches the filter ``item`` equals +``"paper"``: -.. class:: copyable-code - -.. code-block:: javascript - - db.inventory.replaceOne( - { item: "paper" }, - { item: "paper", instock: [ { warehouse: "A", qty: 60 }, { warehouse: "B", qty: 40 } ] } - ) +.. include:: /includes/driver-example-update-54.rst Behavior -------- @@ -207,13 +206,27 @@ Field Order ``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. +.. tabs:: + + tabs: + - id: shell + content: | + 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. + + - id: python + content: | + 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. @@ -225,17 +238,34 @@ With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see :doc:`/reference/write-concern`. -.. include:: /includes/footnote-set-shell-batch-size.rst +.. tabs:: + + tabs: + - id: shell + content: | + .. include:: /includes/footnote-set-shell-batch-size.rst + + .. seealso:: -.. seealso:: + - :method:`db.collection.updateOne()` - - :method:`db.collection.updateOne()` + - :method:`db.collection.updateMany()` - - :method:`db.collection.updateMany()` + - :method:`db.collection.replaceOne()` - - :method:`db.collection.replaceOne()` + - :ref:`additional-updates` - - :ref:`additional-updates` + - id: python + content: | + .. seealso:: + + - :py:meth:`pymongo.collection.Collection.update_one` + + - :py:meth:`pymongo.collection.Collection.update_many` + + - :py:meth:`pymongo.collection.Collection.replace_one` + + - :ref:`additional-updates` .. class:: hidden