From 013a730ab901070dd186c137d566f050f233aa74 Mon Sep 17 00:00:00 2001 From: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Date: Mon, 22 Apr 2024 13:25:49 -0700 Subject: [PATCH 01/13] DOCSP-38547 Standardize Quick Start Title (#159) (cherry picked from commit f5c69fcd52c4c69dbd9313fc1a72c90e06897d07) --- source/index.txt | 2 +- source/quick-start.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/index.txt b/source/index.txt index 12b0850b..1baaa6f8 100644 --- a/source/index.txt +++ b/source/index.txt @@ -6,7 +6,7 @@ MongoDB Kotlin Driver :titlesonly: :maxdepth: 1 - /quick-start + Quick Start /quick-reference /whats-new /usage-examples diff --git a/source/quick-start.txt b/source/quick-start.txt index 29e30933..114e2b78 100644 --- a/source/quick-start.txt +++ b/source/quick-start.txt @@ -1,8 +1,8 @@ .. _kotlin-quickstart: -=========== -Quick Start -=========== +========================= +Kotlin Driver Quick Start +========================= .. facet:: :name: genre From bd434e8de3a4abe542415efde80d4b83d7d9d41c Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 18 Jul 2024 11:08:55 -0400 Subject: [PATCH 02/13] typo fix (cherry picked from commit 2390577e0c26f9541beffde02d08ff4c6a0cd023) --- source/fundamentals/connection/connection-options.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/connection/connection-options.txt b/source/fundamentals/connection/connection-options.txt index e972ecc1..0cdcaf90 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/fundamentals/connection/connection-options.txt @@ -122,10 +122,10 @@ parameters of the connection URI to specify the behavior of the client. * - **maxIdleTimeMS** - integer - - Specifies the maximum amount of time, in milliseconds, the Kotlin - driver will allow a pooled connection to idle before closing the + - Specifies the maximum amount of time, in milliseconds, that the driver + allows a pooled connection to idle before closing the connection. A value of ``0`` indicates that there is no upper bound - on how long the driver can allow a pooled collection to be idle. + on how long the driver allows a pooled connection to be idle. | **Default**: ``0`` From cb21ee6a263beb62366c34e65d8031c5f648b4a9 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 14 Aug 2024 15:19:57 -0400 Subject: [PATCH 03/13] Use sharedincludes in compat --- source/compatibility.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/compatibility.txt b/source/compatibility.txt index 57f71dda..258db22d 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -23,7 +23,7 @@ The first column lists the driver version. .. sharedinclude:: dbx/compatibility-table-legend.rst -.. include:: /includes/mongodb-compatibility-table-kotlin.rst +.. sharedinclude:: dbx/mongodb-compatibility-table-kotlin.rst Language Compatibility ---------------------- @@ -33,7 +33,7 @@ of the {+driver-long+} for use with a specific version of Kotlin. The first column lists the driver version. -.. include:: /includes/language-compatibility-table-kotlin.rst +.. sharedinclude:: dbx/language-compatibility-table-kotlin.rst For more information on how to read the compatibility tables, see our guide on :ref:`MongoDB Compatibility Tables `. From d2539692e7f99d233b08e91ab9e133991d93b54a Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Thu, 29 Aug 2024 08:32:06 -0700 Subject: [PATCH 04/13] DOCSP-41760 Add transactions page (#167) * Add transactions page, add language variable, include code snippet for transactions --------- Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Co-authored-by: Brandon Ly Co-authored-by: rustagir (cherry picked from commit e0c22eefa3a8346be0cbeeed213abe9f358ff030) --- examples/src/test/kotlin/SearchIndexesTest.kt | 1 - examples/src/test/kotlin/TransactionsTest.kt | 86 ++++++++++++ snooty.toml | 1 + .../TransactionsTest.snippet.data-class.kt | 4 + ...ctionsTest.snippet.transaction-function.kt | 31 +++++ source/fundamentals.txt | 1 + source/fundamentals/transactions.txt | 130 ++++++++++++++++++ 7 files changed, 253 insertions(+), 1 deletion(-) create mode 100644 examples/src/test/kotlin/TransactionsTest.kt create mode 100644 source/examples/generated/TransactionsTest.snippet.data-class.kt create mode 100644 source/examples/generated/TransactionsTest.snippet.transaction-function.kt create mode 100644 source/fundamentals/transactions.txt diff --git a/examples/src/test/kotlin/SearchIndexesTest.kt b/examples/src/test/kotlin/SearchIndexesTest.kt index c7d4fcf3..cbc4f1f0 100644 --- a/examples/src/test/kotlin/SearchIndexesTest.kt +++ b/examples/src/test/kotlin/SearchIndexesTest.kt @@ -53,7 +53,6 @@ class SearchIndexesTest { } @Ignore - @Test fun multipleSearchIndexTest() = runBlocking { // :snippet-start: multi-search-index-create val indexOne = SearchIndexModel( diff --git a/examples/src/test/kotlin/TransactionsTest.kt b/examples/src/test/kotlin/TransactionsTest.kt new file mode 100644 index 00000000..dfd758bd --- /dev/null +++ b/examples/src/test/kotlin/TransactionsTest.kt @@ -0,0 +1,86 @@ +import com.mongodb.kotlin.client.coroutine.MongoClient +import com.mongodb.client.model.Filters.eq +import com.mongodb.client.model.Updates.inc +import config.getConfig +import kotlinx.coroutines.runBlocking +import org.junit.jupiter.api.AfterAll +import org.junit.jupiter.api.Assertions.assertNotNull +import org.junit.jupiter.api.BeforeAll +import org.junit.jupiter.api.Test +import org.junit.jupiter.api.TestInstance + +@TestInstance(TestInstance.Lifecycle.PER_CLASS) +class TransactionsTest { + + // :snippet-start: data-class + data class Account( + val accountId: String, + val amount: Int + ) + // :snippet-end: + + companion object { + val config = getConfig() + val client = MongoClient.create(config.connectionUri) + val database = client.getDatabase("bank") + + @BeforeAll + @JvmStatic + fun beforeAll() { + runBlocking { + val savAcct = Account("9876", 900) + database.getCollection("savings_accounts").insertOne(savAcct) + + val chkAcct = Account("9876", 50) + database.getCollection("checking_accounts").insertOne(chkAcct) + } + } + + @AfterAll + @JvmStatic + fun afterAll() { + runBlocking { + database.drop() + client.close() + } + } + } + + @Test + fun transactionTest() = runBlocking { + // :snippet-start: transaction-function + // Set up the session + val session = client.startSession() + + try { + session.startTransaction() + + val savingsColl = database + .getCollection("savings_accounts") + val checkingColl = database + .getCollection("checking_accounts") + + savingsColl.findOneAndUpdate( + session, + eq(Account::accountId.name, "9876"), + inc(Account::amount.name, -100), + ) + + checkingColl.findOneAndUpdate( + session, + eq(Account::accountId.name, "9876"), + inc(Account::amount.name, 100) + ) + + // Commit the transaction + val result = session.commitTransaction() + println("Transaction committed.") + assertNotNull(result) // :remove: + } catch (error: Exception) { + println("An error occurred during the transaction: ${error.message}") + // Abort the transaction + session.abortTransaction() + } + // :snippet-end: + } +} diff --git a/snooty.toml b/snooty.toml index e50f8c57..e32f5c01 100644 --- a/snooty.toml +++ b/snooty.toml @@ -21,6 +21,7 @@ driver-short = "Kotlin driver" driver-long = "MongoDB Kotlin Driver" version = "5.0" full-version = "{+version+}.0" +language = "Kotlin" mdb-server = "MongoDB server" kotlin-docs = "https://kotlinlang.org" diff --git a/source/examples/generated/TransactionsTest.snippet.data-class.kt b/source/examples/generated/TransactionsTest.snippet.data-class.kt new file mode 100644 index 00000000..45f6c152 --- /dev/null +++ b/source/examples/generated/TransactionsTest.snippet.data-class.kt @@ -0,0 +1,4 @@ +data class Account( + val accountId: String, + val amount: Int +) diff --git a/source/examples/generated/TransactionsTest.snippet.transaction-function.kt b/source/examples/generated/TransactionsTest.snippet.transaction-function.kt new file mode 100644 index 00000000..2ce7b0b5 --- /dev/null +++ b/source/examples/generated/TransactionsTest.snippet.transaction-function.kt @@ -0,0 +1,31 @@ +// Set up the session +val session = client.startSession() + +try { + session.startTransaction() + + val savingsColl = database + .getCollection("savings_accounts") + val checkingColl = database + .getCollection("checking_accounts") + + savingsColl.findOneAndUpdate( + session, + eq(Account::accountId.name, "9876"), + inc(Account::amount.name, -100), + ) + + checkingColl.findOneAndUpdate( + session, + eq(Account::accountId.name, "9876"), + inc(Account::amount.name, 100) + ) + + // Commit the transaction + val result = session.commitTransaction() + println("Transaction committed.") +} catch (error: Exception) { + println("An error occurred during the transaction: ${error.message}") + // Abort the transaction + session.abortTransaction() +} diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 1ef41c30..a44f2708 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -19,6 +19,7 @@ Fundamentals /fundamentals/aggregation /fundamentals/aggregation-expression-operations /fundamentals/indexes + /fundamentals/transactions /fundamentals/collations /fundamentals/logging /fundamentals/monitoring diff --git a/source/fundamentals/transactions.txt b/source/fundamentals/transactions.txt new file mode 100644 index 00000000..0656b5cd --- /dev/null +++ b/source/fundamentals/transactions.txt @@ -0,0 +1,130 @@ +.. _kotlin-fundamentals-transactions: + +============ +Transactions +============ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: modify, customize + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to perform +**transactions**. :manual:`Transactions ` allow +you to run a series of operations that do not change any data until the +transaction is committed. If any operation in the transaction returns an +error, the driver cancels the transaction and discards all data changes +before they ever become visible. + +In MongoDB, transactions run within logical **sessions**. A +:manual:`session ` is a grouping of related +read or write operations that you intend to run sequentially. Sessions +enable :manual:`causal consistency +` for a +group of operations or allow you to execute operations in an +:website:`ACID transaction `. MongoDB +guarantees that the data involved in your transaction operations remains +consistent, even if the operations encounter unexpected errors. + +When using the {+driver-short+}, you can create a new session from a +``MongoClient`` instance as a ``ClientSession``. We recommend that you reuse +your client for multiple sessions and transactions instead of +instantiating a new client each time. + +.. warning:: + + Use a ``ClientSession`` only with the ``MongoClient`` (or associated + ``MongoDatabase`` or ``MongoCollection``) that created it. Using a + ``ClientSession`` with a different ``MongoClient`` results in operation + errors. + +Methods +------- + +Create a ``ClientSession`` by using the ``startSession()`` method on your +``Client`` instance. You can then modify the session state by using the +following methods: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Method + - Description + + * - ``startTransaction()`` + - | Starts a new transaction for this session with the + default transaction options. You cannot start a + transaction if there's already an active transaction + on the session. + | + | To set transaction options, use ``startTransaction(transactionOptions: TransactionOptions)``. + + * - ``abortTransaction()`` + - | Ends the active transaction for this session. Returns an error + if there is no active transaction for the + session or the transaction was previously ended. + + * - ``commitTransaction()`` + - | Commits the active transaction for this session. Returns an + error if there is no active transaction for the session or if the + transaction was ended. + +A ``ClientSession`` also has methods to retrieve session properties and modify +mutable session properties. View the `API documentation <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-client-session/index.html>`__ +to learn more about these methods. + +Example +------- + +This example uses the following {+language+} data class to model its documents: + +.. literalinclude:: /examples/generated/TransactionsTest.snippet.data-class.kt + :language: kotlin + +The following example demonstrates how you can create a session, create a transaction, +and commit changes to existing documents: + +1. Create a session from the client using the ``startSession()`` method. +#. Use the ``startTransaction()`` method to start a transaction. +#. Update the specified documents, then use the ``commitTransaction()`` method if all + operations succeed, or ``abortTransaction()`` if any operations fail. + +.. literalinclude:: /examples/generated/TransactionsTest.snippet.transaction-function.kt + :language: kotlin + +Additional Information +---------------------- + +To learn more about the concepts mentioned in this guide, see the following pages in +the Server manual: + +- :manual:`Transactions ` +- :manual:`Server Sessions ` +- :manual:`Read Isolation, Consistency, and Recency ` + +To learn more about ACID compliance, see the :website:`What are ACID +Properties in Database Management Systems? ` +article on the MongoDB website. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the types or methods discussed in this +guide, see the following API Documentation: + +- `ClientSession <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-client-session/index.html>`__ +- `startTransaction <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-client-session/start-transaction.html>`__ +- `commitTransaction <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-client-session/commit-transaction.html>`__ +- `abortTransaction <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-client-session/abort-transaction.html>`__ From d54e4b7e90acc9eb3e6306ad39ef5a23f84305d6 Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Fri, 30 Aug 2024 09:34:37 -0500 Subject: [PATCH 05/13] Add files via upload --- build.sh | 8 ++++++++ netlify.toml | 9 +++++++++ 2 files changed, 17 insertions(+) create mode 100644 build.sh create mode 100644 netlify.toml diff --git a/build.sh b/build.sh new file mode 100644 index 00000000..b62b6772 --- /dev/null +++ b/build.sh @@ -0,0 +1,8 @@ +# ensures that we always use the latest version of the script +if [ -f build-site.sh ]; then + rm build-site.sh +fi + + +curl https://raw.githubusercontent.com/mongodb/docs-worker-pool/netlify-poc/scripts/build-site.sh -o build-site.sh +sh build-site.sh \ No newline at end of file diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 00000000..2d0a3b98 --- /dev/null +++ b/netlify.toml @@ -0,0 +1,9 @@ +[[integrations]] +name = "snooty-cache-plugin" + +# Production context: all deploys from the Production branch +# set in your site’s Branches settings in the UI will inherit +# these settings. +[build] +publish = "snooty/public" +command = ". ./build.sh" From c1b1e753401cc3a6b4dc2f132882a352fdf902b0 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 27 Sep 2024 12:08:44 -0400 Subject: [PATCH 06/13] encrypt fields embeddings (cherry picked from commit 05b10e47c91812482cdf81fe4fe0525303e7731c) (cherry picked from commit 4a1c4ef55d86b8a2a6fccfae8db00ff8dbebf250) --- snooty.toml | 2 +- source/fundamentals/encrypt-fields.txt | 25 +++++++++++++++++++ .../code-snippets/crypt-gradle-versioned.rst | 5 ++++ .../code-snippets/crypt-maven-versioned.rst | 9 +++++++ 4 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst create mode 100644 source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst diff --git a/snooty.toml b/snooty.toml index e32f5c01..1751b631 100644 --- a/snooty.toml +++ b/snooty.toml @@ -28,7 +28,7 @@ kotlin-docs = "https://kotlinlang.org" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" stable-api = "Stable API" -mongocrypt-version = "1.7.3" +mongocrypt-version = "{+full-version+}" nettyVersion = "io.netty:netty-all:4.1.79.Final" snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4" zstdVersion = "com.github.luben:zstd-jni:1.5.5-2" diff --git a/source/fundamentals/encrypt-fields.txt b/source/fundamentals/encrypt-fields.txt index b66b6623..0fa23918 100644 --- a/source/fundamentals/encrypt-fields.txt +++ b/source/fundamentals/encrypt-fields.txt @@ -1,3 +1,28 @@ .. _kotlin-fle: .. sharedinclude:: dbx/encrypt-fields.rst + + .. replacement:: driver-specific-content + + .. important:: Compatible Encryption Library Version + + The {+driver-short+} uses the `mongodb-crypt + `__ + encryption library for in-use encryption. This driver version + is compatible with ``mongodb-crypt`` v{+mongocrypt-version+}. + + Select from the following :guilabel:`Maven` and + :guilabel:`Gradle` tabs to see how to add the ``mongodb-crypt`` + dependency to your project by using the specified manager: + + .. tabs:: + + .. tab:: Maven + :tabid: maven-dependency + + .. include:: /includes/fundamentals/code-snippets/crypt-maven-versioned.rst + + .. tab:: Gradle + :tabid: gradle-dependency + + .. include:: /includes/fundamentals/code-snippets/crypt-gradle-versioned.rst diff --git a/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst b/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst new file mode 100644 index 00000000..af6427b6 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst @@ -0,0 +1,5 @@ +.. code-block:: groovy + + dependencies { + implementation("org.mongodb:mongodb-crypt:{+mongocrypt-version+}") + } \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst b/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst new file mode 100644 index 00000000..0b2c3b0e --- /dev/null +++ b/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst @@ -0,0 +1,9 @@ +.. code-block:: xml + + + + org.mongodb + mongodb-crypt + {+mongocrypt-version+} + + From bc219949c49048708e10dc15bbbc6d816e48bcb1 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 27 Sep 2024 12:16:00 -0400 Subject: [PATCH 07/13] update crypt source constant --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index 1751b631..a5f26637 100644 --- a/snooty.toml +++ b/snooty.toml @@ -28,7 +28,7 @@ kotlin-docs = "https://kotlinlang.org" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" stable-api = "Stable API" -mongocrypt-version = "{+full-version+}" +mongocrypt-version = "1.8.0" nettyVersion = "io.netty:netty-all:4.1.79.Final" snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4" zstdVersion = "com.github.luben:zstd-jni:1.5.5-2" From decf207503ee7f0c0e75c48796daa4087e409dc2 Mon Sep 17 00:00:00 2001 From: Caitlin Davey Date: Thu, 24 Oct 2024 15:32:42 -0400 Subject: [PATCH 08/13] Following guidance, removing nested components from tables (#178) (cherry picked from commit 473088d0d40a91925406d164b95cf664d8adf6b3) --- .../connection/mongoclientsettings.txt | 18 ++++++++---------- .../document-data-format-data-class.txt | 8 +++----- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/source/fundamentals/connection/mongoclientsettings.txt b/source/fundamentals/connection/mongoclientsettings.txt index 84943672..72b1e855 100644 --- a/source/fundamentals/connection/mongoclientsettings.txt +++ b/source/fundamentals/connection/mongoclientsettings.txt @@ -230,18 +230,16 @@ settings to modify the driver's behavior: - Sets the host name to use to look up an SRV DNS record to find the MongoDB hosts. - .. note:: + When setting ``srvHost``, the driver does not process any + associated TXT records associated with the host. - When setting ``srvHost``, the driver does not process any - associated TXT records associated with the host. + If you want to enable the processing of TXT records, you must + specify the SRV host in the connection string using the + ``applyConnectionString()`` method. - If you want to enable the processing of TXT records, you must - specify the SRV host in the connection string using the - ``applyConnectionString()`` method. - - .. literalinclude:: /examples/generated/MongoClientSettingsTest.snippet.srv-host-connection-string.kt - :language: kotlin - :emphasize-lines: 3 + .. literalinclude:: /examples/generated/MongoClientSettingsTest.snippet.srv-host-connection-string.kt + :language: kotlin + :emphasize-lines: 3 * - ``srvMaxHosts()`` - | Sets the maximum number of hosts the driver can connect to when using diff --git a/source/fundamentals/data-formats/document-data-format-data-class.txt b/source/fundamentals/data-formats/document-data-format-data-class.txt index 2a7171fd..aa47b367 100644 --- a/source/fundamentals/data-formats/document-data-format-data-class.txt +++ b/source/fundamentals/data-formats/document-data-format-data-class.txt @@ -115,12 +115,10 @@ You can use the following annotations on data classes: - Specifies the BSON type MongoDB uses to store the value. Use this annotation only when you need to store a value as a different BSON type than the data class property. - - .. warning:: - Your code might throw an exception if you include the - ``BsonRepresentation`` annotation on a property that you store - as the same type as the data class property. + :red:`WARNING:` Your code might throw an exception if you include the + ``BsonRepresentation`` annotation on a property that you store + as the same type as the data class property. For reference information on these property annotations, refer to the `org.bson.codecs.pojo.annotations <{+api+}/apidocs/bson/org/bson/codecs/pojo/annotations/package-summary.html>`__ From a479928381d77d39f45c1a609a40ecbaf7f12b88 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Thu, 21 Nov 2024 18:20:04 -0500 Subject: [PATCH 09/13] [Backport v5.0] DOCSP-44902 TOC Relabel (#179) (#181) (#182) (#183) * DOCSP-44902 TOC Relabel (#179) (#181) (#182) * DOCSP-44902 TOC Relabel * DOCSP-44902 TOC Relabel * Mike's suggestions * 'one/many' operation changes (cherry picked from commit 1144bde00f5ce107638a6d2664abce2ea62aad3b) Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> (cherry picked from commit bc41eefcc7e17f719a9a4a50344cdab7d8ad16e1) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> (cherry picked from commit 39747b227a515b77978fb514b4db2234f568397c) * backport action --- .github/workflows/backport.yml | 26 ++++++++++++++++ source/fundamentals.txt | 34 ++++++++++----------- source/fundamentals/builders.txt | 12 ++++---- source/fundamentals/connection.txt | 12 ++++---- source/fundamentals/crud.txt | 8 ++--- source/fundamentals/data-formats.txt | 20 ++++++------ source/index.txt | 20 ++++++------ source/usage-examples.txt | 19 ++++++------ source/usage-examples/delete-operations.txt | 10 +++--- source/usage-examples/find-operations.txt | 10 +++--- source/usage-examples/insert-operations.txt | 10 +++--- source/usage-examples/update-operations.txt | 14 ++++----- 12 files changed, 110 insertions(+), 85 deletions(-) create mode 100644 .github/workflows/backport.yml diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml new file mode 100644 index 00000000..971e8a65 --- /dev/null +++ b/.github/workflows/backport.yml @@ -0,0 +1,26 @@ +name: Backport +on: + pull_request_target: + types: + - closed + - labeled + +jobs: + backport: + name: Backport + runs-on: ubuntu-latest + # Only react to merged PRs for security reasons. + # See https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target. + if: > + github.event.pull_request.merged + && ( + github.event.action == 'closed' + || ( + github.event.action == 'labeled' + && contains(github.event.label.name, 'backport') + ) + ) + steps: + - uses: tibdex/backport@v2 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/source/fundamentals.txt b/source/fundamentals.txt index a44f2708..9ea37b6c 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -8,23 +8,23 @@ Fundamentals :titlesonly: :maxdepth: 1 - /fundamentals/connection - /fundamentals/auth - /fundamentals/enterprise-auth - /fundamentals/stable-api - /fundamentals/databases-collections - /fundamentals/data-formats - /fundamentals/crud - /fundamentals/builders - /fundamentals/aggregation - /fundamentals/aggregation-expression-operations - /fundamentals/indexes - /fundamentals/transactions - /fundamentals/collations - /fundamentals/logging - /fundamentals/monitoring - /fundamentals/time-series - /fundamentals/encrypt-fields + Connection Guide + Authentication + Enterprise Authentication + Stable API + Databases & Collections + Data Formats + CRUD Operations /fundamentals/crud + Builders + Aggregation + Aggregation Expressions + Indexes + Transactions + Collations + Logging + Monitoring + Time Series Collections + In-Use Encryption .. TODO : add back in after MVP .. /fundamentals/gridfs diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 4660b942..7bd54273 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -6,12 +6,12 @@ Builders .. toctree:: - /fundamentals/builders/aggregates - /fundamentals/builders/filters - /fundamentals/builders/indexes - /fundamentals/builders/projections - /fundamentals/builders/sort - /fundamentals/builders/updates + Aggregation + Filters + Indexes + Projection + Sort + Update .. contents:: On this page :local: diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index 5c8de999..8aed7e10 100644 --- a/source/fundamentals/connection.txt +++ b/source/fundamentals/connection.txt @@ -6,12 +6,12 @@ Connection Guide .. toctree:: - /fundamentals/connection/connect - /fundamentals/connection/connection-options - /fundamentals/connection/mongoclientsettings - /fundamentals/connection/network-compression - /fundamentals/connection/tls - /fundamentals/connection/socks5 + Connect to MongoDB + Connection Options + MongoClient Settings + Network Compression + TLS/SSL + SOCKS5 Proxy Connection .. contents:: On this page :local: diff --git a/source/fundamentals/crud.txt b/source/fundamentals/crud.txt index 80eb72ab..ea152d08 100644 --- a/source/fundamentals/crud.txt +++ b/source/fundamentals/crud.txt @@ -7,10 +7,10 @@ CRUD Operations .. toctree:: :caption: CRUD Operations - /fundamentals/crud/read-operations - /fundamentals/crud/write-operations - /fundamentals/crud/query-document - /fundamentals/crud/compound-operations + Read + Write + Query + Compound Operations CRUD (Create, Read, Update, Delete) operations enable you to work with data stored in MongoDB. diff --git a/source/fundamentals/data-formats.txt b/source/fundamentals/data-formats.txt index 03036c47..5737e098 100644 --- a/source/fundamentals/data-formats.txt +++ b/source/fundamentals/data-formats.txt @@ -2,19 +2,19 @@ Data Formats ============ +.. toctree:: + :caption: Data Formats + + Data Classes + BSON + Extended JSON + Documents + Kotlin Serialization + Codecs + - :doc:`/fundamentals/data-formats/document-data-format-data-class` - :doc:`/fundamentals/data-formats/document-data-format-bson` - :doc:`/fundamentals/data-formats/document-data-format-extended-json` - :doc:`/fundamentals/data-formats/documents` - :doc:`/fundamentals/data-formats/serialization` - :doc:`/fundamentals/data-formats/codecs` - -.. toctree:: - :caption: Data Formats - - /fundamentals/data-formats/document-data-format-data-class - /fundamentals/data-formats/document-data-format-bson - /fundamentals/data-formats/document-data-format-extended-json - /fundamentals/data-formats/documents - /fundamentals/data-formats/serialization - /fundamentals/data-formats/codecs diff --git a/source/index.txt b/source/index.txt index 1baaa6f8..7cc0269a 100644 --- a/source/index.txt +++ b/source/index.txt @@ -7,16 +7,16 @@ MongoDB Kotlin Driver :maxdepth: 1 Quick Start - /quick-reference - /whats-new - /usage-examples - /fundamentals - /api-documentation - /faq - /connection-troubleshooting - /issues-and-help - /compatibility - /migrate-kmongo + Quick Reference + What's New + Usage Examples + Fundamentals + API Documentation + FAQ + Connection Troubleshooting + Issues & Help + Compatibility + Migrate from KMongo View the Source Introduction diff --git a/source/usage-examples.txt b/source/usage-examples.txt index 1e3844c2..56cb08d2 100644 --- a/source/usage-examples.txt +++ b/source/usage-examples.txt @@ -10,16 +10,15 @@ Usage Examples .. toctree:: - /usage-examples/find-operations - /usage-examples/insert-operations - /usage-examples/update-operations - /usage-examples/delete-operations - /usage-examples/bulkWrite - /usage-examples/watch - /usage-examples/count - /usage-examples/distinct - /usage-examples/command - + Find + Insert + Update & Replaces + Delete + Bulk Operations + Watch for Changes + Count Documents + Distinct Field Values + Run a Command Overview -------- diff --git a/source/usage-examples/delete-operations.txt b/source/usage-examples/delete-operations.txt index dc6f748e..f1574e01 100644 --- a/source/usage-examples/delete-operations.txt +++ b/source/usage-examples/delete-operations.txt @@ -2,12 +2,12 @@ Delete Operations ================= -- :doc:`Delete a Document ` -- :doc:`Delete Multiple Documents ` - .. toctree:: :caption: Examples - /usage-examples/deleteOne - /usage-examples/deleteMany + Delete One + Delete Many + +- :doc:`Delete a Document ` +- :doc:`Delete Multiple Documents ` \ No newline at end of file diff --git a/source/usage-examples/find-operations.txt b/source/usage-examples/find-operations.txt index faa91153..17d2f6d8 100644 --- a/source/usage-examples/find-operations.txt +++ b/source/usage-examples/find-operations.txt @@ -2,11 +2,11 @@ Find Operations =============== -- :doc:`Find a Document ` -- :doc:`Find Multiple Documents ` - .. toctree:: :caption: Examples - /usage-examples/findOne - /usage-examples/find + Find One + Find Many + +- :doc:`Find a Document ` +- :doc:`Find Multiple Documents ` diff --git a/source/usage-examples/insert-operations.txt b/source/usage-examples/insert-operations.txt index 05005b02..74fe1d7a 100644 --- a/source/usage-examples/insert-operations.txt +++ b/source/usage-examples/insert-operations.txt @@ -2,11 +2,11 @@ Insert Operations ================= -- :doc:`Insert a Document ` -- :doc:`Insert Multiple Documents ` - .. toctree:: :caption: Examples - /usage-examples/insertOne - /usage-examples/insertMany + Insert One + Insert Many + +- :doc:`Insert a Document ` +- :doc:`Insert Multiple Documents ` diff --git a/source/usage-examples/update-operations.txt b/source/usage-examples/update-operations.txt index 802aefff..0513e947 100644 --- a/source/usage-examples/update-operations.txt +++ b/source/usage-examples/update-operations.txt @@ -2,13 +2,13 @@ Update & Replace Operations =========================== -- :doc:`Update a Document ` -- :doc:`Update Multiple Documents ` -- :doc:`Replace a Document ` - .. toctree:: :caption: Examples - /usage-examples/updateOne - /usage-examples/updateMany - /usage-examples/replaceOne + Update One + Update Many + Replace One + +- :doc:`Update a Document ` +- :doc:`Update Multiple Documents ` +- :doc:`Replace a Document ` From 10ee1230b3d6893dd8d4bdc3e34e3b05d855c1b5 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 16 Jan 2025 10:55:52 -0500 Subject: [PATCH 10/13] add Crud link --- source/fundamentals.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 9ea37b6c..20d6cb62 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -14,7 +14,7 @@ Fundamentals Stable API Databases & Collections Data Formats - CRUD Operations /fundamentals/crud + CRUD Operations Builders Aggregation Aggregation Expressions From 834ae9bc079950b45e49b1540292f1e6cb2740f1 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 11 Mar 2025 10:24:34 -0400 Subject: [PATCH 11/13] DOCSP-48207-404s (#203) (cherry picked from commit e10923bd8bb6e49dc2c6a7e260da5b8ecae7890d) --- examples/src/test/kotlin/RetrieveDataTest.kt | 2 +- source/fundamentals/aggregation.txt | 4 +- source/fundamentals/crud/query-document.txt | 2 + .../fundamentals/crud/read-operations/geo.txt | 158 +++++++++--------- .../crud/read-operations/retrieve.txt | 88 +++++----- 5 files changed, 133 insertions(+), 121 deletions(-) diff --git a/examples/src/test/kotlin/RetrieveDataTest.kt b/examples/src/test/kotlin/RetrieveDataTest.kt index a94b3fda..6ffc2f62 100644 --- a/examples/src/test/kotlin/RetrieveDataTest.kt +++ b/examples/src/test/kotlin/RetrieveDataTest.kt @@ -28,7 +28,7 @@ internal class RetrieveDataTest { private val config = getConfig() private val client = MongoClient.create(config.connectionUri) private val database = client.getDatabase("retrieve_data") - val collection = database.getCollection("paint_order") + val collection = database.getCollection("orders") @BeforeAll @JvmStatic diff --git a/source/fundamentals/aggregation.txt b/source/fundamentals/aggregation.txt index 1088fec6..86d728fb 100644 --- a/source/fundamentals/aggregation.txt +++ b/source/fundamentals/aggregation.txt @@ -1,3 +1,5 @@ +.. _kotlin-aggregation: + =========== Aggregation =========== @@ -11,8 +13,6 @@ Aggregation Overview -------- -.. _kotlin-aggregation: - In this guide, you can learn how to use **aggregation operations** in the MongoDB Kotlin driver. Aggregation operations process data in your MongoDB collections and return computed results. MongoDB's Aggregation diff --git a/source/fundamentals/crud/query-document.txt b/source/fundamentals/crud/query-document.txt index af9f44d7..1e422f13 100644 --- a/source/fundamentals/crud/query-document.txt +++ b/source/fundamentals/crud/query-document.txt @@ -1,3 +1,5 @@ +.. _kotlin-fundamentals-query: + =============== Specify a Query =============== diff --git a/source/fundamentals/crud/read-operations/geo.txt b/source/fundamentals/crud/read-operations/geo.txt index 3665d5d4..53a8fc8b 100644 --- a/source/fundamentals/crud/read-operations/geo.txt +++ b/source/fundamentals/crud/read-operations/geo.txt @@ -1,7 +1,16 @@ +.. _kotlin-fundamentals-geospatial-search: + =================== Search Geospatially =================== +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, coordinates, plane, earth + .. contents:: On this page :local: :backlinks: none @@ -11,8 +20,9 @@ Search Geospatially Overview -------- -In this guide, you can learn how to search **geospatial data** with the -MongoDB Kotlin Driver, and the different geospatial data formats supported by MongoDB. +In this guide, you can learn how to query **geospatial data** by using +the {+driver-short+}. You can also learn about different geospatial data +formats supported by MongoDB. Geospatial data is data that represents a geographical location on the surface of the Earth. Examples of geospatial data include: @@ -32,7 +42,7 @@ Here is the location of MongoDB headquarters in GeoJSON: .. code-block:: json - "MongoDB Headquarters" : { + "location" : { "type": "point", "coordinates": [-73.986805, 40.7620853] } @@ -43,7 +53,7 @@ For definitive information on GeoJSON, see the GeoJSON Positions ~~~~~~~~~~~~~~~~~ -A position represents a single place on Earth, and exists in code as an array +A position represents a single place on Earth and is given as an array containing two or three number values: - Longitude in the first position (required) @@ -52,11 +62,11 @@ containing two or three number values: .. important:: Longitude then Latitude - GeoJSON orders coordinates as longitude first and latitude second. This may - be surprising as geographic coordinate system conventions generally list - latitude first and longitude second. Make sure to check what format any other - tools you are working with use. Popular tools such as OpenStreetMap and Google - Maps list coordinates as latitude first and longitude second. + GeoJSON orders coordinates as longitude first and latitude second. This may + be surprising as geographic coordinate system conventions generally list + latitude first and longitude second. Make sure to check what format any other + tools you are working with use. Popular tools such as OpenStreetMap and Google + Maps list coordinates as latitude first and longitude second. GeoJSON Types ~~~~~~~~~~~~~ @@ -66,46 +76,46 @@ made up of positions. Here are some common GeoJSON types and how you can specify them with positions: -- ``Point``: a single position. This could represent the location of a - `sculpture `__. -- ``LineString``: an array of two or more positions, thus forming a series of line +- ``Point``: Single position. This could represent the location of a + `sculpture `__. +- ``LineString``: Array of two or more positions, thus forming a series of line segments. This could represent `the route of the Great Wall of China `__. -- ``Polygon``: an array of positions in which the first and last - position are the same, thus enclosing some space. This could represent +- ``Polygon``: Array of positions in which the first and last + position are the same, enclosing some space. This could represent `the land within Vatican City `__. - -To learn more about the shapes you can use in MongoDB, see the -:manual:`GeoJSON manual entry `. +To learn more about the shapes you can use in MongoDB, see +:manual:`GeoJSON ` in the Server manual. Index ~~~~~ To query data stored in the GeoJSON format, add the field containing GeoJSON data to a ``2dsphere`` index. The following snippet creates a -``2dsphere`` index on the ``location.geo`` field using the ``Indexes`` builder: +``2dsphere`` index on the ``location.geo`` field by using the +``Indexes`` builder: .. literalinclude:: /examples/generated/GeoTest.snippet.geo2dsphere-index.kt :language: kotlin -For more information on the ``Indexes`` builder, see our -:doc:`guide on the Indexes builder `. +To learn more about the ``Indexes`` builder, see the +:ref:`indexes-builders` guide. Coordinates on a 2D Plane ------------------------- You can store geospatial data using ``x`` and ``y`` coordinates on a two-dimensional Euclidean plane. We refer to coordinates on a two-dimensional -plane as "legacy coordinate pairs". +plane as *legacy coordinate pairs*. Legacy coordinate pairs have the following structure: .. code-block:: json - "" : [ x, y ] + { "location" : [ x, y ] } -Your field should contain an array of two values in which the first represents +The field value contains an array of two values in which the first represents the ``x`` axis value and the second represents the ``y`` axis value. Index @@ -113,23 +123,26 @@ Index To query data stored as legacy coordinate pairs, you must add the field containing legacy coordinate pairs to a ``2d`` index. The following snippet creates a -``2d`` index on the ``coordinates`` field using the ``Indexes`` builder: +``2d`` index on the ``coordinates`` field by using the ``Indexes`` builder: .. literalinclude:: /examples/generated/GeoTest.snippet.geo2d-index.kt :language: kotlin -For more information on the ``Indexes`` builder, see our -:doc:`guide on the Indexes builder `. +To learn more about the ``Indexes`` builder, see the +:ref:`indexes-builders` guide. For more information on legacy coordinate pairs, see the -:manual:`MongoDB server manual page on legacy coordinate pairs `. +:manual:`Legacy Coordinate Pairs +` section of the +Geospatial Queries guide in the Server manual. .. tip:: Supported Operators Spherical (``2dsphere``) and flat (``2d``) indexes support some, but - not all, of the same query operators. For a full list of operators - and their index compatibility, see the - :manual:`manual entry for geospatial queries `. + not all, of the same query operators. To view a full list of operators + and their index compatibility, see the :manual:`Geospatial Query + Operators ` section + of the Geospatial Queries guide in the Server manual. Geospatial Queries ------------------ @@ -151,58 +164,56 @@ You can specify these query operators in the MongoDB Kotlin driver with the ``near()``, ``geoWithin()``, ``nearSphere()``, and ``geoIntersects()`` utility methods of the ``Filters`` builder class. -For more information on geospatial query operators, see the -:manual:`manual entry for geospatial queries `. +To learn more about geospatial query operators, see the :manual:`Geospatial Query +Operators ` section +of the Geospatial Queries guide in the Server manual. -For more information on ``Filters``, see our -:doc:`guide on the Filters builder `. +To learn more about the ``Filters`` builder, see the +:ref:`filters-builders` guide. Query Parameters ~~~~~~~~~~~~~~~~ -To specify a shape to use in a geospatial query, use the -``Position``, ``Point``, ``LineString``, and ``Polygon`` classes of the MongoDB -Kotlin driver. +To specify a shape to use in a geospatial query, use the ``Position``, +``Point``, ``LineString``, and ``Polygon`` classes from the {+driver-short+}. -For a full list of the GeoJSON shapes available in the MongoDB Kotlin driver, see the -`GeoJSON package -<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__ +To learn more about the GeoJSON shape classes, see the +`GeoJSON package <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/geojson/package-summary.html>`__ API Documentation. -Examples --------- +Geospatial Query Examples +------------------------- The following examples use the MongoDB Atlas sample dataset. You can learn how to set up your own free-tier Atlas cluster and how to load the sample dataset -in our :doc:`quick start guide `. +in the :ref:`kotlin-quickstart` guide. The examples use the ``theaters`` collection in the ``sample_mflix`` database from the sample dataset. -The examples require the following imports: +The examples in this section require the following imports: -.. code-block:: - :source: kotlin +.. code-block:: kotlin - import com.mongodb.client.model.geojson.Point - import com.mongodb.client.model.geojson.Polygon - import com.mongodb.client.model.geojson.Position - import com.mongodb.client.model.Filters.near - import com.mongodb.client.model.Filters.geoWithin - import com.mongodb.client.model.Projections.fields - import com.mongodb.client.model.Projections.include - import com.mongodb.client.model.Projections.excludeId + import com.mongodb.client.model.geojson.Point + import com.mongodb.client.model.geojson.Polygon + import com.mongodb.client.model.geojson.Position + import com.mongodb.client.model.Filters.near + import com.mongodb.client.model.Filters.geoWithin + import com.mongodb.client.model.Projections.fields + import com.mongodb.client.model.Projections.include + import com.mongodb.client.model.Projections.excludeId -The data is modeled using the following Kotlin data class: +The sample documents are modeled by the following {+language+} data class: .. literalinclude:: /examples/generated/GeoTest.snippet.theater-data-class.kt - :language: kotlin + :language: kotlin -The results are modeled using the following Kotlin data class: +The result documents are modeled by the following {+language+} data class: .. literalinclude:: /examples/generated/GeoTest.snippet.results-data-class.kt - :language: kotlin - + :language: kotlin + The ``theaters`` collection already contains a ``2dsphere`` index on the ``"${Theater::location.name}.${Theater.Location::geo.name}"`` field. @@ -213,8 +224,8 @@ To search for and return documents from nearest to farthest from a point, use the ``near()`` static utility method of the ``Filters`` builder class. The ``near()`` method constructs a query with the ``$near`` query operator. -The following example queries for theaters between ``10,000`` and ``5,000`` -meters from the Great Lawn of Central Park: +The following example queries for movie theaters between ``10000`` and +``5000`` meters from the Great Lawn of Central Park: .. io-code-block:: @@ -237,17 +248,14 @@ meters from the Great Lawn of Central Park: TheaterResults(location=Location(address=Address(city=Flushing))) TheaterResults(location=Location(address=Address(city=Elmhurst))) -.. tip:: Fun Fact +.. tip:: - MongoDB uses the - :manual:`same reference system ` + MongoDB uses the :manual:`same reference system ` as GPS satellites to calculate geometries over the Earth. -For more information on the ``$near`` operator, see the -:manual:`reference documentation for $near `. - -For more information on ``Filters``, see -:doc:`our guide on the Filters builder `. +To learn more about the ``$near`` operator, see the +:manual:`$near ` reference in the +Server manual. Query Within a Range ~~~~~~~~~~~~~~~~~~~~ @@ -276,13 +284,11 @@ The following example searches for movie theaters in a section of Long Island. The following figure shows the polygon defined by the ``longIslandTriangle`` variable and dots representing the locations of -the movie theaters returned by our query. +the movie theaters returned by our query. .. figure:: /includes/figures/geo_geometry.png - :alt: Area of Long Island we are searching for movie theaters - -For more information on the ``$geoWithin`` operator, see the -:manual:`reference documentation for $geoWithin ` + :alt: Area of Long Island in which to search for movie theaters -For more information on the operators you can use in your query, see the -:manual:`MongoDB server manual page on geospatial query operators ` +To learn more about the ``$geoWithin`` operator, see the +:manual:`$geoWithin ` reference in +the Server manual. diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt index b8a7b185..2419fb89 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/fundamentals/crud/read-operations/retrieve.txt @@ -1,8 +1,15 @@ .. _kotlin-fundamentals-retrieve-data: -============== +============= Retrieve Data -============== +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, read, query, filter .. contents:: On this page :local: @@ -14,23 +21,27 @@ Overview -------- In this guide, you can learn how to retrieve data from your MongoDB -database. To retrieve data, use read operations. +database by using the {+driver-short+}. You can perform **read +operations** to retrieve data from MongoDB. -Read operations allow you to do the following: +Read operations enable you to perform the following tasks: -- Retrieve a subset of documents from your collection using a :ref:`find operation ` -- Perform transformations on retrieved documents from your collection using an :ref:`aggregate operation ` -- Monitor real-time changes to your database using :ref:`change streams ` +- Retrieve a subset of documents from your collection using a :ref:`find + operation ` +- Perform transformations on retrieved documents from your collection + using an :ref:`aggregate operation ` +- Monitor real-time changes to your database using :ref:`change streams + ` .. _retrieve-paint-order-collection: Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ -The following sections feature examples of how the owner of a paint -store manages their customers' orders. For each order, the owner keeps +The following sections include examples that demonstrate how you can +manage customer orders for cans of paint. For each order, you keep track of the color and quantity, which corresponds to the ``color`` and -``qty`` fields in their ``paint_order`` collection: +``qty`` fields in documents in the ``orders`` collection: .. code-block:: json @@ -39,7 +50,7 @@ track of the color and quantity, which corresponds to the ``color`` and { "_id": 3, "color": "purple", "qty": 4 } { "_id": 4, "color": "green", "qty": 11 } -This data is modeled with the following Kotlin data class: +This data is modeled by the following {+language+} data class: .. literalinclude:: /examples/generated/RetrieveDataTest.snippet.retrieve-data-model.kt :language: kotlin @@ -56,16 +67,15 @@ to retrieve, in what order to retrieve them, and how many to retrieve. To perform a find operation, call the ``find()`` method on an instance of a ``MongoCollection``. This method searches a collection for documents that match the query filter you provide. For more information on how to -specify a query, see our :doc:`Specify a Query -` guide. +specify a query, see the :ref:`kotlin-fundamentals-query` guide. Example ~~~~~~~ -The owner would like to know which orders contain greater than three, but -less than nine cans of paint from their :ref:`paint_order collection `. +You want to know which orders contain greater than ``3``, but +less than ``9`` cans of paint. -To address this scenario, the owner finds orders to match the criteria: +Run the following code to find orders to match the criteria: .. io-code-block:: @@ -78,40 +88,37 @@ To address this scenario, the owner finds orders to match the criteria: PaintOrder(id=2, qty=8, color=green) PaintOrder(id=3, qty=4, color=purple) -After the owner runs this query, they find two orders that matched the -criteria. - -For more information on how to build filters, see our :doc:`Filters Builders -` guide. +To learn more about the ``Filters`` builder, see the +:ref:`filters-builders` guide. -For a runnable ``find()`` example, see our :doc:`Find Multiple -Documents ` page. +To view a runnable ``find()`` example, see the :ref:`kotlin-usage-find` +usage example. .. _retrieve-aggregate: Aggregate Operation ------------------- -Use the aggregate operation to perform the stages in an aggregation -pipeline. An aggregation pipeline is a multi-staged transformation that -produces an aggregated result. +Use aggregation operations to run an aggregation pipeline on your data. +An aggregation pipeline is a multi-staged transformation that produces +an aggregated result. -To perform an aggregate operation, call the ``aggregate()`` method on an -instance of a ``MongoCollection``. This method accepts aggregation +To perform an aggregation operation, call the ``aggregate()`` method on an +instance of ``MongoCollection``. This method accepts aggregation expressions to run in sequence. To perform aggregations, you can define aggregation stages that specify how to match documents, rename -fields, and group values. For more information, see our -:doc:`Aggregation ` guide. +fields, and group values. To learn more, see the +:ref:`kotlin-aggregation` guide. Example ~~~~~~~ -The owner would like to know which paint color is the most purchased -(highest quantity sold) from their :ref:`paint_order collection `. +You want to know which paint color is the most popular by finding the +color that is bought the most. -To address the scenario, the owner creates an aggregation pipeline that: +You can create an aggregation pipeline that performs the following actions: -- Matches all the documents in the ``paint_order`` collection +- Matches all the documents in the ``orders`` collection - Groups orders by colors - Sums up the quantity field by color - Orders the results by highest-to-lowest quantity @@ -124,16 +131,13 @@ To address the scenario, the owner creates an aggregation pipeline that: .. output:: :language: console - PaintOrder(id=2, qty=8, color=green) - PaintOrder(id=3, qty=4, color=purple) - -After the owner runs the aggregation, they find that "green" is the most -purchased color. + PaintOrder(id=2, qty=19, color=green) + PaintOrder(id=3, qty=14, color=purple) -For more information on how to construct an aggregation pipeline, see -the MongoDB server manual page on :manual:`Aggregation `. +To learn more about constructing aggregation pipelines, see +:manual:`Aggregation ` in the Server manual. -For additional information on the methods mentioned on this page, see +To learn more about the methods mentioned on this page, see the following API Documentation: - `MongoCollection.find() <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/find.html>`__ From 5aae25193e484fd92f3a6f58ad072b34d460f04d Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 29 Apr 2025 12:30:59 -0400 Subject: [PATCH 12/13] DOCSP-48544: Add AWS Lambda link (#215) (cherry picked from commit e348e28a73644b13f989349d432f7b3a318f679c) --- source/fundamentals/connection.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index 8aed7e10..e85b81bc 100644 --- a/source/fundamentals/connection.txt +++ b/source/fundamentals/connection.txt @@ -12,6 +12,7 @@ Connection Guide Network Compression TLS/SSL SOCKS5 Proxy Connection + AWS Lambda .. contents:: On this page :local: @@ -32,6 +33,7 @@ sections: - :ref:`Enable Network Compression ` - :ref:`Enable TLS/SSL on a Connection ` - :ref:`Connect to MongoDB by Using a SOCKS5 Proxy ` +- `Manage Connections with AWS Lambda `__ For information about authenticating with a MongoDB instance, see :ref:`` and :ref:``. From 4223edf891eccd1c5f4fe70ee8ec7206458ae914 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 22 May 2025 22:17:19 -0400 Subject: [PATCH 13/13] DOCSP-50017 Remove EOL versions (#220) (#221) * DOCSP-50017 Remove EOL versions * auth * auth suggestion NR * NR comments * get rid of font on headings (cherry picked from commit 94fd075a3dc034aaa464b665aa89094fb23bf8e5) Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> (cherry picked from commit 7046a65689f30a4b07a83014adc04acf0dfbe28b) --- source/fundamentals/auth.txt | 144 +++--------------- source/fundamentals/builders/aggregates.txt | 14 +- source/fundamentals/builders/projections.txt | 6 - .../connection/network-compression.txt | 6 +- .../crud/read-operations/sort.txt | 4 +- source/fundamentals/enterprise-auth.txt | 2 +- source/fundamentals/indexes.txt | 11 +- source/fundamentals/stable-api.txt | 7 - source/fundamentals/time-series.txt | 7 +- .../mongodb-compatibility-table-kotlin.rst | 47 +----- source/usage-examples/bulkWrite.txt | 5 +- source/usage-examples/count.txt | 9 -- 12 files changed, 38 insertions(+), 224 deletions(-) diff --git a/source/fundamentals/auth.txt b/source/fundamentals/auth.txt index 2404ecdc..698ffff6 100644 --- a/source/fundamentals/auth.txt +++ b/source/fundamentals/auth.txt @@ -23,10 +23,7 @@ confirm identity and establish trust to ensure security. The mechanisms that you can use with the latest version of MongoDB Community Edition are as follows: -* :ref:`Default ` * :ref:`SCRAM-SHA-256 ` -* :ref:`SCRAM-SHA-1 ` -* :ref:`MONGODB-CR ` * :ref:`MONGODB-AWS ` * :ref:`X.509 ` @@ -45,38 +42,31 @@ Mechanisms ---------- .. _default-auth-mechanism: +.. _scram-sha-256-auth-mechanism: -Default -~~~~~~~ - -The default authentication mechanism setting uses one of the following -authentication mechanisms depending on what your MongoDB server supports: - -#. ``SCRAM-SHA-256`` -#. ``SCRAM-SHA-1`` -#. ``MONGODB-CR`` +SCRAM-SHA-256 +~~~~~~~~~~~~~ -Server versions 3.6 and earlier use ``MONGODB-CR`` as the default -mechanism. Newer versions of the server use one of the mechanisms for -which they advertise support. +``SCRAM-SHA-256`` is a salted challenge-response authentication mechanism +(SCRAM) that uses your username and password, encrypted with the ``SHA-256`` +algorithm, to authenticate your user. This is the default authentication +mechanism. The following code snippets show how to specify the authentication mechanism, using the following placeholders: -* ``username`` - your MongoDB username -* ``password`` - your MongoDB user's password -* ``hostname`` - network address of your MongoDB server, accessible by your client -* ``port`` - port number of your MongoDB server +* ``db_username`` - your MongoDB database username. +* ``db_password`` - your MongoDB database user's password. +* ``hostname`` - network address of your MongoDB server, accessible by your client. +* ``port`` - port number of your MongoDB server. * ``authenticationDb`` - MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value ``admin``. Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication +tab below for instructions and sample code to specify this default authentication mechanism: -.. _mongo-client-setting-with-mongo-credential-example: - .. tabs:: .. tab:: @@ -99,38 +89,10 @@ mechanism: .. literalinclude:: /examples/generated/AuthTest.snippet.default-mongo-cred.kt :language: kotlin -For more information on the challenge-response (CR) and salted -challenge-response authentication mechanisms (SCRAM) that MongoDB supports, -see the :manual:`SCRAM ` section of the Server manual. - -.. _scram-sha-256-auth-mechanism: - -``SCRAM-SHA-256`` -~~~~~~~~~~~~~~~~~ - -.. note:: - - ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting - in MongoDB 4.0. - -``SCRAM-SHA-256`` is a salted challenge-response authentication mechanism -(SCRAM) that uses your username and password, encrypted with the ``SHA-256`` -algorithm, to authenticate your user. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -* ``username`` - your MongoDB username. -* ``password`` - your MongoDB user's password. -* ``hostname`` - network address of your MongoDB server, accessible by your client. -* ``port`` - port number of your MongoDB server. -* ``authenticationDb`` - MongoDB database that contains your user's - authentication data. If you omit this parameter, the driver uses the - default value ``admin``. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: +You can also explicitly specify the ``SCRAM-SHA-256`` authentication mechanism, +as shown in the following code snippets. Select the :guilabel:`Connection String` +or the :guilabel:`MongoCredential` tab below for instructions and sample code for +specifying this authentication mechanism: .. tabs:: @@ -156,76 +118,10 @@ mechanism: .. literalinclude:: /examples/generated/AuthTest.snippet.scram-sha-256-cred.kt :language: kotlin -.. _scram-sha-1-auth-mechanism: - -``SCRAM-SHA-1`` -~~~~~~~~~~~~~~~ - -.. note:: - ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions - 3.0, 3.2, 3.4, and 3.6. - -``SCRAM-SHA-1`` is a salted challenge-response mechanism (SCRAM) that uses your -username and password, encrypted with the ``SHA-1`` algorithm, to authenticate -your user. - -The following code snippets show how to specify the authentication mechanism, -using the following placeholders: - -* ``username`` - your MongoDB username. -* ``password`` - your MongoDB user's password. -* ``hostname`` - network address of your MongoDB server, accessible by your client. -* ``port`` - port number of your MongoDB server. -* ``authenticationDb`` - MongoDB database that contains your user's - authentication data. If you omit this parameter, the driver uses the - default value ``admin``. - -Select the :guilabel:`Connection String` or the :guilabel:`MongoCredential` -tab below for instructions and sample code for specifying this authentication -mechanism: - -.. tabs:: - - .. tab:: - :tabid: Connection String - - To specify the ``SCRAM-SHA-1`` authentication mechanism using a - connection string, assign the ``authMechanism`` parameter the value - ``SCRAM-SHA-1`` in your connection string. Your code to instantiate - a ``MongoClient`` should resemble the following: - - .. literalinclude:: /examples/generated/AuthTest.snippet.scram-sha-1-string.kt - :language: kotlin - - .. tab:: - :tabid: MongoCredential - - To specify the default authentication mechanism using the - ``MongoCredential`` class, use the - `createScramSha1Credential() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html#createScramSha1Credential(java.lang.String,java.lang.String,char[])>`__ - method. Your code to instantiate a ``MongoClient`` should resemble the following: - - .. literalinclude:: /examples/generated/AuthTest.snippet.scram-sha-1-cred.kt - :language: kotlin - -.. _mongodb-cr-auth-mechanism: - -``MONGODB-CR`` -~~~~~~~~~~~~~~ - -``MONGODB-CR`` is a challenge-response authentication mechanism that uses your -username and password to authenticate your user. This authentication -mechanism was deprecated starting in MongoDB 3.6 and is no longer -supported as of MongoDB 4.0. - -You cannot specify this method explicitly; refer to the fallback provided -by the :ref:`default authentication mechanism ` to -connect using ``MONGODB-CR``. - .. _mongodb-aws-auth-mechanism: -``MONGODB-AWS`` -~~~~~~~~~~~~~~~ +MONGODB-AWS +~~~~~~~~~~~ .. note:: @@ -448,8 +344,8 @@ method: .. _x509-auth-mechanism: -``X.509`` -~~~~~~~~~ +X.509 +~~~~~ The ``X.509`` authentication mechanism uses :wikipedia:`TLS ` with X.509 certificates to diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index c0eb34d9..7e712089 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/fundamentals/builders/aggregates.txt @@ -864,11 +864,10 @@ Atlas Full-Text Search Use the ``search()`` method to create a :manual:`$search ` pipeline stage that specifies a full-text search of one or more fields. -.. tip:: Only Available on Atlas for MongoDB v4.2 and later +.. tip:: Only Available on Collections with an Atlas Search Index - This aggregation pipeline operator is only available for collections hosted - on :atlas:`MongoDB Atlas ` clusters running v4.2 or later that are - covered by an :atlas:`Atlas search index `. + This aggregation pipeline operator is only available for collections + with an :atlas:`Atlas search index `. Learn more about the required setup and the functionality of this operator from the :ref:`Atlas Search ` documentation. @@ -889,13 +888,6 @@ Use the ``searchMeta()`` method to create a pipeline stage which returns only the metadata part of the results from Atlas full-text search queries. -.. tip:: Only Available on Atlas for MongoDB v4.4.11 and later - - This aggregation pipeline operator is only available - on :atlas:`MongoDB Atlas ` clusters running v4.4.11 and later. For a - detailed list of version availability, see the MongoDB Atlas documentation - on :atlas:`$searchMeta `. - The following example shows the ``count`` metadata for an Atlas search aggregation stage: diff --git a/source/fundamentals/builders/projections.txt b/source/fundamentals/builders/projections.txt index fa62ccac..4e4f4b6c 100644 --- a/source/fundamentals/builders/projections.txt +++ b/source/fundamentals/builders/projections.txt @@ -229,12 +229,6 @@ When you've specified matching criteria in the **query** portion of your operati variant to specify a :manual:`positional projection ` to include the first element of an array. Only documents that match the query filter will be retrieved. -.. important:: - - In MongoDB version 4.4 and earlier, the specified array field must appear in the query filter. Beginning in MongoDB 4.4, - you can use a positional project on an array field that does not appear in the query filter. - - The following example projects the first element of the ``temperatures`` array: .. io-code-block:: diff --git a/source/fundamentals/connection/network-compression.txt b/source/fundamentals/connection/network-compression.txt index d9485f41..daf53185 100644 --- a/source/fundamentals/connection/network-compression.txt +++ b/source/fundamentals/connection/network-compression.txt @@ -17,9 +17,9 @@ and your application. The driver supports the following algorithms: -1. `Snappy `__: available in MongoDB 3.4 and later. -#. `Zlib `__: available in MongoDB 3.6 and later. -#. `Zstandard `__: available in MongoDB 4.2 and later. +1. `Snappy `__ +#. `Zlib `__ +#. `Zstandard `__ The driver tests against the following versions of these libraries: diff --git a/source/fundamentals/crud/read-operations/sort.txt b/source/fundamentals/crud/read-operations/sort.txt index 045d3596..fcb320bb 100644 --- a/source/fundamentals/crud/read-operations/sort.txt +++ b/source/fundamentals/crud/read-operations/sort.txt @@ -320,9 +320,9 @@ The data is modeled with the following Kotlin data class: OrderScore(id=5, description=one large vanilla and chocolate cake, score=0.6) OrderScore(id=2, description=two medium vanilla birthday cakes, score=0.6) -.. note:: Text Search Behavior in MongoDB 4.4 or Later +.. note:: Text Search Behavior in MongoDB 6.0 or Later - The structure of text search has changed for MongoDB 4.4 or later. You no + The structure of text search has changed for MongoDB 6.0 or later. You no longer need to project ``Projections.metaTextScore()`` into your ``FindFlow`` instance in order to sort on the text score. In addition, the field name you specify in a ``$meta`` text score aggregation operation diff --git a/source/fundamentals/enterprise-auth.txt b/source/fundamentals/enterprise-auth.txt index c1946caf..11ba4d5d 100644 --- a/source/fundamentals/enterprise-auth.txt +++ b/source/fundamentals/enterprise-auth.txt @@ -221,7 +221,7 @@ to improve performance. LDAP (PLAIN) ~~~~~~~~~~~~ -*Available in MongoDB Enterprise Edition 3.4 and later.* +*Available in MongoDB Enterprise Edition.* You can authenticate to a Lightweight Directory Access Protocol (LDAP) server using your directory server username and password. diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt index 305384c4..4b781074 100644 --- a/source/fundamentals/indexes.txt +++ b/source/fundamentals/indexes.txt @@ -97,8 +97,8 @@ your application uses indexes: operation updates an indexed field, MongoDB updates the related index. Since MongoDB supports dynamic schemas, applications can query against fields whose names cannot be known in advance or -are arbitrary. MongoDB 4.2 introduced :manual:`wildcard indexes ` to help support these queries. -Wildcard indexes are not designed to replace workload-based index planning. +are arbitrary with :manual:`wildcard indexes `. Wildcard indexes are +not designed to replace workload-based index planning. For more information on designing your data model and choosing indexes appropriate for your application, see the MongoDB server documentation on :manual:`Indexing Strategies ` and @@ -434,9 +434,8 @@ created in the preceding code snippet: :language: kotlin MongoDB also supports ``2d`` indexes for calculating distances on a -Euclidean plane and for working with the "legacy coordinate pairs" -syntax used in MongoDB 2.2 and earlier. To learn more, see -:manual:`Geospatial Queries ` in the Server manual. +Euclidean plane. To learn more, see :manual:`Geospatial Queries ` +in the Server manual. Unique Indexes ~~~~~~~~~~~~~~ @@ -569,7 +568,7 @@ The following snippet removes the "title_text" index from the collection: Remove an Index Using a Wildcard Character ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Starting with MongoDB 4.2, you can drop all indexes by calling the +You can drop all indexes by calling the ``dropIndexes()`` method on your collection: .. literalinclude:: /examples/generated/IndexesTest.snippet.drop-all-indexes.kt diff --git a/source/fundamentals/stable-api.txt b/source/fundamentals/stable-api.txt index fd15506e..315076f9 100644 --- a/source/fundamentals/stable-api.txt +++ b/source/fundamentals/stable-api.txt @@ -11,13 +11,6 @@ :depth: 1 :class: singlecol -.. note:: - - The {+stable-api+} feature requires MongoDB Server 5.0 or later. - - You should only use the {+stable-api+} feature if all the MongoDB - servers you are connecting to support this feature. - Overview -------- diff --git a/source/fundamentals/time-series.txt b/source/fundamentals/time-series.txt index c6d99cd3..a1b3ee1c 100644 --- a/source/fundamentals/time-series.txt +++ b/source/fundamentals/time-series.txt @@ -50,10 +50,6 @@ method: .. literalinclude:: /examples/generated/TimeSeriesTest.snippet.create-time-series-collection.kt :language: kotlin -.. important:: - - Versions prior to MongoDB 5.0 cannot create a time series collection. - To check if you successfully created the collection, send the ``"listCollections"`` command to the `runCommand() <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-database/run-command.html>`__ method. @@ -90,8 +86,7 @@ and :ref:`aggregating data `. .. note:: Window Functions - MongoDB version 5.0 introduces window functions into the aggregation - pipeline. You can use window functions to perform operations on a + You can use window functions to perform operations on a contiguous span of time series data. For more information, see our diff --git a/source/includes/mongodb-compatibility-table-kotlin.rst b/source/includes/mongodb-compatibility-table-kotlin.rst index ee348235..c156c159 100644 --- a/source/includes/mongodb-compatibility-table-kotlin.rst +++ b/source/includes/mongodb-compatibility-table-kotlin.rst @@ -6,52 +6,7 @@ * - Kotlin Driver Version - MongoDB 7.0 - MongoDB 6.0 - - MongoDB 5.0 - - MongoDB 4.4 - - MongoDB 4.2 - - MongoDB 4.0 - - MongoDB 3.6 - - MongoDB 3.4 - - MongoDB 3.2 - - MongoDB 3.0 - - MongoDB 2.6 - * - 5.0 + * - 4.10 to 5.0 - ✓ - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - - - - - - - - - * - 4.11 - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - - - - - - - - - * - 4.10 - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - - - - - - - - diff --git a/source/usage-examples/bulkWrite.txt b/source/usage-examples/bulkWrite.txt index 097febe8..9ebd6182 100644 --- a/source/usage-examples/bulkWrite.txt +++ b/source/usage-examples/bulkWrite.txt @@ -34,9 +34,8 @@ The ``bulkWrite()`` method accepts the following parameters: .. note:: - Retryable writes run on MongoDB server versions 3.6 or later in bulk - write operations unless they include one or more instances of - ``UpdateManyModel`` or ``DeleteManyModel``. + Retryable writes run in bulk write operations unless they include one or + more instances of ``UpdateManyModel`` or ``DeleteManyModel``. .. tip:: diff --git a/source/usage-examples/count.txt b/source/usage-examples/count.txt index f9ce46ac..e5635d72 100644 --- a/source/usage-examples/count.txt +++ b/source/usage-examples/count.txt @@ -36,15 +36,6 @@ When you call the ``countDocuments()`` method, you can optionally pass a **query filter** parameter. You cannot pass any parameters when you call ``estimatedDocumentCount()``. -.. important:: Stable API V1 and MongoDB Server Issue - - If you are using the Stable API ``V1`` with the "strict" option and a - MongoDB server version between 5.0.0 and 5.0.8 inclusive, method calls to - ``estimatedDocumentCount()`` may error due to a server bug. - - Upgrade to MongoDB server 5.0.9 or set the Stable API "strict" option to - ``false`` to avoid this issue. - You can also pass an optional parameter to either of these methods to specify the behavior of the call: