diff --git a/source/includes/read/specify-queries.php b/source/includes/read/specify-queries.php new file mode 100644 index 00000000..3e3c07cb --- /dev/null +++ b/source/includes/read/specify-queries.php @@ -0,0 +1,108 @@ +"; +$client = new Client($uri); +$collection = $client->db->fruits; + +// Inserts documents representing fruits +$fruits = [ + [ + '_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' => 'pineapples', + 'qty' => 3, + 'rating' => 5, + 'color' => 'yellow' + ] +]; + +$result = $collection->insertMany($fruits); +// end-setup + +// Retrieves documents in which the "color" value is "yellow" +// start-find-exact +$cursor = $collection->find(['color' => 'yellow']); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-exact + +// Retrieves all documents in the collection +// start-find-all +$cursor = $collection->find([]); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-all + +// Retrieves and prints documents in which the "rating" value is greater than 2 +// start-find-comparison +$cursor = $collection->find(['rating' => ['$gt' => 2]]); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-comparison + +// Retrieves and prints documents that match one or both query filters +// start-find-logical +$cursor = $collection->find([ + '$or' => [ + ['qty' => ['$gt' => 5]], + ['color' => 'yellow'] + ] +]); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-logical + +// Retrieves and prints documents in which the "type" array has 2 elements +// start-find-array +$cursor = $collection->find(['type' => ['$size' => 2]]); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-array + +// Retrieves and prints documents that have a "color" field +// start-find-element +$cursor = $collection->find(['color' => ['$exists' => true]]); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-element + +// Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters +// start-find-evaluation +$cursor = $collection->find(['name' => ['$regex' => 'p{2,}']]); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-find-evaluation diff --git a/source/read.txt b/source/read.txt index a5c58482..5cc0e838 100644 --- a/source/read.txt +++ b/source/read.txt @@ -7,7 +7,8 @@ Read Data from MongoDB .. toctree:: :titlesonly: :maxdepth: 1 - + /read/retrieve + /read/specify-a-query /read/project diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt new file mode 100644 index 00000000..9e38c2f6 --- /dev/null +++ b/source/read/specify-a-query.txt @@ -0,0 +1,265 @@ +.. _php-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 the {+php-library+}. + +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 that MongoDB uses to match documents in a read or write operation. +In a query filter, you can prompt the driver to search for documents that have +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 the ``fruits`` collection, +which contains documents representing fruits. The following +code example shows how to create a database and collection, then +insert the sample documents into your collection: + +.. literalinclude:: /includes/read/specify-queries.php + :start-after: start-setup + :end-before: end-setup + :language: php + :dedent: + :copyable: + +Exact Match +----------- + +Literal value queries return documents that have an exact match to your query filter. + +The following example specifies a query filter as a parameter to the ``MongoDB\Collection::find()`` +method. The code returns all documents in which the value of the ``color`` field +is ``'yellow'``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.php + :start-after: start-find-exact + :end-before: end-find-exact + :language: php + :dedent: + + .. output:: + :visible: false + + {"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]} + {"_id":4,"name":"pineapples","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/read/specify-queries.php + :start-after: start-find-all + :end-before: end-find-all + :language: php + :dedent: + :copyable: + +Comparison Operators +-------------------- + +Comparison operators evaluate a document field value against a specified value +in your query filter. The following list defines 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 +` guide in the {+mdb-server+} manual. + +The following example specifies a comparison operator in a query filter as a +parameter to the ``MongoDB\Collection::find()`` method. The code returns all documents +in which the value of the ``rating`` field is greater than ``2``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.php + :start-after: start-find-comparison + :end-before: end-find-comparison + :language: php + :dedent: + + .. 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":"pineapples","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 list describes each logical operator: + +- ``$and``: Returns all documents that match the conditions of *all* clauses +- ``$or``: Returns all documents that match the conditions of *one* clause +- ``$nor``: Returns all documents that *do not* match the conditions of any clause +- ``$not``: Returns all documents that *do not* match the expression + +To learn more about logical operators, see the :manual:`Logical Query Operators +` guide in the {+mdb-server+} manual. + +The following example specifies a logical operator in a query filter as a +parameter to the ``MongoDB\Collection::find()`` method. The code returns all documents +in which the ``qty`` field value is greater than ``5`` **or** the ``color`` field +value is ``'yellow'``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.php + :start-after: start-find-logical + :end-before: end-find-logical + :language: php + :dedent: + + .. 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":"pineapples","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 list describes the available array operators: + +- ``$all``: Returns documents with arrays that contain all elements in the query +- ``$elemMatch``: Returns documents if an element in their array field matches all conditions in the query +- ``$size``: Returns all documents with arrays of a specified size + +To learn more about array operators, see the :manual:`Array Query Operators +` guide in the {+mdb-server+} manual. + +The following example specifies an array operator in a query filter as a +parameter to the ``MongoDB\Collection::find()`` method. The code returns all +documents in which the ``type`` array field contains ``2`` elements: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.php + :start-after: start-find-array + :end-before: end-find-array + :language: php + :dedent: + + .. 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 +----------------- + +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 +` guide in the {+mdb-server+} manual. + +The following example specifies an element operator in a query filter as a +parameter to the ``MongoDB\Collection::find()`` method. The code returns all +documents that have a ``color`` field: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.php + :start-after: start-find-element + :end-before: end-find-element + :language: php + :dedent: + + .. 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":"pineapples","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 list describes common evaluation operators: + +- ``$text``: Performs a text search on the documents +- ``$regex``: Returns documents that match a specified regular expression +- ``$mod``: 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 +` guide in the {+mdb-server+} manual. + +The following example specifies an evaluation operator in a query filter as a +parameter to the ``MongoDB\Collection::find()`` method. The code uses a regular +expression to return all documents in which the ``name`` field value has at least +two consecutive ``'p'`` characters: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.php + :start-after: start-find-evaluation + :end-before: end-find-evaluation + :language: php + :dedent: + + .. output:: + :visible: false + + {"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]} + {"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"} + +Additional Information +---------------------- + +To learn more about querying documents, see the :manual:`Query Documents +` guide in the {+mdb-server+} manual. + +.. TODO: + To learn more about retrieving documents with the {+php-library+}, see the + :ref:`php-retrieve` guide. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__ +- `MongoDB\\Collection::insertMany() <{+api+}/method/MongoDBCollection-insertMany/>`__ \ No newline at end of file