DOCSP-41132: Read Data from MongoDB (mongodb#3)

README.rst

@@ -1,6 +1,6 @@
-==================================
-{+driver-long+} Documentation
-==================================
+=================================
+MongoDB Kotlin Sync Documentation
+=================================
 
 This repository contains documentation for the {+driver-short+}.
 

source/includes/usage-examples/retrieve-code-examples.kt

@@ -0,0 +1,57 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.kotlin.client.*
+import com.mongodb.client.model.Filters.*
+import org.bson.Document
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    // Create a new client and connect to the server
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("<database name>")
+    val collection = database.getCollection<Document>("<collection name>")
+
+    // start-find
+    val filter = <filter>
+    val results = collection.find(filter)
+    results.forEach { result ->
+        print(result)
+    }
+    // end-find
+
+    // start-count-all
+    val count = collection.countDocuments()
+    print(count)
+    // end-count-all
+
+    // start-count-query
+    val filter = <filter>
+    val queryCount = collection.countDocuments(filter)
+    print(queryCount)
+    // end-count-query
+
+    // start-estimated-count
+    val estimatedCount = collection.estimatedDocumentCount()
+    print(estimatedCount)
+    // end-estimated-count
+
+    // start-distinct
+    val distinctResults = collection.distinct("<field name>")
+    distinctResults.forEach { result ->
+        print(result)
+    }
+    // end-distinct
+
+    // start-watch
+    val changeStream = collection.watch()
+    changeStream.forEach { changeEvent ->
+        print(changeEvent)
+    }
+    // end-watch
+}

source/includes/usage-examples/sample-app-intro.rst

@@ -0,0 +1,9 @@
+Sample Application
+~~~~~~~~~~~~~~~~~~
+
+You can use the following sample application to test the code examples on this
+page. To use the sample application, perform the following steps:
+
+1. Ensure you have the {+driver-short+} installed in your Maven or Gradle project.
+#. Copy the following code and paste it into a new ``.kt`` file.
+#. Copy a code example from this page and paste it on the specified lines in the file.

source/includes/usage-examples/sample-app.kt

@@ -0,0 +1,23 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.kotlin.client.*
+import com.mongodb.client.model.Filters.*
+import org.bson.Document
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    // Create a new client and connect to the server
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("<database name>")
+    val collection = database.getCollection<Document>("<collection name>")
+
+    // Start example code here
+
+    // End example code here
+}

source/index.txt

@@ -6,6 +6,7 @@
    :titlesonly:
    :maxdepth: 1
 
+   /read
    /faq
    /connection-troubleshooting
    /issues-and-help

source/read.txt

@@ -0,0 +1,156 @@
+.. _kotlin-sync-read:
+
+======================
+Read Data from MongoDB
+======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :description: Learn how to use the Kotlin Sync Driver to read data from MongoDB.
+   :keywords: usage examples, query, find, code example
+
+.. .. toctree::
+..    :titlesonly:
+..    :maxdepth: 1
+
+   .. /read/specify-a-query
+   .. /read/retrieve
+   .. /read/project
+   .. /read/specify-documents-to-return
+   .. /read/count
+   .. /read/distinct
+   .. /read/cursors
+   .. /read/change-streams
+
+Overview
+--------
+
+On this page, you can see copyable code examples that show common
+methods you can use to retrieve documents by using the {+driver-short+}.
+
+.. tip::
+
+  To learn more about any of the methods shown on this page, see the link
+  to a relevant guide provided in each section.
+
+To use an example from this page, copy the code example into the
+:ref:`sample application <kotlin-sync-read-sample>` or your own application.
+Be sure to replace all placeholders in the code examples, such as ``<connection string URI>``, with
+the relevant values for your MongoDB deployment.
+
+.. _kotlin-sync-read-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/sample-app.kt
+    :language: kotlin
+    :copyable:
+    :linenos:
+    :emphasize-lines: 20-22
+
+.. .. tip::
+
+..   For instructions about how to install the {+driver-short+}, see :ref:`<kotlin-sync-quick-start>`.
+
+Find Documents
+--------------
+
+The following example retrieves a list of documents that match the criteria specified by the
+given filter:
+
+.. literalinclude:: /includes/usage-examples/retrieve-code-examples.kt
+   :start-after: start-find
+   :end-before: end-find
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: To learn more about the ``find()`` method, see the :ref:`kotlin-sync-retrieve-find` guide.
+
+Count Documents in a Collection
+-------------------------------
+
+The following example returns the number of documents in the specified collection:
+
+.. literalinclude:: /includes/usage-examples/retrieve-code-examples.kt
+   :start-after: start-count-all
+   :end-before: end-count-all
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: To learn more about the ``count_documents()`` method, see the
+.. :ref:`kotlin-sync-accurate-count` guide.
+
+Count Documents Returned from a Query
+-------------------------------------
+
+The following example returns the number of documents that match the criteria specified by
+the given filter:
+
+.. literalinclude:: /includes/usage-examples/retrieve-code-examples.kt
+   :start-after: start-count-query
+   :end-before: end-count-query
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: To learn more about the ``countDocuments()`` method, see the
+.. :ref:`kotlin-sync-accurate-count` guide.
+
+Estimated Document Count
+------------------------
+
+The following example returns an approximate number of documents in the specified
+collection based on collection metadata:
+
+.. literalinclude:: /includes/usage-examples/retrieve-code-examples.kt
+   :start-after: start-estimated-count
+   :end-before: end-estimated-count
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: To learn more about the ``estimatedDocumentCount()`` method, see the
+.. :ref:`kotlin-sync-estimated-count` guide.
+
+Retrieve Distinct Values
+------------------------
+
+The following example returns all distinct values of the specified field name in a given
+collection:
+
+.. literalinclude:: /includes/usage-examples/retrieve-code-examples.kt
+   :start-after: start-distinct
+   :end-before: end-distinct
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: To learn more about the ``distinct()`` method, see the
+.. :ref:`kotlin-sync-distinct` guide.
+
+Monitor Data Changes
+--------------------
+
+The following example creates a change stream for a given collection and prints out
+subsequent change events in that collection:
+
+.. literalinclude:: /includes/usage-examples/retrieve-code-examples.kt
+   :start-after: start-watch
+   :end-before: end-watch
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+.. TODO: To learn more about the ``watch()`` method, see the
+.. :ref:`kotlin-sync-change-streams` guide.