DOCSP-37538 Specify a Query (#51)

Author: jordan-smith721

source/includes/specify-query/specify-queries.py

@@ -0,0 +1,72 @@
+# start-sample-data
+from pymongo import MongoClient
+
+uri = "<connection string URI>"
+client = MongoClient(uri)
+
+try:
+    database = client["sample_fruit"]
+    collection = database["fruits"]
+
+    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" },
+    ])
+
+    client.close()
+
+except Exception as e:
+    raise Exception("Error inserting documents: ", e)
+# end-sample-data
+
+# start-find-exact
+results = collection.find({ "color": "yellow" })
+# end-find-exact
+
+# start-find-all
+results = collection.find({})
+# end-find-all
+
+# start-find-comparison
+results = collection.find({ "rating": { "$gt" : 2 }})
+
+for f in results:
+    print(f) 
+# end-find-comparison
+    
+# start-find-logical
+results = collection.find({ 
+    "$or": [
+        { "qty": { "$gt": 5 }},
+        { "color": "yellow" }
+    ]
+})
+
+for f in results:
+    print(f)
+# end-find-logical
+
+# start-find-array
+results = collection.find({
+    "type" : { "$size": 2 }
+})
+
+for f in results:
+    print(f)
+# end-find-array
+
+# start-find-element
+results = collection.find( { "color" : { "$exists": "true" }} )
+
+for f in results:
+    print(f)
+# end-find-element
+
+# start-find-evaluation
+results = collection.find({ "name" : { "$regex" : "p{2,}" }} )
+
+for f in results:
+    print(f)
+# end-find-evaluation

source/index.txt

@@ -19,6 +19,7 @@ MongoDB PyMongo Documentation
    /connect
    /write-operations
    /read
+   /specify-a-query
    /security
    /tools
    API Documentation <{+api-root+}>

source/specify-a-query.txt

@@ -0,0 +1,256 @@
+.. _pymongo-specify-query:
+
+===============
+Specify a Query
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: expressions, operations, read, write, filter
+
+Overview
+--------
+
+In this guide, you can learn how to specify a query by using {+driver-short+}.
+
+You can refine the set of documents that a query returns by creating a
+**query filter**. A query filter is an expression that specifies the search
+criteria MongoDB uses to match documents in a read or write operation.
+In a query filter, you can prompt the driver to search for documents with an
+exact match to your query, or you can compose query filters to express more
+complex matching criteria.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide run operations on a collection called
+``fruits`` that contains the following documents:
+
+.. code-block:: json
+
+   { "_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" },
+
+The following code example shows how to create a database and collection, then
+insert the sample documents into your collection:
+
+.. literalinclude:: /includes/specify-query/specify-queries.py
+   :start-after: start-sample-data
+   :end-before: end-sample-data
+   :language: python
+   :copyable:
+
+Exact Match
+-----------
+
+Literal value queries return documents with an exact match to your query filter.
+
+The following example specifies a query filter as a parameter to the ``find()``
+method. The code returns all documents with a ``color`` field value of ``"yellow"``:
+
+.. io-code-block::
+   :copyable: 
+
+   .. input:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-exact
+      :end-before: end-find-exact
+      :language: python
+
+   .. output::
+      
+      {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']}
+      {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'}
+
+.. tip:: Find All Documents
+
+   To find all documents in a collection, call the ``find()`` method and pass it an
+   empty query filter. The following example finds all documents in a
+   collection:
+
+   .. literalinclude:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-all
+      :end-before: end-find-all
+      :language: python
+      :copyable:
+
+Comparison Operators
+--------------------
+
+Comparison operators evaluate a document field value against a specified value
+in your query filter. The following is a list of common comparison operators:
+
+- ``$gt``: Greater than
+- ``$lte``: Less than or Equal
+- ``$ne``: Not equal
+
+To view a full list of comparison operators, see the :manual:`Comparison Query Operators
+</reference/operator/query-comparison/>` guide in the MongoDB Server manual.
+
+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: 
+
+   .. input:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-comparison
+      :end-before: end-find-comparison
+      :language: python
+
+   .. output::
+
+      {'_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
+-----------------
+
+Logical operators match documents by using logic applied to the results of two or
+more sets of expressions. The following is a list of logical operators: 
+
+- ``$and``, which returns all documents that match the conditions of *all* clauses
+- ``$or``, which returns all documents that match the conditions of *one* clause
+- ``$nor``, which returns all documents that *do not* match the conditions of any clause
+- ``$not``, which returns all documents that *do not* match the expression
+
+To learn more about logical operators, see the :manual:`Logical Query Operators
+</reference/operator/query-logical/>` guide in the MongoDB Server manual.
+
+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"``:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-logical
+      :end-before: end-find-logical
+      :language: python
+
+   .. output::
+
+      {'_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
+---------------
+
+Array operators match documents based on the value or quantity of elements in an
+array field. The following is a list of available array operators:
+
+- ``$all``, which returns documents with arrays that contain all elements in the query
+- ``$elemMatch``, which returns documents if an element in their array field matches all conditions in the query
+- ``$size``, which returns all documents with arrays of a specified size
+
+To learn more about array operators, see the :manual:`Array Query Operators
+</reference/operator/query-array/>` guide in the MongoDB Server manual.
+
+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:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-array
+      :end-before: end-find-array
+      :language: python
+
+   .. output::
+
+      {'_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
+-----------------
+
+Element operators query data based on the presence or type of a field.
+
+To learn more about element operators, see the :manual:`Element Query Operators
+</reference/operator/query-element/>` guide in the MongoDB Server manual.
+
+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:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-element
+      :end-before: end-find-element
+      :language: python
+
+   .. output::
+
+      {'_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
+--------------------
+
+Evaluation operators return data based on evaluations of either individual
+fields or the entire collection's documents.
+
+The following is a list of common evaluation operators:
+
+- ``$text``, which performs a text search on the documents
+- ``$regex``, which returns documents that match a specified regular expression
+- ``$mod``, which performs a modulo operation on the value of a field and
+  returns documents where the remainder is a specified value
+
+To view a full list of evaluation operators, see the :manual:`Evaluation Query Operators
+</reference/operator/query-evaluation/>` guide in the MongoDB Server manual.
+
+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:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/specify-query/specify-queries.py
+      :start-after: start-find-evaluation
+      :end-before: end-find-evaluation
+      :language: python
+
+   .. output::
+
+      {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']}
+      {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'}
+
+Additional Information
+----------------------
+
+To learn more about querying documents, see the :manual:`Query Documents
+</tutorial/query-documents/>` guide in the MongoDB Server manual.
+
+To learn more about retrieving documents with PyMongo, see
+:ref:`pymongo-retrieve`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `find() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__