Merge pull request #11 from rustagir/DOCSP-37798-reads

DOCSP-37798: read operations

Author: rustagir

snooty.toml

@@ -15,6 +15,6 @@ driver-short = "Java RS driver"
 driver-long = "MongoDB Java Reactive Streams Driver"
 version = "5.0"
 full-version = "{+version+}.0"
-api = "https://mongodb.github.io/mongo-java-driver/5.0/apidocs/mongodb-driver-reactivestreams/com/mongodb/reactivestreams"
+api = "https://mongodb.github.io/mongo-java-driver/{+version+}/apidocs"
 rs-docs = "https://www.reactive-streams.org/reactive-streams-1.0.4-javadoc/org/reactivestreams"
 driver-source-gh = "https://github.com/mongodb/mongo-java-driver"

source/tutorials.txt

@@ -9,6 +9,7 @@ Tutorials
    /tutorials/connect/
    /tutorials/db-coll/
    /tutorials/indexes/
+   /tutorials/read-ops/
    /tutorials/write-ops/
    /tutorials/aggregation/
 

source/tutorials/connect.txt

@@ -23,7 +23,7 @@ running MongoDB deployment.
    The following examples do not provide an exhaustive list of
    ways to instantiate a ``MongoClient``. For a complete list of the
    ``MongoClient`` factory methods, see the `MongoClients API
-   documentation <{+api+}/client/MongoClients.html>`__.
+   documentation <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoClients.html>`__.
 
 .. note::
 

source/tutorials/read-ops.txt

@@ -0,0 +1,345 @@
+.. _javars-read-operations:
+
+===============
+Read Operations
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Read operations retrieve documents or information about documents from a
+collection. You can specify a filter to retrieve only those documents that
+match the filter condition. 
+
+Prerequisites
+-------------
+
+You must set up the following components to run the code examples in
+this guide:
+
+- A ``test.restaurants`` collection populated with documents from the
+  ``restaurants.json`` file in the `documentation assets GitHub
+  <https://raw.githubusercontent.com/mongodb/docs-assets/drivers/restaurants.json>`__.
+
+- The following import statements:
+
+.. code-block:: java
+
+   import com.mongodb.*;
+   import com.mongodb.reactivestreams.client.MongoClients;
+   import com.mongodb.reactivestreams.client.MongoClient;
+   import com.mongodb.reactivestreams.client.MongoCollection;
+   import com.mongodb.reactivestreams.client.MongoDatabase;
+   import com.mongodb.client.model.Projections;
+   import com.mongodb.client.model.Filters;
+   import com.mongodb.client.model.Sorts;
+    
+   import java.util.Arrays;
+   import org.bson.Document;
+      
+   import static com.mongodb.client.model.Filters.*;
+   import static com.mongodb.client.model.Projections.*;
+
+.. important::
+
+   This guide uses the ``Subscriber`` implementations, which are
+   described in the :ref:`Quick Start Primer <javars-primer>`.
+
+Connect to a MongoDB Deployment
+-------------------------------
+
+First, connect to a MongoDB deployment and declare and define
+``MongoDatabase`` and ``MongoCollection`` instances.
+
+The following code connects to a standalone
+MongoDB deployment running on ``localhost`` on port ``27017``. Then, it
+defines the ``database`` variable to refer to the ``test`` database and
+the ``collection`` variable to refer to the ``restaurants`` collection:
+
+.. code-block:: java
+
+   MongoClient mongoClient = MongoClients.create();
+   MongoDatabase database = mongoClient.getDatabase("test");
+   MongoCollection<Document> collection = database.getCollection("restaurants");
+
+To learn more about connecting to MongoDB deployments,
+see the :ref:`javars-connect` tutorial.
+
+Query a Collection
+------------------
+
+To query the collection, you can use the collection's ``find()``
+method.
+
+You can call the method without any arguments to query all documents
+in a collection:
+
+.. code-block:: java
+
+   collection.find().subscribe(new PrintDocumentSubscriber());
+
+Or, you can pass a filter to query for documents that match the filter
+criteria:
+
+.. code-block:: java
+
+   collection.find(eq("name", "456 Cookies Shop"))
+       .subscribe(new PrintDocumentSubscriber());
+
+Query Filters
+-------------
+
+To query for documents that match certain conditions, pass a filter
+document to the ``find()`` method.
+
+Empty Filter
+~~~~~~~~~~~~
+
+To specify an empty filter and match all documents in a collection,
+use an empty ``Document`` object:
+
+.. code-block:: java
+
+   collection.find(new Document()).subscribe(new PrintDocumentSubscriber());
+
+.. tip::
+
+   When using the ``find()`` method, you can also call the method without
+   passing any filter object to match all documents in a collection.
+
+   .. code-block:: java
+   
+      collection.find().subscribe(new PrintDocumentSubscriber());
+
+Filters Helper
+~~~~~~~~~~~~~~
+
+To facilitate the creation of filter documents, the driver
+provides the ``Filters`` class that provides filter condition helper
+methods.
+
+This example find operation includes a filter
+``Document`` instance which specifies the following conditions:
+
+- ``stars`` field value is greater than or equal to ``2`` and less than ``5``
+- ``categories`` field equals ``"Bakery"``, or if ``categories`` is an
+  array field, contains the string ``"Bakery"`` as an element
+
+.. code-block:: java
+
+   collection.find(
+       new Document("stars", new Document("$gte", 2)
+           .append("$lt", 5))
+           .append("categories", "Bakery")).subscribe(new PrintDocumentSubscriber());
+
+The following example specifies the same filter condition using the
+``Filters`` helper methods:
+
+.. code-block:: java
+
+   collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
+       .subscribe(new PrintDocumentSubscriber());
+
+To view a list of query filter operators, see :manual:`Query and
+Projection Operators </reference/operator/query/>` in the
+Server manual. To view a list of ``Filters`` helpers, see the `Filters
+API documentation <{+api+}/mongodb-driver-core/com/mongodb/client/model/Filters.html>`__.
+
+FindPublisher
+-------------
+
+The ``find()`` method returns an instance of the ``FindPublisher``
+interface. The interface provides various methods that you can chain
+to the ``find()`` method to modify the output or behavior of the query,
+such as ``sort()`` or ``projection()``, as well as for iterating
+the results via the ``subscribe()`` method.
+
+Projections
+~~~~~~~~~~~
+
+By default, queries in MongoDB return all fields in matching
+documents. To specify the fields to return in the matching documents,
+you can specify a projection document.
+
+This find operation example includes a projection
+``Document`` which specifies that the matching documents include only the
+``name``, ``stars``, and the ``categories`` fields:
+
+.. code-block:: java
+
+   collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
+       .projection(new Document("name", 1)
+           .append("stars", 1)
+           .append("categories",1)
+           .append("_id", 0))
+       .subscribe(new PrintDocumentSubscriber());
+
+To facilitate the creation of projection documents, the driver
+provides the ``Projections`` class.
+
+.. code-block:: java
+
+   collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
+       .projection(fields(include("name", "stars", "categories"), excludeId()))
+       .subscribe(new PrintDocumentSubscriber());
+
+In the projection document, you can also specify a projection
+expression by using a projection operator.
+
+.. TODO update link To view an example that uses the ``Projections.metaTextScore()`` method, see the
+.. :ref:`Text Search <>` tutorial.
+
+Sorts
+~~~~~
+
+To sort documents, pass a sort specification document to the
+``FindPublisher.sort()`` method. The driver provides ``Sorts``
+helper methods to facilitate the creation of the sort specification document.
+
+.. code-block:: java
+
+   collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
+       .sort(Sorts.ascending("name"))
+       .subscribe(new PrintDocumentSubscriber());
+
+Sort with Projections
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``FindPublisher`` methods themselves return ``FindPublisher``
+objects, and as such, you can append multiple ``FindPublisher`` methods
+to the ``find()`` method:
+
+.. code-block:: java
+
+   collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
+       .sort(Sorts.ascending("name"))
+       .projection(fields(include("name", "stars", "categories"), excludeId()))
+       .subscribe(new PrintDocumentSubscriber());
+
+Explain
+~~~~~~~
+
+To explain a find operation, call the ``FindPublisher.explain()``
+method:
+
+.. code-block:: java
+
+   collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
+       .explain()
+       .subscribe(new PrintDocumentSubscriber());
+
+Read Preference
+---------------
+
+For read operations on replica sets or sharded clusters,
+you can configure the read preference at the following levels:
+
+- In a ``MongoClient`` in the following ways:
+  
+  - By creating a ``MongoClientSettings`` instance:
+
+    .. code-block:: java
+    
+       MongoClient mongoClient = MongoClients.create(MongoClientSettings.builder()
+           .applyConnectionString(new ConnectionString("mongodb://host1,host2"))
+           .readPreference(ReadPreference.secondary())
+           .build());
+
+  - By creating a ``ConnectionString`` instance:
+
+    .. code-block:: java
+    
+       MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017/?readPreference=secondary");
+
+- In a ``MongoDatabase`` by using the ``withReadPreference()`` method:
+
+  .. code-block:: java
+  
+     MongoDatabase database = mongoClient.getDatabase("test")
+         .withReadPreference(ReadPreference.secondary());
+
+- In a ``MongoCollection`` by using the ``withReadPreference()`` method:
+
+  .. code-block:: java
+  
+     MongoCollection<Document> collection = database.getCollection("restaurants")
+         .withReadPreference(ReadPreference.secondary());
+
+``MongoDatabase`` and ``MongoCollection`` instances are immutable. Calling
+``withReadPreference()`` on an existing ``MongoDatabase`` or
+``MongoCollection`` instance returns a new instance and does not affect
+the instance on which the method is called.
+
+In the following example, the ``collectionWithReadPref`` instance
+has the read preference of ``primaryPreferred`` whereas the read
+preference of the ``collection`` is unaffected:
+
+.. code-block:: java
+
+   MongoCollection<Document> collectionWithReadPref = collection.withReadPreference(ReadPreference.primaryPreferred());
+
+Read Concern
+------------
+
+For read operations on replica sets or sharded clusters,
+applications can configure the read concern at the following levels:
+
+- In a ``MongoClient`` in the following ways:
+  
+  - By creating a ``MongoClientSettings`` instance:
+
+    .. code-block:: java
+    
+       MongoClient mongoClient = MongoClients.create(MongoClientSettings.builder()
+           .applyConnectionString(new ConnectionString("mongodb://host1,host2"))
+           .readConcern(ReadConcern.MAJORITY)
+           .build());
+
+  - By creating a ``ConnectionString`` instance:
+
+    .. code-block:: java
+    
+       MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017/?readConcernLevel=majority");
+
+- In a ``MongoDatabase`` by using the ``withReadConcern()`` method:
+
+  .. code-block:: java
+  
+     MongoDatabase database = mongoClient.getDatabase("test")
+         .withReadConcern(ReadConcern.MAJORITY);
+
+- In a ``MongoCollection`` by using the ``withReadConcern()`` method:
+
+  .. code-block:: java
+  
+     MongoCollection<Document> collection = database.getCollection("restaurants")
+         .withReadConcern(ReadConcern.MAJORITY);
+
+``MongoDatabase`` and ``MongoCollection`` instances are immutable. Calling
+``withReadConcern()`` on an existing ``MongoDatabase`` or
+``MongoCollection`` instance returns a new instance and does not affect
+the instance on which the method is called.
+
+In the following example, the ``collWithReadConcern`` instance has
+an ``AVAILABLE`` read concern whereas the read concern of the ``collection``
+is unaffected:
+
+.. code-block:: java
+
+   MongoCollection<Document> collWithReadConcern = collection.withReadConcern(ReadConcern.AVAILABLE);
+
+You can build ``MongoClientSettings``, ``MongoDatabase``, or
+``MongoCollection`` instances to include combinations of read concerns, read
+preferences, and write concerns.
+
+For example, the following code sets all three at the collection level:
+
+.. code-block:: java
+
+   collection = database.getCollection("restaurants")
+       .withReadPreference(ReadPreference.primary())
+       .withReadConcern(ReadConcern.MAJORITY)
+       .withWriteConcern(WriteConcern.MAJORITY);