Merge branch 'master' into DOCSP-41115-get-started

Author: rustagir

snooty.toml

@@ -7,10 +7,15 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
               ]
 
 toc_landing_pages = [
+    "/get-started",
     "/read",
-    "/get-started"
+    "/connect",
+    "/indexes",
+    "work-with-indexes",
 ]
 
+sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
+
 [constants]
 driver-long = "MongoDB Kotlin Sync Driver"
 driver-short = "Kotlin Sync driver"
@@ -21,5 +26,5 @@ version = "v{+version-number+}"
 mdb-server = "MongoDB Server"
 stable-api = "Stable API"
 api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
-core-api = "https://mongodb.github.io/mongo-java-driver/5.1/apidocs"
 kotlin-docs = "https://kotlinlang.org"
+core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/"

source/connect.txt

@@ -0,0 +1,190 @@
+.. _kotlin-sync-connect:
+
+==================
+Connect to 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 connect to MongoDB.
+   :keywords: client, ssl, tls, localhost
+
+.. .. toctree::
+..    :titlesonly:
+..    :maxdepth: 1
+.. 
+..    /connect/mongoclient
+..    /connect/connection-targets
+..    /connect/connection-options
+..    /connect/tls
+..    /connect/network-compression
+..    /connect/server-selection
+..    /connect/stable-api
+..    /connect/csot
+
+Overview
+--------
+
+This page contains code examples that show how to use the
+{+driver-short+} to connect your application to MongoDB by specifying
+various settings. 
+
+.. .. tip::
+.. 
+..   To learn more about the connection options on this page, see the link
+..   provided in each section.
+
+To use a connection example from this page, copy the code example into the
+:ref:`sample application <kotlin-sync-connect-sample>` or your own application.
+Be sure to replace all placeholders in the code examples, such as
+``<hostname>``, with the relevant values for your MongoDB deployment.
+
+.. _kotlin-sync-connect-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/connect-sample-app.kt
+   :language: python
+   :copyable: true
+   :linenos:
+   :emphasize-lines: 6-8
+
+Connection
+----------
+
+The following sections describe how to connect to different targets,
+such as a local instance of MongoDB or a cloud-hosted instance on Atlas.
+
+Local Deployment
+~~~~~~~~~~~~~~~~
+
+The following code shows the connection string to connect to a local
+instance of MongoDB:
+
+.. code-block:: kotlin
+
+   val uri = "mongodb://localhost:27017/"
+   val mongoClient = MongoClient.create(uri)
+
+Atlas
+~~~~~
+
+The following code shows the connection string to connect to a
+deployment hosted on Atlas:
+
+.. code-block:: kotlin
+
+   val uri = "mongodb+srv://<username>:<password>@<hostname/port>/?<options>"
+   val mongoClient = MongoClient.create(uri)
+
+Replica Set
+~~~~~~~~~~~
+
+The following code shows the connection string to connect to a
+replica set:
+
+.. code-block:: kotlin
+   
+   val uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
+   val mongoClient = MongoClient.create(uri)
+
+Transport Layer Security (TLS)
+------------------------------
+
+The following sections describe how to connect to MongoDB
+while enabling the TLS protocol.
+
+Enable TLS
+~~~~~~~~~~
+
+The following tabs demonstrate how to enable TLS on a connection:
+
+.. include:: /includes/connect/tls-tabs.rst
+
+.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in
+.. the TLS configuration guide.
+
+Disable Hostname Verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to disable hostname verification when
+connecting by using TLS:
+
+.. include:: /includes/connect/disable-host-verification-tabs.rst
+
+.. To learn more about disabling hostname verification, see :ref:`kotlin-sync-insecure-tls` in
+.. the TLS configuration guide.
+
+Network Compression
+-------------------
+
+The following sections describe how to connect to MongoDB
+while specifying network compression algorithms.
+
+Compression Algorithms
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to specify all available compressors
+while connecting to MongoDB:
+
+.. include:: /includes/connect/compression-tabs.rst
+
+.. To learn more about specifying compression algorithms, see
+.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
+
+zlib Compression Level
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following tabs demonstrate how to specify a compression level for
+the ``zlib`` compressor:
+
+.. include:: /includes/connect/zlib-level-tabs.rst
+
+.. To learn more about setting the zlib compression level, see
+.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
+
+Server Selection
+----------------
+
+The following code shows a connection string that specifies a server
+selection function:
+
+.. code-block:: kotlin
+
+   val client = MongoClient.create("mongodb://<username>:<password>@<hostname>:<port>",
+                                server_selector=<selector function>)
+
+.. To learn more about customizing server selection, see
+.. :ref:`kotlin-sync-server-selection`.
+
+{+stable-api+}
+--------------
+
+The following code shows how to specify Stable API settings within a
+``MongoClientSettings`` instance:
+
+.. code-block:: kotlin
+
+   val serverApi = ServerApi.builder()
+       .version(ServerApiVersion.V1)
+       .build()
+   
+   val uri = "<connection string>"
+   
+   val settings = MongoClientSettings.builder()
+       .applyConnectionString(ConnectionString(uri))
+       .serverApi(serverApi)
+       .build()
+   
+   val client = MongoClient.create(settings)
+
+.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.

