diff --git a/source/includes/read/specify-queries.rb b/source/includes/read/specify-queries.rb new file mode 100644 index 00000000..ccd6bb63 --- /dev/null +++ b/source/includes/read/specify-queries.rb @@ -0,0 +1,79 @@ +require 'bundler/inline' + +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = '' + +Mongo::Client.new(uri) do |client| + # start-setup + database = client.use('db') + collection = database[: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' } + ] + + collection.insert_many(fruits) + # end-setup + + # Retrieves documents in which the "color" value is "yellow" + # start-find-exact + filter = { color: 'yellow' } + results = collection.find(filter) + results.each do |doc| + puts doc + end + # end-find-exact + + # Retrieves and prints documents in which the "rating" value is greater than 2 + # start-find-comparison + filter = { rating: { '$gt' => 2 } } + results = collection.find(filter) + results.each do |doc| + puts doc + end + # end-find-comparison + + # Retrieves and prints documents that match one or both query filters + # start-find-logical + filter = { '$or' => [{ qty: { '$gt' => 5 } }, { color: 'yellow' }] } + results = collection.find(filter) + results.each do |doc| + puts doc + end + # end-find-logical + + # Retrieves and prints documents in which the "type" array has 2 elements + # start-find-array + filter = { type: { '$size' => 2 } } + results = collection.find(filter) + results.each do |doc| + puts doc + end + # end-find-array + + # Retrieves and prints documents that have a "color" field + # start-find-element + filter = { color: { '$exists' => true } } + results = collection.find(filter) + results.each do |doc| + puts doc + end + # end-find-element + + # Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters + # start-find-evaluation + filter = { name: /p{2,}/ } + results = collection.find(filter) + results.each do |doc| + puts doc + end + # end-find-evaluation +end diff --git a/source/read.txt b/source/read.txt index 316d2bce..075d3eae 100644 --- a/source/read.txt +++ b/source/read.txt @@ -23,5 +23,6 @@ Read Data from MongoDB :maxdepth: 1 Retrieve Data + Specify a Query Specify Documents to Return Specify Fields to Return diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt new file mode 100644 index 00000000..2e94c793 --- /dev/null +++ b/source/read/specify-a-query.txt @@ -0,0 +1,280 @@ +.. _ruby-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, filter, code example + +Overview +-------- + +In this guide, you can learn how to specify a query by using the {+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 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, and then +insert the sample documents into your collection: + +.. literalinclude:: /includes/read/specify-queries.rb + :start-after: start-setup + :end-before: end-setup + :language: ruby + :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 ``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.rb + :start-after: start-find-exact + :end-before: end-find-exact + :language: ruby + :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"} + +.. note:: Find All Documents + + To find all documents in a collection, call the ``find`` method + without passing any parameters: + + .. code-block:: ruby + + results = collection.find + +Comparison Operators +-------------------- + +Comparison operators evaluate a document field value against a specified value +in your query filter. The following list describes common comparison operators: + +- ``$gt``: Returns documents in which the value of the given field is *greater than* + the specified value +- ``$lte``: Returns documents in which the value of the given field is *less than or + equal to* the specified value +- ``$ne``: Returns documents in which the value of the given field *does not equal* the + specified value + +.. tip:: + + 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 ``find`` method. The code returns all documents that have a +``rating`` field value greater than ``2``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.rb + :start-after: start-find-comparison + :end-before: end-find-comparison + :language: ruby + :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 documents that match the conditions of *all* clauses +- ``$or``: Returns documents that match the conditions of *one* clause +- ``$nor``: Returns documents that *do not* match the conditions of any clause +- ``$not``: Returns documents that *do not* match the expression + +.. tip:: + + 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 ``find`` method. The code returns all documents that have a +``qty`` field value greater than ``5`` **or** a ``color`` field value of +``'yellow'``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.rb + :start-after: start-find-logical + :end-before: end-find-logical + :language: ruby + :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 each array operator: + +- ``$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 documents with arrays of a specified size + +.. tip:: + + 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 ``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.rb + :start-after: start-find-array + :end-before: end-find-array + :language: ruby + :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. The following +list describes each element operator: + +- ``$exists``: Returns documents that contain the specified field +- ``$type``: Returns documents that contain a field of the specified type + +.. tip:: + + 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 ``find`` method. The code returns all documents that have a +``color`` field: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/specify-queries.rb + :start-after: start-find-element + :end-before: end-find-element + :language: ruby + :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 element 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 + +.. tip:: + + 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 ``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.rb + :start-after: start-find-evaluation + :end-before: end-find-evaluation + :language: ruby + :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"} + +.. note:: + + The {+driver-short+} implicitly uses the ``$regex`` operator + when a query filter includes a regular expression value, as shown + in the preceding example. + +Additional Information +---------------------- + +To learn more about querying documents, see :manual:`Query Documents +` in the {+mdb-server+} manual. + +To learn more about retrieving documents by using the {+driver-short+}, see the +:ref:`ruby-retrieve` guide. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``find`` method, see the `API documentation. +<{+api-root+}/Mongo/Collection.html#find-instance_method>`__ \ No newline at end of file