From eda8d4c6a887a0c0cfe9e9d167b1315945c1a167 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 24 Sep 2024 13:54:25 -0400 Subject: [PATCH 1/3] DOCSP-42607: v5.2 changes --- .github/workflows/check-autobuilder.yml | 13 --- snooty.toml | 1 + source/data-formats/serialization.txt | 96 ++++++++++++++++++- source/includes/data-formats/serialization.kt | 20 ++++ source/includes/indexes/indexes.kt | 30 +++++- source/indexes/atlas-search-index.txt | 37 ++++--- source/whats-new.txt | 27 ++++++ 7 files changed, 191 insertions(+), 33 deletions(-) delete mode 100644 .github/workflows/check-autobuilder.yml diff --git a/.github/workflows/check-autobuilder.yml b/.github/workflows/check-autobuilder.yml deleted file mode 100644 index 8495db96..00000000 --- a/.github/workflows/check-autobuilder.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: Check Autobuilder for Errors - -on: - pull_request: - paths: - - "source/**" - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: cbush/snooty-autobuilder-check@main diff --git a/snooty.toml b/snooty.toml index 75560bbb..a0884475 100644 --- a/snooty.toml +++ b/snooty.toml @@ -34,3 +34,4 @@ java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}" core-api = "{+java-api+}/apidocs/mongodb-driver-core" kotlin-docs = "https://kotlinlang.org" serialization-version = "1.5.1" +kotlinx-dt-version = "0.6.1" diff --git a/source/data-formats/serialization.txt b/source/data-formats/serialization.txt index a98f24ba..f1d0f6ba 100644 --- a/source/data-formats/serialization.txt +++ b/source/data-formats/serialization.txt @@ -297,4 +297,98 @@ deserializes them accordingly. Retrieving as Document type Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}} - Document{{_id=..., _t=Student, name=Kate Parker, grade=10}} \ No newline at end of file + Document{{_id=..., _t=Student, name=Kate Parker, grade=10}} + +.. _kotlin-sync-datetime-serialization: + +Serialize Dates and Times +------------------------- + +In this section, you can learn about using {+language+} serialization to +work with date and time types. + +kotlinx-datetime Library +~~~~~~~~~~~~~~~~~~~~~~~~ + +``kotlinx-datetime`` is a {+language+} library that offers +a high level of control over how your date and time values +are serialized. To use the library, add the ``kotlinx-datetime`` +dependency to your project's dependency list. + +Select from the following tabs to see how to add the ``kotlinx-datetime`` +dependency to your project by using the :guilabel:`Gradle` and +:guilabel:`Maven` package managers: + +.. tabs:: + + .. tab:: + :tabid: Gradle + + .. code-block:: kotlin + :caption: build.gradle.kts + + implementation("org.jetbrains.kotlinx:kotlinx-datetime:{+kotlinx-dt-version+}") + + .. tab:: + :tabid: Maven + + .. code-block:: kotlin + :caption: pom.xml + + + org.jetbrains.kotlinx + kotlinx-datetime-jvm + {+kotlinx-dt-version+} + + +To learn more about this library, see the :github:`kotlinx-datetime repository +` on GitHub. + +Example Data Class with Dates and Times +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you add the library dependency, you can implement serializers from +the ``kotlinx-datetime`` library that map your data class field values +to the expected types in BSON. + +In the following example, the driver serializes the fields of +the ``Appointment`` data class with the following behavior: + +- ``name``: The driver serializes the value as a string. + +- ``date``: The driver uses the ``kotlinx-datetime`` serializer + because the field has the ``@Contextual`` annotation. ``LocalDate`` + values are serialized as BSON dates. + +- ``time``: The driver serializes the value as a string because it does + not have the ``@Contextual`` annotation. This is the default + serialization behavior for ``LocalTime`` values. + +.. literalinclude:: /includes/data-formats/serialization.kt + :language: kotlin + :start-after: start-datetime-data-class + :end-before: end-datetime-data-class + :dedent: + +The following example inserts an instance of the ``Appointment`` data +class into MongoDB: + +.. literalinclude:: /includes/data-formats/serialization.kt + :language: kotlin + :start-after: start-datetime-insertone + :end-before: end-datetime-insertone + :dedent: + +In MongoDB, the ``LocalDate`` value is stored as a BSON date, and the +``time`` field is stored as a string by default serialization: + +.. code-block:: json + + { + "_id": ..., + "name": "Daria Smith", + "date": { + "$date": "2024-10-15T00:00:00.000Z" + }, + "time": "11:30", + } diff --git a/source/includes/data-formats/serialization.kt b/source/includes/data-formats/serialization.kt index b942c370..5a53afa2 100644 --- a/source/includes/data-formats/serialization.kt +++ b/source/includes/data-formats/serialization.kt @@ -74,6 +74,14 @@ data class Teacher( ) : Person // end-poly-classes +// start-datetime-data-class +@Serializable +data class Appointment( + val name: String, + @Contextual val date: LocalDate, + val time: LocalTime, +) +// end-datetime-data-class fun main() { @@ -126,5 +134,17 @@ fun main() { } // end-poly-operations + // start-datetime-insertone + val collection = database.getCollection("appointments") + + val apptDoc = Appointment( + "Daria Smith", + LocalDate(2024, 10, 15), + LocalTime(hour = 11, minute = 30) + ) + + collection.insertOne(apptDoc) + // end-datetime-insertone + } diff --git a/source/includes/indexes/indexes.kt b/source/includes/indexes/indexes.kt index e8c987f6..7a782926 100644 --- a/source/includes/indexes/indexes.kt +++ b/source/includes/indexes/indexes.kt @@ -74,13 +74,35 @@ fun main() { // start-create-search-index val index = Document("mappings", Document("dynamic", true)) - collection.createSearchIndex("", index) + collection.createSearchIndex("mySearchIdx", index) // end-create-search-index // start-create-search-indexes - val indexOne = SearchIndexModel("", Document("mappings", Document("dynamic", true))) - val indexTwo = SearchIndexModel("", Document("mappings", Document("dynamic", true))) - collection.createSearchIndexes(listOf(indexOne, indexTwo)) + val searchIdxMdl = SearchIndexModel( + "searchIdx", + Document("analyzer", "lucene.standard").append( + "mappings", Document("dynamic", true) + ), + SearchIndexType.search() + ) + + val vectorSearchIdxMdl = SearchIndexModel( + "vsIdx", + Document( + "fields", + listOf( + Document("type", "vector") + .append("path", "embeddings") + .append("numDimensions", 1536) + .append("similarity", "dotProduct") + ) + ), + SearchIndexType.vectorSearch() + ) + + collection.createSearchIndexes( + listOf(searchIdxMdl, vectorSearchIdxMdl) + ) // end-create-search-indexes // start-list-search-indexes diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index 38c837a0..846d2369 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -1,8 +1,9 @@ .. _kotlin-sync-atlas-search-index: +.. _kotlin-sync-search-avs-indexes: -==================== -Atlas Search Indexes -==================== +====================================== +Atlas Search and Vector Search Indexes +====================================== .. contents:: On this page :local: @@ -20,12 +21,23 @@ Atlas Search Indexes Overview -------- -:atlas:`Atlas Search ` enables you to perform full-text searches on +You can programmatically manage your :atlas:`Atlas Search +` and :atlas:`Atlas Vector Search +` indexes by using the +{+driver-short+}. + +Atlas Search enables you to perform full-text searches on collections hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of the search and which fields to index. -You can call the following methods on a collection to manage your Atlas Search -indexes: +Atlas Vector Search enables you to perform semantic searches on vector +embeddings stored in MongoDB Atlas. Vector Search indexes define the +indexes for the vector embeddings that you want to query and the boolean, +date, objectId, numeric, string, or UUID values that you want to use to +pre-filter your data. + +You can call the following methods on a collection to manage your Atlas +Search and Vector Search indexes: - ``createSearchIndex()`` - ``createSearchIndexes()`` @@ -50,13 +62,7 @@ Create a Search Index You can use the `createSearchIndex() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/create-search-index.html>`__ and the `createSearchIndexes() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/create-search-indexes.html>`__ -methods to create one or more Atlas Search indexes. - -You can also use these methods to create Atlas Vector Search Indexes. -Atlas Vector Search enables you to perform semantic searches on vector -embeddings stored in MongoDB Atlas. To learn more about this feature, -see the :atlas:`Atlas Vector Search Overview -`. +methods to create one or more Atlas Search or Vector Search indexes. The following code example shows how to create an Atlas Search index: @@ -66,7 +72,8 @@ The following code example shows how to create an Atlas Search index: :end-before: end-create-search-index :dedent: -The following code example shows how to create multiple indexes: +The following code example shows how to create Search and +Vector Search indexes in one call: .. literalinclude:: /includes/indexes/indexes.kt :language: kotlin @@ -76,7 +83,7 @@ The following code example shows how to create multiple indexes: To learn more about the syntax used to define Atlas Search indexes, see the :atlas:`Review Atlas Search Index Syntax ` guide -in the Atlas manual. +in the Atlas documentation. .. _kotlin-sync-atlas-search-index-list: diff --git a/source/whats-new.txt b/source/whats-new.txt index bc33a32c..3628394f 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -12,12 +12,39 @@ What's New Learn what's new in: +* :ref:`Version 5.2 ` * :ref:`Version 5.1.3 ` * :ref:`Version 5.1.2 ` * :ref:`Version 5.1.1 ` * :ref:`Version 5.1 ` * :ref:`Version 5.0 ` +.. _kotlin-sync-version-5.2: + +What's New in 5.2 +----------------- + +The 5.2 driver release includes the following new features, +improvements, and fixes: + +.. sharedinclude:: dbx/jvm/v5.2-wn-items.rst + + .. replacement:: avs-index-link + + the :ref:`kotlin-sync-search-avs-indexes` guide + +- Adds support for serializers from the ``kotlinx-datetime`` library + that let you map {+language+} date and time types to BSON as the + expected types instead of as strings. To learn more, see the + :ref:`kotlin-sync-datetime-serialization` section of the {+language+} + Serialization guide. + +- Supports serialization of `JsonElement + <{+kotlin-docs+}/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/>`__ + values. To work with the ``JsonElement`` type, you must add the + ``kotlinx-serialization-json`` library as a dependency in your + application. + .. _kotlin-sync-version-5.1.3: What's New in 5.1.3 From b9310174e8c0c5e60600bcfcd82dfa7dca38754c Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 24 Sep 2024 15:06:05 -0400 Subject: [PATCH 2/3] NR PR fixes 1 --- source/data-formats/serialization.txt | 6 +++--- source/indexes/atlas-search-index.txt | 10 ++++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/source/data-formats/serialization.txt b/source/data-formats/serialization.txt index f1d0f6ba..b4c13a3a 100644 --- a/source/data-formats/serialization.txt +++ b/source/data-formats/serialization.txt @@ -351,7 +351,7 @@ After you add the library dependency, you can implement serializers from the ``kotlinx-datetime`` library that map your data class field values to the expected types in BSON. -In the following example, the driver serializes the fields of +In this example, the driver serializes the fields of the ``Appointment`` data class with the following behavior: - ``name``: The driver serializes the value as a string. @@ -371,7 +371,7 @@ the ``Appointment`` data class with the following behavior: :dedent: The following example inserts an instance of the ``Appointment`` data -class into MongoDB: +class into the ``appointments`` collection: .. literalinclude:: /includes/data-formats/serialization.kt :language: kotlin @@ -380,7 +380,7 @@ class into MongoDB: :dedent: In MongoDB, the ``LocalDate`` value is stored as a BSON date, and the -``time`` field is stored as a string by default serialization: +``time`` field is stored as a string by default serialization: .. code-block:: json diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index 846d2369..de0cffa8 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -47,9 +47,11 @@ Search and Vector Search indexes: .. note:: - The Atlas Search index management methods run asynchronously and might return before - confirming that they ran successfully. To determine the current status of the indexes, - call the ``listSearchIndexes()`` method. + The Atlas Search and Vector Search index management methods run + asynchronously and might return before confirming that they ran + successfully. To determine the current status of the indexes, call + the ``listSearchIndexes()`` method or view the indexes list in the + :atlas:`Atlas UI `. The following sections provide code examples that demonstrate how to use each of the preceding methods. @@ -72,7 +74,7 @@ The following code example shows how to create an Atlas Search index: :end-before: end-create-search-index :dedent: -The following code example shows how to create Search and +The following code example shows how to create Atlas Search and Vector Search indexes in one call: .. literalinclude:: /includes/indexes/indexes.kt From 9d1c359c11a4a273659d218cb6cc9b8190f93746 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 24 Sep 2024 15:08:18 -0400 Subject: [PATCH 3/3] indentation fix --- source/data-formats/serialization.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/data-formats/serialization.txt b/source/data-formats/serialization.txt index b4c13a3a..fd114cf7 100644 --- a/source/data-formats/serialization.txt +++ b/source/data-formats/serialization.txt @@ -325,21 +325,21 @@ dependency to your project by using the :guilabel:`Gradle` and :tabid: Gradle .. code-block:: kotlin - :caption: build.gradle.kts + :caption: build.gradle.kts - implementation("org.jetbrains.kotlinx:kotlinx-datetime:{+kotlinx-dt-version+}") + implementation("org.jetbrains.kotlinx:kotlinx-datetime:{+kotlinx-dt-version+}") .. tab:: :tabid: Maven .. code-block:: kotlin - :caption: pom.xml + :caption: pom.xml - - org.jetbrains.kotlinx - kotlinx-datetime-jvm - {+kotlinx-dt-version+} - + + org.jetbrains.kotlinx + kotlinx-datetime-jvm + {+kotlinx-dt-version+} + To learn more about this library, see the :github:`kotlinx-datetime repository ` on GitHub.