source/includes/connect/compression-tabs.rst

@@ -0,0 +1,27 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString("<connection string>"))
+             .compressorList(
+                 listOf(
+                     MongoCompressor.createSnappyCompressor(),
+                     MongoCompressor.createZlibCompressor(),
+                     MongoCompressor.createZstdCompressor())
+             )
+             .build()
+
+         val mongoClient = MongoClient.create(settings)
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = ConnectionString("mongodb+srv://<user>:<password>@<cluster-url>/?compressors=snappy,zlib,zstd")
+         
+         val mongoClient = MongoClient.create(uri)

source/includes/connect/disable-host-verification-tabs.rst

@@ -0,0 +1,24 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString("<connection string>"))
+             .applyToSslSettings { builder ->
+                 builder.enabled(true)
+                 builder.invalidHostNameAllowed(true)
+             }
+             .build()
+         val mongoClient = MongoClient.create(settings);
+
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = "mongodb://<username>:<password>@<hostname>:<port>/?"tls=true&tlsAllowInvalidHostnames=true"
+         val mongoClient = MongoClient.create(uri)

source/includes/connect/tls-tabs.rst

@@ -0,0 +1,24 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString("<connection string>"))
+             .applyToSslSettings { builder ->
+                 builder.enabled(true)
+             }
+             .build()
+             
+         val mongoClient = MongoClient.create(settings)
+
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = "mongodb+srv://<user>:<password>@<cluster-url>?tls=true"
+         val mongoClient = MongoClient.create(uri)

source/includes/connect/zlib-level-tabs.rst

@@ -0,0 +1,26 @@
+.. tabs::
+
+   .. tab:: MongoClient
+      :tabid: mongoclient
+
+      .. code-block:: kotlin
+
+         val zlib = MongoCompressor.createZlibCompressor()
+
+         val settings = MongoClientSettings.builder()
+             .applyConnectionString(ConnectionString(uri))
+             .compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, <level>)))
+             .build()
+
+         val mongoClient = MongoClient.create(settings)
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: kotlin
+
+         val uri = "mongodb://<username>:<password>@<hostname>:<port>/?" +
+                   "compressors=zlib" +
+                   "zlibCompressionLevel=<zlib compression level>"
+         
+         val mongoClient = MongoClient.create(uri)

source/includes/indexes/indexes.kt

@@ -0,0 +1,72 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.Indexes
+import com.mongodb.client.model.Filters
+import com.mongodb.client.model.Sorts
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.codecs.pojo.annotations.BsonId
+import org.bson.types.ObjectId
+
+// start-movie-class
+data class Movie(
+    @BsonId
+    val id: ObjectId,
+    val title: String? = "",
+    val type: String? = "",
+    val genres: List<String>? = null,
+    val cast: List<String>? = null,
+    val plot: String? = "",
+)
+// end-movie-class
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+    val database = mongoClient.getDatabase("sample_mflix")
+    val collection = database.getCollection<Movie>("movies")
+
+    // start-remove-index
+    collection.dropIndex("_title_")
+    // end-remove-index
+
+    // start-remove-all-indexes
+    collection.dropIndexes()
+    // end-remove-all-indexes
+
+    // start-index-single
+    collection.createIndex(Indexes.ascending(Movie::title.name))
+    // end-index-single
+
+    // start-index-single-query
+    val filter = Filters.eq(Movie::title.name, "Batman")
+    val sort = Sorts.ascending(Movie::title.name)
+    val results = collection.find(filter).sort(sort)
+
+    results.forEach { result ->
+        println(result)
+    }
+    // end-index-single-query
+
+    // start-index-compound
+    collection.createIndex(Indexes.ascending(Movie::type.name, Movie::genres.name))
+    // end-index-compound
+
+    // start-index-compound-query
+    val filter = and(
+        eq(Movie::type.name, "movie"),
+        `in`(Movie::genres.name, "Drama")
+    )
+    val sort = Sorts.ascending(Movie::type.name, Movie::genres.name)
+    val results = collection.find(filter).sort(sort)
+
+    results.forEach { result ->
+        println(result)
+    }
+    // end-index-compound-query
+}