From 188de20b036467f8e0d448963cc811ce892f6e35 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 16 Jul 2024 10:47:15 -0400 Subject: [PATCH 1/3] DOCSP-41133: Specify a Query --- source/includes/read/specify-a-query.kt | 93 +++++++++ source/read.txt | 1 + source/read/specify-a-query.txt | 264 ++++++++++++++++++++++++ 3 files changed, 358 insertions(+) create mode 100644 source/includes/read/specify-a-query.kt create mode 100644 source/read/specify-a-query.txt diff --git a/source/includes/read/specify-a-query.kt b/source/includes/read/specify-a-query.kt new file mode 100644 index 00000000..cf54ddcb --- /dev/null +++ b/source/includes/read/specify-a-query.kt @@ -0,0 +1,93 @@ +package org.example +import com.mongodb.ConnectionString +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.Filters.* +import com.mongodb.kotlin.client.MongoClient +import org.bson.codecs.pojo.annotations.BsonId + +// start-data-class +data class Fruit( + @BsonId + val id: Int, + val name: String, + val quantity: Int, + val rating: Int, + val color: String, + val type: List +) +// end-data-class + +fun main() { + // start-sample-data + val uri = "" + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .retryWrites(true) + .build() + + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_fruit") + val collection = database.getCollection("fruits") + + collection.insertMany(listOf( + Fruit(1, "apples", 5, 3, "red", listOf("fuji", "honeycrisp")), + Fruit(2, "bananas", 7, 4, "yellow", listOf("cavendish")), + Fruit(3, "oranges", 6, 2, null, listOf("naval", "mandarin")), + Fruit(4, "pineapples", 3, 5, "yellow", null) + )) + // end-sample-data + + // start-find-exact + val results = collection.find(eq(Fruit::color.name, "yellow")) + + results.forEach { result -> + println(result); + } + // end-find-exact + + // start-find-comparison + val results = collection.find(gt(Fruit::rating.name, 2)) + + results.forEach { result -> + println(result) + } + // end-find-comparison + + // start-find-logical + val results = collection.find( + or( + gt(Fruit::quantity.name, 5), + eq(Fruit::color.name, "yellow") + ) + ) + + results.forEach { result -> + println(result) + } + // end-find-logical + + // start-find-array + val results = collection.find(size(Fruit::type.name, 2)) + + results.forEach { result -> + println(result) + } + // end-find-array + + // start-find-element + val results = collection.find(exists(Fruit::color.name)) + + results.forEach { result -> + println(result) + } + // end-find-element + + // start-find-evaluation + val results = collection.find(regex(Fruit::name.name, "p{2,}")) + + results.forEach { result -> + println(result) + } + // end-find-evaluation +} diff --git a/source/read.txt b/source/read.txt index 0cdf1f55..13554862 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,6 +22,7 @@ Read Data from MongoDB :titlesonly: :maxdepth: 1 + /read/specify-a-query /read/count Overview diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt new file mode 100644 index 00000000..c2759c1c --- /dev/null +++ b/source/read/specify-a-query.txt @@ -0,0 +1,264 @@ +.. _kotlin-sync-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 {+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", "quantity": 5, "rating": 3, "color": "red", "type": ["fuji", "honeycrisp"] }, + { "_id": 2, "name": "bananas", "quantity": 7, "rating": 4, "color": "yellow", "type": ["cavendish"] }, + { "_id": 3, "name": "oranges", "quantity": 6, "rating": 2, "type": ["naval", "mandarin"] }, + { "_id": 4, "name": "pineapple", "quantity": 3, "rating": 5, "color": "yellow" }, + +The documents in this collection are modeled by the following {+language+} data class: + +.. literalinclude:: /includes/read/specify-a-query.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + +The following code example shows how to create a database and collection, then +insert the sample documents into your collection: + +.. literalinclude:: /includes/read/specify-a-query.kt + :start-after: start-sample-data + :end-before: end-sample-data + :language: kotlin + :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: true + + .. input:: /includes/read/specify-a-query.kt + :start-after: start-find-exact + :end-before: end-find-exact + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Fruit(id=2, name=bananas, quantity=7, rating=4, color=yellow, type=[cavendish]) + Fruit(id=4, name=pineapples, quantity=3, rating=5, color=yellow, type=null) + +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 +` 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: true + + .. input:: /includes/read/specify-a-query.kt + :start-after: start-find-comparison + :end-before: end-find-comparison + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Fruit(id=1, name=apples, quantity=5, rating=3, color=red, type=[fuji, honeycrisp]) + Fruit(id=2, name=bananas, quantity=7, rating=4, color=yellow, type=[cavendish]) + Fruit(id=4, name=pineapples, quantity=3, rating=5, color=yellow, type=null) + +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 +` 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 +``quantity`` field value greater than ``5`` **or** a ``color`` field value of +``"yellow"``: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/specify-a-query.kt + :start-after: start-find-logical + :end-before: end-find-logical + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Fruit(id=2, name=bananas, quantity=7, rating=4, color=yellow, type=[cavendish]) + Fruit(id=3, name=oranges, quantity=6, rating=2, color=null, type=[naval, mandarin]) + Fruit(id=4, name=pineapples, quantity=3, rating=5, color=yellow, type=null) + +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 +` 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 exactly ``2`` elements: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/specify-a-query.kt + :start-after: start-find-array + :end-before: end-find-array + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Fruit(id=1, name=apples, quantity=5, rating=3, color=red, type=[fuji, honeycrisp]) + Fruit(id=3, name=oranges, quantity=6, rating=2, color=null, 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 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: true + + .. input:: /includes/read/specify-a-query.kt + :start-after: start-find-element + :end-before: end-find-element + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Fruit(id=1, name=apples, quantity=5, rating=3, color=red, type=[fuji, honeycrisp]) + Fruit(id=2, name=bananas, quantity=7, rating=4, color=yellow, type=[cavendish]) + Fruit(id=4, name=pineapples, quantity=3, rating=5, color=yellow, type=null) + +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 +` 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: true + + .. input:: /includes/read/specify-a-query.kt + :start-after: start-find-evaluation + :end-before: end-find-evaluation + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Fruit(id=1, name=apples, quantity=5, rating=3, color=red, type=[fuji, honeycrisp]) + Fruit(id=4, name=pineapples, quantity=3, rating=5, color=yellow, type=null) + +Additional Information +---------------------- + +To learn more about querying documents, see the :manual:`Query Documents +` guide in the MongoDB Server manual. + +To learn more about retrieving documents with the {+driver-short+}, see +:ref:`kotlin-sync-retrieve`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `find() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/find.html>`__ From 8ab377911b84404807a83b527fe13c320c77a807 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 16 Jul 2024 10:54:24 -0400 Subject: [PATCH 2/3] Fix indent --- source/read/specify-a-query.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt index c2759c1c..b0ac3cb2 100644 --- a/source/read/specify-a-query.txt +++ b/source/read/specify-a-query.txt @@ -57,6 +57,7 @@ insert the sample documents into your collection: :start-after: start-sample-data :end-before: end-sample-data :language: kotlin + :dedent: :copyable: Exact Match From f46591061799f579eea5885c6d3e90906affd17f Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 16 Jul 2024 11:49:51 -0400 Subject: [PATCH 3/3] Address JS feedback --- source/read/specify-a-query.txt | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt index b0ac3cb2..7761438f 100644 --- a/source/read/specify-a-query.txt +++ b/source/read/specify-a-query.txt @@ -66,7 +66,7 @@ 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"``: +method. The code returns all documents with a ``color`` field value of ``"yellow"``. .. io-code-block:: :copyable: true @@ -98,7 +98,7 @@ To view a full list of comparison operators, see the :manual:`Comparison Query O 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``: +``rating`` field value greater than ``2``. .. io-code-block:: :copyable: true @@ -133,7 +133,7 @@ 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 ``quantity`` field value greater than ``5`` **or** a ``color`` field value of -``"yellow"``: +``"yellow"``. .. io-code-block:: :copyable: true @@ -166,7 +166,7 @@ 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 exactly ``2`` elements: +``type`` array field containing exactly ``2`` elements. .. io-code-block:: :copyable: true @@ -193,7 +193,7 @@ 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. .. io-code-block:: :copyable: true @@ -221,8 +221,9 @@ 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 +- ``$mod``, which performs a :wikipedia:`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 MongoDB Server manual. @@ -230,7 +231,7 @@ 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. .. io-code-block:: :copyable: true