diff --git a/source/includes/cursors/cursors-async.py b/source/includes/cursors/cursors-async.py new file mode 100644 index 00000000..a96a6e22 --- /dev/null +++ b/source/includes/cursors/cursors-async.py @@ -0,0 +1,29 @@ +# start-cursor-iterate +results = collection.find() + +async for document in results: + print(document) +# end-cursor-iterate + +# start-cursor-next +results = collection.find({ "name": "Dunkin' Donuts" }) + +print(await results.next()) +# end-cursor-next + +# start-cursor-list +results = collection.find({ "name": "Dunkin' Donuts" }) + +all_results = await to_list(results) + +for document in all_results: + print(document) +# end-cursor-list + +# start-cursor-close +results = collection.find() + +... + +await results.close() +# end-cursor-close \ No newline at end of file diff --git a/source/includes/cursors/tailable-cursor.py b/source/includes/cursors/tailable-cursor.py index d2d4af4e..393c6f0b 100644 --- a/source/includes/cursors/tailable-cursor.py +++ b/source/includes/cursors/tailable-cursor.py @@ -1,3 +1,4 @@ +# start-tailable-cursor oplog = client.local.oplog.rs first = oplog.find().sort('$natural', pymongo.ASCENDING).limit(-1).next() print(first) @@ -13,4 +14,24 @@ # You end up here if the find() method returns no documents, or if # no new documents are added to the collection for more than 1 second. - time.sleep(1) \ No newline at end of file + time.sleep(1) +# end-tailable-cursor + +# start-tailable-cursor-async +oplog = client.local.oplog.rs +first = await oplog.find().sort('$natural', pymongo.ASCENDING).limit(-1).next() +print(first) +ts = first['ts'] + +while True: + cursor = oplog.find({'ts': {'$gt': ts}}, + cursor_type=pymongo.CursorType.TAILABLE_AWAIT) + while cursor.alive: + async for doc in cursor: + ts = doc['ts'] + print(doc) + + # You end up here if the find() method returns no documents, or if + # no new documents are added to the collection for more than 1 second. + await asyncio.sleep(1) +# end-tailable-cursor-async \ No newline at end of file diff --git a/source/includes/project/project-async.py b/source/includes/project/project-async.py new file mode 100644 index 00000000..c6a5ea7e --- /dev/null +++ b/source/includes/project/project-async.py @@ -0,0 +1,20 @@ +# start-project-include +results = restaurants.find({ "name" : "Emerald Pub"}, {"name": 1, "cuisine": 1, "borough": 1}) + +async for restaurant in results: + print(restaurant) +# end-project-include + +# start-project-include-without-id +results = restaurants.find({ "name" : "Emerald Pub"}, {"_id": 0, "name": 1, "cuisine": 1, "borough": 1}) + +async for restaurant in results: + print(restaurant) +# end-project-include-without-id + +# start-project-exclude +results = restaurants.find({ "name" : "Emerald Pub"}, {"grades": 0, "address": 0} ) + +async for restaurant in results: + print(restaurant) +# end-project-exclude \ No newline at end of file diff --git a/source/includes/read/change-streams-async.py b/source/includes/read/change-streams-async.py new file mode 100644 index 00000000..9381da57 --- /dev/null +++ b/source/includes/read/change-streams-async.py @@ -0,0 +1,38 @@ +# start-open-change-stream +database = client["sample_restaurants"] +collection = database["restaurants"] + +async with await collection.watch() as stream: + async for change in stream: + print(change) +# end-open-change-stream + +# start-update-for-change-stream +database = client["sample_restaurants"] +collection = database["restaurants"] + +query_filter = { "name": "Blarney Castle" } +update_operation = { '$set' : + { "cuisine": "Irish" } +} + +result = await collection.update_one(query_filter, update_operation) +# end-update-for-change-stream + +# start-change-stream-pipeline + +change_pipeline = { "$match": { "operationType": "update" }}, + +async with await collection.watch(pipeline=change_pipeline) as stream: + async for change in stream: + print(change) +# end-change-stream-pipeline + +# start-change-stream-post-image +database = client["sample_restaurants"] +collection = database["restaurants"] + +async with await collection.watch(full_document='updateLookup') as stream: + async for change in stream: + print(change) +# end-change-stream-post-image \ No newline at end of file diff --git a/source/includes/read/distinct-async.py b/source/includes/read/distinct-async.py new file mode 100644 index 00000000..f605ed1e --- /dev/null +++ b/source/includes/read/distinct-async.py @@ -0,0 +1,23 @@ +# start-distinct +results = await restaurants.distinct("borough") + +for restaurant in results: + print(restaurant) +# end-distinct + +# start-distinct-with-query +results = await restaurants.distinct("borough", { + "cuisine": "Italian" +}) + +for restaurant in results: + print(restaurant) +# end-distinct-with-query + +# start-distinct-with-comment +results = await restaurants.distinct("name", + { "borough": "Bronx", + "cuisine": "Pizza" }, + comment="Bronx pizza restaurants" +) +# end-distinct-with-comment \ No newline at end of file diff --git a/source/includes/read/specify-documents-to-return-async.py b/source/includes/read/specify-documents-to-return-async.py new file mode 100644 index 00000000..6660faa0 --- /dev/null +++ b/source/includes/read/specify-documents-to-return-async.py @@ -0,0 +1,58 @@ +# start-limit-method +results = restaurants.find({ "cuisine" : "Italian"}).limit(5) + +async for restaurant in results: + print(restaurant["name"]) +# end-limit-method + +# start-limit-option +results = restaurants.find({ "cuisine" : "Italian"}, limit=5) + +async for restaurant in results: + print(restaurant["name"]) +# end-limit-option + +# start-sort-method +results = restaurants.find({ "cuisine" : "Italian"}).sort("name", pymongo.ASCENDING) + +async for restaurant in results: + print(restaurant["name"]) +# end-sort-method + +# start-sort-option +results = restaurants.find({ "cuisine" : "Italian"}, sort={"name": pymongo.ASCENDING} ) + +async for restaurant in results: + print(restaurant["name"]) +# end-sort-option + +# start-skip +results = restaurants.find({ "borough" : "Manhattan"}).skip(10) + +async for restaurant in results: + print(restaurant["name"]) +# end-skip + +# start-skip-option +results = restaurants.find({ "borough" : "Manhattan"}, skip=10) + +async for restaurant in results: + print(restaurant["name"]) +# end-skip-option + +# start-limit-sort-skip +results = restaurants.find({ "cuisine" : "Italian"}) \ + .sort("name", pymongo.ASCENDING) \ + .limit(5) \ + .skip(10) + +async for restaurant in results: + print(restaurant["name"]) +# end-limit-sort-skip + +# start-limit-sort-skip-option +results = restaurants.find({ "cuisine" : "Italian"}, limit=5, sort={"name": pymongo.ASCENDING}, skip=10) + +async for restaurant in results: + print(restaurant["name"]) +# end-limit-sort-skip-option \ No newline at end of file diff --git a/source/includes/specify-query/specify-queries-async.py b/source/includes/specify-query/specify-queries-async.py new file mode 100644 index 00000000..8d34dabd --- /dev/null +++ b/source/includes/specify-query/specify-queries-async.py @@ -0,0 +1,64 @@ +# start-sample-data +from pymongo import AsyncMongoClient + +uri = "" +client = AsyncMongoClient(uri) + +try: + database = client["sample_fruit"] + collection = database["fruits"] + + await collection.insert_many([ + { "_id": 1, "name": "apples", "qty": 5, "rating": 3, "color": "red", "type": ["fuji", "honeycrisp"] }, + { "_id": 2, "name": "bananas", "qty": 7, "rating": 4, "color": "yellow", "type": ["cavendish"] }, + { "_id": 3, "name": "oranges", "qty": 6, "rating": 2, "type": ["naval", "mandarin"] }, + { "_id": 4, "name": "pineapple", "qty": 3, "rating": 5, "color": "yellow" }, + ]) + + await client.close() + +except Exception as e: + raise Exception("Error inserting documents: ", e) +# end-sample-data + +# start-find-comparison +results = collection.find({ "rating": { "$gt" : 2 }}) + +async for f in results: + print(f) +# end-find-comparison + +# start-find-logical +results = collection.find({ + "$or": [ + { "qty": { "$gt": 5 }}, + { "color": "yellow" } + ] +}) + +async for f in results: + print(f) +# end-find-logical + +# start-find-array +results = collection.find({ + "type" : { "$size": 2 } +}) + +async for f in results: + print(f) +# end-find-array + +# start-find-element +results = collection.find( { "color" : { "$exists": "true" }} ) + +async for f in results: + print(f) +# end-find-element + +# start-find-evaluation +results = collection.find({ "name" : { "$regex" : "p{2,}" }} ) + +async for f in results: + print(f) +# end-find-evaluation \ No newline at end of file diff --git a/source/includes/usage-examples/retrieve-code-examples-async.py b/source/includes/usage-examples/retrieve-code-examples-async.py new file mode 100644 index 00000000..d844b03f --- /dev/null +++ b/source/includes/usage-examples/retrieve-code-examples-async.py @@ -0,0 +1,39 @@ +# start-find-one +results = await collection.find_one({ "" : "" }) + +print(results) +# end-find-one +# start-find +results = collection.find({ "" : "" }) + +async for document in results: + print(document) +# end-find +# start-count-all +count = await collection.count_documents({}) + +print(count) +#end-count-all +# start-count-query +count = await collection.count_documents({ "": "" }) + +print(count) +# end-count-query + +# start-estimated-count +count = await collection.estimated_document_count() + +print(count) +# end-estimated-count +# start-distinct +results = await collection.distinct("") + +for document in results: + print(document) +# end-distinct + +# start-watch-for-changes +async with await collection.watch() as stream: + async for change in stream: + print(change) +# end-watch-for-changes \ No newline at end of file diff --git a/source/includes/usage-examples/sample-app-async.py b/source/includes/usage-examples/sample-app-async.py new file mode 100644 index 00000000..ff4166ca --- /dev/null +++ b/source/includes/usage-examples/sample-app-async.py @@ -0,0 +1,23 @@ +import asyncio +import pymongo +from pymongo import AsyncMongoClient + +async def main(): + try: + uri = "" + client = AsyncMongoClient(uri) + + database = client[""] + collection = database[""] + + # start example code here + + # end example code here + + await client.close() + + except Exception as e: + raise Exception( + "The following error occurred: ", e) + +asyncio.run(main()) \ No newline at end of file diff --git a/source/read.txt b/source/read.txt index 5fe466b0..85bf043e 100644 --- a/source/read.txt +++ b/source/read.txt @@ -51,20 +51,47 @@ the relevant values for your MongoDB deployment. .. include:: /includes/usage-examples/sample-app-intro.rst -.. literalinclude:: /includes/usage-examples/sample-app.py - :language: python - :copyable: - :linenos: - :emphasize-lines: 11-13 +Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding +code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/sample-app.py + :language: python + :copyable: + :linenos: + :emphasize-lines: 11-13 + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/sample-app-async.py + :language: python + :copyable: + :linenos: + :emphasize-lines: 11-13 Find One -------- -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-find-one - :end-before: end-find-one - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-find-one + :end-before: end-find-one + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-find-one + :end-before: end-find-one To learn more about the ``find_one()`` method, see :ref:`pymongo-retrieve-find-one` in the Retrieve Data guide. @@ -72,11 +99,21 @@ the Retrieve Data guide. Find Multiple ------------- -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-find - :end-before: end-find - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-find + :end-before: end-find + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-find + :end-before: end-find To learn more about the ``find()`` method, see :ref:`pymongo-retrieve-find-multiple` in the Retrieve Data guide. @@ -84,11 +121,21 @@ the Retrieve Data guide. Count Documents in a Collection ------------------------------- -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-count-all - :end-before: end-count-all - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-count-all + :end-before: end-count-all + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-count-all + :end-before: end-count-all To learn more about the ``count_documents()`` method, see the :ref:`pymongo-accurate-count` guide. @@ -96,11 +143,21 @@ To learn more about the ``count_documents()`` method, see the Count Documents Returned from a Query ------------------------------------- -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-count-query - :end-before: end-count-query - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-count-query + :end-before: end-count-query + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-count-query + :end-before: end-count-query To learn more about the ``count_documents()`` method, see the :ref:`pymongo-accurate-count` guide. @@ -108,11 +165,21 @@ To learn more about the ``count_documents()`` method, see the Estimated Document Count ------------------------ -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-estimated-count - :end-before: end-estimated-count - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-estimated-count + :end-before: end-estimated-count + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-estimated-count + :end-before: end-estimated-count To learn more about the ``estimated_document_count()`` method, see the :ref:`pymongo-estimated-count` guide. @@ -120,11 +187,21 @@ To learn more about the ``estimated_document_count()`` method, see the Retrieve Distinct Values ------------------------ -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-distinct - :end-before: end-distinct - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-distinct + :end-before: end-distinct + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-distinct + :end-before: end-distinct To learn more about the ``distinct()`` method, see the :ref:`pymongo-distinct` guide. @@ -132,11 +209,21 @@ To learn more about the ``distinct()`` method, see the Monitor Data Changes -------------------- -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-watch-for-changes - :end-before: end-watch-for-changes - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-watch-for-changes + :end-before: end-watch-for-changes + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/usage-examples/retrieve-code-examples-async.py + :start-after: start-watch-for-changes + :end-before: end-watch-for-changes To learn more about the ``watch()`` method, see the :ref:`pymongo-change-streams` guide. \ No newline at end of file diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 318aae5a..f28da475 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -46,23 +46,51 @@ classes: - ``Collection``: To monitor changes in the collection The following example opens a change stream on the ``restaurants`` collection -and outputs changes as they occur: +and outputs changes as they occur. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: -.. literalinclude:: /includes/read/change-streams.py - :start-after: start-open-change-stream - :end-before: end-open-change-stream - :language: python +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/read/change-streams.py + :start-after: start-open-change-stream + :end-before: end-open-change-stream + :language: python + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/read/change-streams-async.py + :start-after: start-open-change-stream + :end-before: end-open-change-stream + :language: python To begin watching for changes, run the application. Then, in a separate application or shell, modify the ``restaurants`` collection. The following -example updates a document with a ``name`` field value of ``Blarney Castle``: +example updates a document with a ``name`` field value of ``Blarney Castle``. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: .. _pymongo-change-stream-update: -.. literalinclude:: /includes/read/change-streams.py - :start-after: start-update-for-change-stream - :end-before: end-update-for-change-stream - :language: python +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/read/change-streams.py + :start-after: start-update-for-change-stream + :end-before: end-update-for-change-stream + :language: python + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/read/change-streams-async.py + :start-after: start-update-for-change-stream + :end-before: end-update-for-change-stream + :language: python When you update the collection, the change stream application prints the change as it occurs. The printed change event resembles the @@ -94,12 +122,26 @@ You can specify the following stages in the ``pipeline`` parameter: - ``$unset`` The following example uses the ``pipeline`` parameter to open a change stream -that records only update operations: +that records only update operations. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync -.. literalinclude:: /includes/read/change-streams.py - :start-after: start-change-stream-pipeline - :end-before: end-change-stream-pipeline - :language: python + .. literalinclude:: /includes/read/change-streams.py + :start-after: start-change-stream-pipeline + :end-before: end-change-stream-pipeline + :language: python + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/read/change-streams-async.py + :start-after: start-change-stream-pipeline + :end-before: end-change-stream-pipeline + :language: python To learn more about modifying your change stream output, see the :manual:`Modify Change Stream Output @@ -222,12 +264,26 @@ one of the following values: driver raises an error. The following example calls the ``watch()`` method on a collection and includes the post-image -of updated documents by specifying the ``fullDocument`` parameter: - -.. literalinclude:: /includes/read/change-streams.py - :start-after: start-change-stream-post-image - :end-before: end-change-stream-post-image - :language: python +of updated documents by specifying the ``fullDocument`` parameter. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/read/change-streams.py + :start-after: start-change-stream-post-image + :end-before: end-change-stream-post-image + :language: python + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/read/change-streams-async.py + :start-after: start-change-stream-post-image + :end-before: end-change-stream-post-image + :language: python With the change stream application running, updating a document in the ``restaurants`` collection by using the :ref:`preceding update example diff --git a/source/read/count.txt b/source/read/count.txt index b6262c3f..5f35c18e 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -39,21 +39,47 @@ Count All Documents ~~~~~~~~~~~~~~~~~~~ To return a count of all documents in the collection, pass an empty dictionary to -the ``count_documents()`` method, as shown in the following example: +the ``count_documents()`` method, as shown in the following example. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. code-block:: python +.. tabs:: - collection.count_documents({}) + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python + + collection.count_documents({}) + + .. tab:: Asynchronous + :tabid: async + + .. code-block:: python + + await collection.count_documents({}) Count Specific Documents ~~~~~~~~~~~~~~~~~~~~~~~~ To return a count of documents that match specific search criteria, specify your -query in the ``count_documents()`` method, as shown in the following example: +query in the ``count_documents()`` method, as shown in the following example. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python -.. code-block:: python - - collection.count_documents({ "author": "Mike" }) + collection.count_documents({ "author": "Mike" }) + + .. tab:: Asynchronous + :tabid: async + + .. code-block:: python + + await collection.count_documents({ "author": "Mike" }) Customize Count Behavior ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -103,11 +129,24 @@ the ``estimated_document_count()`` method. The method estimates the amount of documents based on collection metadata, which might be faster than performing an accurate count. -The following example estimates the number of documents in a collection: +The following example estimates the number of documents in a collection. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python + + collection.estimated_document_count() + + .. tab:: Asynchronous + :tabid: async + + .. code-block:: python -.. code-block:: python - - collection.estimated_document_count() + await collection.estimated_document_count() Customize Estimated Count Behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/read/cursors.txt b/source/read/cursors.txt index c818b1ae..d7520ea6 100644 --- a/source/read/cursors.txt +++ b/source/read/cursors.txt @@ -43,13 +43,26 @@ Access Cursor Contents Iteratively ---------------------------------- To iterate over the contents of a cursor, use a ``for`` loop, as shown in the -following example: +following example. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to +see the corresponding code: -.. literalinclude:: /includes/cursors/cursors.py - :start-after: start-cursor-iterate - :end-before: end-cursor-iterate - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/cursors/cursors.py + :start-after: start-cursor-iterate + :end-before: end-cursor-iterate + :language: python + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/cursors/cursors-async.py + :start-after: start-cursor-iterate + :end-before: end-cursor-iterate + :language: python Retrieve Documents Individually ------------------------------- @@ -58,19 +71,42 @@ Retrieve documents from a cursor individually by calling the ``next()`` method. The following example finds all documents in a collection with a ``name`` value of ``"Dunkin' Donuts"``. It then prints the first document in the cursor by calling the -``next()`` method. +``next()`` method. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to +see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable + + .. input:: /includes/cursors/cursors.py + :start-after: start-cursor-next + :end-before: end-cursor-next + :language: python + + .. output:: + :visible: false + + {'_id': ObjectId('...'), 'address': { ... }, 'borough': 'Bronx', 'cuisine': 'Donuts', 'grades': [...], 'name': "Dunkin' Donuts", 'restaurant_id': '40379573'} -.. io-code-block:: - :copyable: + .. tab:: Asynchronous + :tabid: async - .. input:: /includes/cursors/cursors.py - :start-after: start-cursor-next - :end-before: end-cursor-next - :language: python + .. io-code-block:: + :copyable - .. output:: + .. input:: /includes/cursors/cursors-async.py + :start-after: start-cursor-next + :end-before: end-cursor-next + :language: python + + .. output:: + :visible: false - {'_id': ObjectId('...'), 'address': { ... }, 'borough': 'Bronx', 'cuisine': 'Donuts', 'grades': [...], 'name': "Dunkin' Donuts", 'restaurant_id': '40379573'} + {'_id': ObjectId('...'), 'address': { ... }, 'borough': 'Bronx', 'cuisine': 'Donuts', 'grades': [...], 'name': "Dunkin' Donuts", 'restaurant_id': '40379573'} Retrieve All Documents ---------------------- @@ -81,29 +117,56 @@ Retrieve All Documents application memory, your program will crash. If you expect a large result set, :ref:`access your cursor iteratively `. -To retrieve all documents from a cursor, convert the cursor into a ``list`` as -shown in the following example: +To retrieve all documents from a cursor, convert the cursor into a ``list``, as +shown in the following example. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: -.. literalinclude:: /includes/cursors/cursors.py - :start-after: start-cursor-list - :end-before: end-cursor-list - :language: python - :copyable: - :emphasize-lines: 3 +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/cursors/cursors.py + :start-after: start-cursor-list + :end-before: end-cursor-list + :copyable: + :emphasize-lines: 3 + :language: python + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/cursors/cursors-async.py + :start-after: start-cursor-list + :end-before: end-cursor-list + :emphasize-lines: 3 + :language: python Close a Cursor -------------- By default, MongoDB closes a cursor when the client has exhausted all the results in the cursor. To explicitly close a cursor, call the ``close()`` method -as shown in the following example: +as shown in the following example. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync -.. literalinclude:: /includes/cursors/cursors.py - :start-after: start-cursor-close - :end-before: end-cursor-close - :emphasize-lines: 5 - :language: python - :copyable: + .. literalinclude:: /includes/cursors/cursors.py + :start-after: start-cursor-close + :end-before: end-cursor-close + :emphasize-lines: 5 + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/cursors/cursors-async.py + :start-after: start-cursor-close + :end-before: end-cursor-close + :emphasize-lines: 5 Tailable Cursors ---------------- @@ -115,12 +178,30 @@ specify ``CursorType.TAILABLE_AWAIT`` in the ``cursor_type`` option of a ``find()`` method. The following example uses a tailable cursor to tail the oplog -of a replica-set member: - -.. literalinclude:: /includes/cursors/tailable-cursor.py - :language: python - :copyable: - :emphasize-lines: 8 +of a replica-set member. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/cursors/tailable-cursor.py + :start-after: start-tailable-cursor + :end-before: end-tailable-cursor + :language: python + :copyable: + :emphasize-lines: 8 + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/cursors/tailable-cursor.py + :start-after: start-tailable-cursor-async + :end-before: end-tailable-cursor-async + :language: python + :copyable: + :emphasize-lines: 8 To learn more about tailable cursors, see the :manual:`Tailable Cursors guide ` in the {+mdb-server+} manual. diff --git a/source/read/distinct.txt b/source/read/distinct.txt index 8fb95e79..9dadf4c0 100644 --- a/source/read/distinct.txt +++ b/source/read/distinct.txt @@ -44,23 +44,50 @@ Retrieve Distinct Values Across a Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example retrieves the distinct values of the ``borough`` field in -the ``restaurants`` collection: +the ``restaurants`` collection. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` +tab to see the corresponding code: -.. io-code-block:: +.. tabs:: - .. input:: /includes/read/distinct.py - :start-after: start-distinct - :end-before: end-distinct - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: - Bronx - Brooklyn - Manhattan - Missing - Queens - Staten Island + .. input:: /includes/read/distinct.py + :start-after: start-distinct + :end-before: end-distinct + :language: python + + .. output:: + :visible: false + + Bronx + Brooklyn + Manhattan + Missing + Queens + Staten Island + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/distinct-async.py + :start-after: start-distinct + :end-before: end-distinct + :language: python + + .. output:: + :visible: false + + Bronx + Brooklyn + Manhattan + Missing + Queens + Staten Island The results show every distinct value that appears in the ``borough`` field across all documents in the collection. Although several documents have the same @@ -75,22 +102,48 @@ criteria used to match documents in an operation. For more information about creating a query filter, see :ref:`pymongo-specify-query`. The following example retrieves the distinct values of the ``borough`` field for -all documents that have a ``cuisine`` field value of ``"Italian"``: +all documents that have a ``cuisine`` field value of ``"Italian"``. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync -.. io-code-block:: + .. io-code-block:: - .. input:: /includes/read/distinct.py - :start-after: start-distinct-with-query - :end-before: end-distinct-with-query - :language: python + .. input:: /includes/read/distinct.py + :start-after: start-distinct-with-query + :end-before: end-distinct-with-query + :language: python - .. output:: + .. output:: + :visible: false - Bronx - Brooklyn - Manhattan - Queens - Staten Island + Bronx + Brooklyn + Manhattan + Queens + Staten Island + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/distinct-async.py + :start-after: start-distinct-with-query + :end-before: end-distinct-with-query + :language: python + + .. output:: + :visible: false + + Bronx + Brooklyn + Manhattan + Queens + Staten Island Modify Distinct Behavior ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -129,23 +182,50 @@ The following table describes the options you can set to customize The following example retrieves the distinct values of the ``name`` field for all documents that have a ``borough`` field value of ``"Bronx"`` and a ``cuisine`` field value of ``"Pizza"``. It also uses -the ``comment`` option to add a comment to the operation. - -.. io-code-block:: - - .. input:: /includes/read/distinct.py - :start-after: start-distinct-with-comment - :end-before: end-distinct-with-comment - :language: python - - .. output:: - - $1.25 Pizza - 18 East Gunhill Pizza - 2 Bros - Aenos Pizza - Alitalia Pizza Restaurant - ... +the ``comment`` option to add a comment to the operation. Select the :guilabel:`Synchronous` +or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/distinct.py + :start-after: start-distinct-with-comment + :end-before: end-distinct-with-comment + :language: python + + .. output:: + :visible: false + + $1.25 Pizza + 18 East Gunhill Pizza + 2 Bros + Aenos Pizza + Alitalia Pizza Restaurant + ... + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/distinct-async.py + :start-after: start-distinct-with-comment + :end-before: end-distinct-with-comment + :language: python + + .. output:: + :visible: false + + $1.25 Pizza + 18 East Gunhill Pizza + 2 Bros + Aenos Pizza + Alitalia Pizza Restaurant + ... API Documentation ----------------- diff --git a/source/read/project.txt b/source/read/project.txt index def9467c..0ffbc435 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -52,20 +52,44 @@ Use the following syntax to specify the fields to include in the result: The following example uses the ``find()`` method to find all restaurants with the ``name`` field value of ``"Emerald Pub"``. It then uses a projection to return only the ``name``, ``cuisine``, and ``borough`` fields in the returned -documents. +documents. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: -.. io-code-block:: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/project/project.py + :start-after: start-project-include + :end-before: end-project-include + :language: python + :emphasize-lines: 1 + + .. output:: + :visible: false + + {'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'} + {'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: - .. input:: /includes/project/project.py - :start-after: start-project-include - :end-before: end-project-include - :language: python - :emphasize-lines: 1 + .. input:: /includes/project/project-async.py + :start-after: start-project-include + :end-before: end-project-include + :language: python + :emphasize-lines: 1 - .. output:: + .. output:: + :visible: false - {'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'} - {'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'} + {'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'} + {'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'} When you use a projection to specify fields to include in the return document, the ``_id`` field is also included by default. All other fields are @@ -81,20 +105,44 @@ When specifying fields to include, you can also exclude the ``_id`` field from the returned document. The following example performs the same query as the preceding example, but -excludes the ``_id`` field from the projection: +excludes the ``_id`` field from the projection. Select the :guilabel:`Synchronous` +or :guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/project/project.py + :start-after: start-project-include-without-id + :end-before: end-project-include-without-id + :language: python + :emphasize-lines: 1 + + .. output:: + :visible: false + + {'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'} + {'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: - .. input:: /includes/project/project.py - :start-after: start-project-include-without-id - :end-before: end-project-include-without-id - :language: python - :emphasize-lines: 1 + .. input:: /includes/project/project-async.py + :start-after: start-project-include-without-id + :end-before: end-project-include-without-id + :language: python + :emphasize-lines: 1 - .. output:: + .. output:: + :visible: false - {'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'} - {'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'} + {'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub'} + {'borough': 'Queens', 'cuisine': 'American', 'name': 'Emerald Pub'} Specify Fields to Exclude ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -107,21 +155,46 @@ Use the following syntax to specify the fields to exclude from the result: The following example uses the ``find()`` method to find all restaurants with the ``name`` field value of ``"Emerald Pub"``. It then uses a projection to -exclude the ``grades`` and ``address`` fields from the returned documents: +exclude the ``grades`` and ``address`` fields from the returned documents. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: - .. input:: /includes/project/project.py - :start-after: start-project-exclude - :end-before: end-project-exclude - :language: python - :emphasize-lines: 1 + .. input:: /includes/project/project.py + :start-after: start-project-exclude + :end-before: end-project-exclude + :language: python + :emphasize-lines: 1 + + .. output:: + :visible: false - .. output:: + {'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub', 'restaurant_id': '40367329'} + {'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', + 'name': 'Emerald Pub', 'restaurant_id': '40668598'} - {'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub', 'restaurant_id': '40367329'} - {'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', - 'name': 'Emerald Pub', 'restaurant_id': '40668598'} + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/project/project-async.py + :start-after: start-project-exclude + :end-before: end-project-exclude + :language: python + :emphasize-lines: 1 + + .. output:: + :visible: false + + {'_id': ObjectId('...'), 'borough': 'Manhattan', 'cuisine': 'American', 'name': 'Emerald Pub', 'restaurant_id': '40367329'} + {'_id': ObjectId('...'), 'borough': 'Queens', 'cuisine': 'American', + 'name': 'Emerald Pub', 'restaurant_id': '40668598'} When you use a projection to specify which fields to exclude, any unspecified fields are implicitly included in the return document. diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 392e6ae3..615af03a 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -68,12 +68,26 @@ results as a Python dictionary. If no documents match the query filter, the meth or you're only interested in the first match. The following example uses the ``find_one()`` method to find the first document where -the ``"cuisine"`` field has the value ``"Bakery"``: +the ``"cuisine"`` field has the value ``"Bakery"``. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. code-block:: python - :copyable: true +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python + :copyable: true - restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"}) + restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"}) + + .. tab:: Asynchronous + :tabid: async + + .. code-block:: python + :copyable: true + + restaurant = await sample_restaurants.restaurants.find_one({"cuisine": "Bakery"}) .. tip:: Sort Order @@ -92,8 +106,7 @@ To find multiple documents in a collection, pass a query filter to the ``find()` method that specifies the criteria of the documents you want to retrieve. The following example uses the ``find()`` method to find all documents where -the ``"cuisine"`` field has the value ``"Spanish"``: - +the ``"cuisine"`` field has the value ``"Spanish"``. .. code-block:: python :copyable: true @@ -106,14 +119,30 @@ results while holding only a subset of them in memory at a given time. Cursors are useful when your ``find()`` method returns a large amount of documents. You can iterate over the documents in a cursor by using a ``for-in`` loop, as shown in -the following example: +the following example. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab +to see the corresponding code: -.. code-block:: python - :copyable: true +.. tabs:: - cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) - for restaurant in cursor: - ... + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python + :copyable: true + + cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) + for restaurant in cursor: + ... + + .. tab:: Asynchronous + :tabid: async + + .. code-block:: python + :copyable: true + + cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) + async for restaurant in cursor: + ... .. note:: Find All Documents diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt index f61c69c4..042747fc 100644 --- a/source/read/specify-a-query.txt +++ b/source/read/specify-a-query.txt @@ -43,13 +43,28 @@ The examples in this guide run operations on a collection called { "_id": 4, "name": "pineapple", "qty": 3, "rating": 5, "color": "yellow" }, The following code example shows how to create a database and collection, then -insert the sample documents into your collection: +insert the sample documents into your collection. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/specify-query/specify-queries.py - :start-after: start-sample-data - :end-before: end-sample-data - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/specify-query/specify-queries.py + :start-after: start-sample-data + :end-before: end-sample-data + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/specify-query/specify-queries-async.py + :start-after: start-sample-data + :end-before: end-sample-data + :language: python + :copyable: Exact Match ----------- @@ -68,6 +83,7 @@ method. The code returns all documents with a ``color`` field value of ``"yellow :language: python .. output:: + :visible: false {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} @@ -101,19 +117,43 @@ The following example specifies a comparison operator in a query filter as a parameter to the ``find()`` method. The code returns all documents with a ``rating`` field value greater than ``2``: -.. io-code-block:: - :copyable: +.. tabs:: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-comparison - :end-before: end-find-comparison - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: + :copyable: - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-comparison + :end-before: end-find-comparison + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries-async.py + :start-after: start-find-comparison + :end-before: end-find-comparison + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} Logical Operators ----------------- @@ -132,21 +172,46 @@ To learn more about logical operators, see the :manual:`Logical Query Operators The following example specifies a logical operator in a query filter as a parameter to the ``find()`` method. The code returns all documents with a ``qty`` field value greater than ``5`` **or** a ``color`` field value of -``"yellow"``: +``"yellow"``. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab +to see the corresponding code: -.. io-code-block:: - :copyable: +.. tabs:: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-logical - :end-before: end-find-logical - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: + :copyable: - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-logical + :end-before: end-find-logical + :language: python + + .. output:: + :visible: false + + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries-async.py + :start-after: start-find-logical + :end-before: end-find-logical + :language: python + + .. output:: + :visible: false + + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} Array Operators --------------- @@ -163,20 +228,44 @@ To learn more about array operators, see the :manual:`Array Query Operators The following example specifies an array operator in a query filter as a parameter to the ``find()`` method. The code returns all documents with a -``type`` array field containing ``2`` elements: +``type`` array field containing ``2`` elements. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: - :copyable: +.. tabs:: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-array - :end-before: end-find-array - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-array + :end-before: end-find-array + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} + + .. tab:: Asynchronous + :tabid: async - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} + .. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries-async.py + :start-after: start-find-array + :end-before: end-find-array + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} Element Operators ----------------- @@ -188,21 +277,46 @@ To learn more about element operators, see the :manual:`Element Query Operators The following example specifies an element operator in a query filter as a parameter to the ``find()`` method. The code returns all documents that have a -``color`` field: +``color`` field. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab +to see the corresponding code: -.. io-code-block:: - :copyable: +.. tabs:: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-element - :end-before: end-find-element - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: + :copyable: - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-element + :end-before: end-find-element + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries-async.py + :start-after: start-find-element + :end-before: end-find-element + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} Evaluation Operators -------------------- @@ -223,20 +337,44 @@ To view a full list of evaluation operators, see the :manual:`Evaluation Query O The following example specifies an evaluation operator in a query filter as a parameter to the ``find()`` method. The code uses a regular expression to return all documents with a ``name`` field value that has at least two consecutive -``"p"`` characters: +``"p"`` characters. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab +to see the corresponding code: -.. io-code-block:: - :copyable: +.. tabs:: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-evaluation - :end-before: end-find-evaluation - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: + :copyable: - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-evaluation + :end-before: end-find-evaluation + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries-async.py + :start-after: start-find-evaluation + :end-before: end-find-evaluation + :language: python + + .. output:: + :visible: false + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} Troubleshooting --------------- diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index e9d0b5ab..cd8e2eef 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -41,40 +41,92 @@ To specify the maximum number of documents returned from a read operation, call the ``limit()`` method. The following example finds all restaurants that have a ``cuisine`` field value -of ``"Italian"``, and limits the results to 5 documents: +of ``"Italian"``, and limits the results to 5 documents. Select the :guilabel:`Synchronous` +or :guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-limit-method - :end-before: end-limit-method - :language: python + .. io-code-block:: - .. output:: + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-limit-method + :end-before: end-limit-method + :language: python - Isle Of Capri Resturant Italian - Arturo'S Italian - Patsy'S Italian Restaurant Italian - Piccola Venezia Italian - Roadhouse Restaurant Italian + .. output:: + :visible: false + + Isle Of Capri Resturant Italian + Arturo'S Italian + Patsy'S Italian Restaurant Italian + Piccola Venezia Italian + Roadhouse Restaurant Italian + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-limit-method + :end-before: end-limit-method + :language: python + + .. output:: + :visible: false + + Isle Of Capri Resturant Italian + Arturo'S Italian + Patsy'S Italian Restaurant Italian + Piccola Venezia Italian + Roadhouse Restaurant Italian You can also limit the number of returned documents by specifying the ``limit`` -parameter in your ``find()`` method: +parameter in your ``find()`` method. Select the :guilabel:`Synchronous` +or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-limit-option + :end-before: end-limit-option + :language: python + + .. output:: + :visible: false + + Isle Of Capri Resturant Italian + Arturo'S Italian + Patsy'S Italian Restaurant Italian + Piccola Venezia Italian + Roadhouse Restaurant Italian + + .. tab:: Asynchronous + :tabid: async -.. io-code-block:: + .. io-code-block:: - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-limit-option - :end-before: end-limit-option - :language: python + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-limit-option + :end-before: end-limit-option + :language: python - .. output:: + .. output:: + :visible: false - Isle Of Capri Resturant Italian - Arturo'S Italian - Patsy'S Italian Restaurant Italian - Piccola Venezia Italian - Roadhouse Restaurant Italian + Isle Of Capri Resturant Italian + Arturo'S Italian + Patsy'S Italian Restaurant Italian + Piccola Venezia Italian + Roadhouse Restaurant Italian .. tip:: @@ -95,45 +147,101 @@ specify the sort direction, specify either ``pymongo.ASCENDING`` or direction, the method defaults to sorting in ascending order. The following example returns all documents with the ``cuisine`` value of -``"Italian"``, sorted in ascending order: +``"Italian"``, sorted in ascending order. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: +.. tabs:: - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-sort-method - :end-before: end-sort-method - :language: python + .. tab:: Synchronous + :tabid: sync - .. output:: + .. io-code-block:: - (Lewis Drug Store) Locanda Vini E Olii - 101 Restaurant And Bar - 44 Sw Ristorante & Bar - 900 Park - A Voce - ... - Zucchero E Pomodori + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-sort-method + :end-before: end-sort-method + :language: python -You can also sort documents by specifying the ``sort`` parameter in your ``find()`` -method. The following example specifies the ``sort`` parameter to return the -results in the same order as the preceding example: + .. output:: + :visible: false + + (Lewis Drug Store) Locanda Vini E Olii + 101 Restaurant And Bar + 44 Sw Ristorante & Bar + 900 Park + A Voce + ... + Zucchero E Pomodori -.. io-code-block:: + .. tab:: Asynchronous + :tabid: async - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-sort-option - :end-before: end-sort-option - :language: python + .. io-code-block:: - .. output:: + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-sort-method + :end-before: end-sort-method + :language: python + + .. output:: + :visible: false - (Lewis Drug Store) Locanda Vini E Olii - 101 Restaurant And Bar - 44 Sw Ristorante & Bar - 900 Park - A Voce - ... - Zucchero E Pomodori + (Lewis Drug Store) Locanda Vini E Olii + 101 Restaurant And Bar + 44 Sw Ristorante & Bar + 900 Park + A Voce + ... + Zucchero E Pomodori + +You can also sort documents by specifying the ``sort`` parameter in your ``find()`` +method. The following example specifies the ``sort`` parameter to return the +results in the same order as the preceding example. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-sort-option + :end-before: end-sort-option + :language: python + + .. output:: + :visible: false + + (Lewis Drug Store) Locanda Vini E Olii + 101 Restaurant And Bar + 44 Sw Ristorante & Bar + 900 Park + A Voce + ... + Zucchero E Pomodori + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-sort-option + :end-before: end-sort-option + :language: python + + .. output:: + :visible: false + + (Lewis Drug Store) Locanda Vini E Olii + 101 Restaurant And Bar + 44 Sw Ristorante & Bar + 900 Park + A Voce + ... + Zucchero E Pomodori Skip ---- @@ -144,43 +252,97 @@ call the ``skip()`` method and pass in the number of documents to skip. The results and returns the rest. The following example returns all documents that have a ``borough`` field value -of ``"Manhattan"``, and skips the first 10 documents: - -.. io-code-block:: - - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-skip - :end-before: end-skip - :language: python - - .. output:: - - Dorrian'S Red Hand Restaurant - The Princeton Club - Moran'S Chelsea - La Parisienne Diner - Jimmy'S Corner - ... +of ``"Manhattan"``, and skips the first 10 documents. Select the :guilabel:`Synchronous` +or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-skip-option + :end-before: end-skip-option + :language: python + + .. output:: + :visible: false + + Dorrian'S Red Hand Restaurant + The Princeton Club + Moran'S Chelsea + La Parisienne Diner + Jimmy'S Corner + ... + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-skip-option + :end-before: end-skip-option + :language: python + + .. output:: + :visible: false + + Dorrian'S Red Hand Restaurant + The Princeton Club + Moran'S Chelsea + La Parisienne Diner + Jimmy'S Corner + ... You can also skip returned documents by using the ``skip`` parameter of the ``find()`` method. The following example specifies the -same skip as the preceding example: - -.. io-code-block:: - - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-skip-option - :end-before: end-skip-option - :language: python - - .. output:: - - Dorrian'S Red Hand Restaurant - The Princeton Club - Moran'S Chelsea - La Parisienne Diner - Jimmy'S Corner - ... +same skip as the preceding example. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-skip-option + :end-before: end-skip-option + :language: python + + .. output:: + :visible: false + + Dorrian'S Red Hand Restaurant + The Princeton Club + Moran'S Chelsea + La Parisienne Diner + Jimmy'S Corner + ... + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-skip-option + :end-before: end-skip-option + :language: python + + .. output:: + :visible: false + + Dorrian'S Red Hand Restaurant + The Princeton Club + Moran'S Chelsea + La Parisienne Diner + Jimmy'S Corner + ... Combine Limit, Sort, and Skip ----------------------------- @@ -191,22 +353,48 @@ return, skipping a specified number of documents before returning. The following example returns documents with the ``cuisine`` value of ``"Italian"``. The results are sorted in alphabetical order, skipping the first -10 documents: +10 documents. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab +to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-limit-sort-skip + :end-before: end-limit-sort-skip + :language: python + + .. output:: + :visible: false + + Acqua + Acqua Restaurant + Acqua Santa + Acquista Trattoria + Acquolina Catering + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: -.. io-code-block:: + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-limit-sort-skip + :end-before: end-limit-sort-skip + :language: python - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-limit-sort-skip - :end-before: end-limit-sort-skip - :language: python + .. output:: + :visible: false - .. output:: - - Acqua - Acqua Restaurant - Acqua Santa - Acquista Trattoria - Acquolina Catering + Acqua + Acqua Restaurant + Acqua Santa + Acquista Trattoria + Acquolina Catering .. note:: @@ -216,22 +404,48 @@ The following example returns documents with the ``cuisine`` value of You can also limit, sort, and skip results by specifying them as parameters in the ``find()`` method. The following example specifies the -same query as the preceding example: - -.. io-code-block:: - - .. input:: /includes/read/specify-documents-to-return.py - :start-after: start-limit-sort-skip-option - :end-before: end-limit-sort-skip-option - :language: python - - .. output:: - - Acqua - Acqua Restaurant - Acqua Santa - Acquista Trattoria - Acquolina Catering +same query as the preceding example. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return.py + :start-after: start-limit-sort-skip-option + :end-before: end-limit-sort-skip-option + :language: python + + .. output:: + :visible: false + + Acqua + Acqua Restaurant + Acqua Santa + Acquista Trattoria + Acquolina Catering + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + + .. input:: /includes/read/specify-documents-to-return-async.py + :start-after: start-limit-sort-skip-option + :end-before: end-limit-sort-skip-option + :language: python + + .. output:: + :visible: false + + Acqua + Acqua Restaurant + Acqua Santa + Acquista Trattoria + Acquolina Catering Additional Information ----------------------