From c86f88c54f1717648ccbe5b49cad77d360f41065 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 7 Jan 2025 17:04:15 -0500 Subject: [PATCH 01/18] DOCSP-36218: filters with dataclass properties --- examples/src/test/kotlin/DataClassTest.kt | 23 +++++++++++++++- ...ssTest.snippet.filters-query-data-class.kt | 7 +++++ ...ssTest.snippet.retrieve-diff-data-class.kt | 2 +- source/fundamentals/builders/filters.txt | 7 +++++ .../document-data-format-data-class.txt | 27 ++++++++++++++++--- source/whats-new.txt | 15 +++++++++++ 6 files changed, 76 insertions(+), 5 deletions(-) create mode 100644 source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt diff --git a/examples/src/test/kotlin/DataClassTest.kt b/examples/src/test/kotlin/DataClassTest.kt index 7a0738d2..f21d307c 100644 --- a/examples/src/test/kotlin/DataClassTest.kt +++ b/examples/src/test/kotlin/DataClassTest.kt @@ -1,5 +1,6 @@ import com.mongodb.client.model.Filters +import com.mongodb.client.model.Filters.eq import com.mongodb.client.model.FindOneAndUpdateOptions import com.mongodb.client.model.ReturnDocument import com.mongodb.client.model.Updates @@ -92,10 +93,30 @@ internal class DataClassTest { .withDocumentClass() .findOneAndUpdate(filter, update, options) - println("Updated document: ${result}") + println("Updated document: $result") // :snippet-end: } + @Test + fun queryDataClassTest() = runBlocking { + + val collection = database.getCollection("data_storage") + + // :snippet-start: filters-query-data-class + val record = DataStorage("SSD", 120.0) + // Infixed query + DataStorage::productName.eq(record.productName) + // Nested query + val bson = eq(DataStorage::productName, record.productName) + // Kmongo DSL + val filter = DataStorage::productName eq record.productName + // :snippet-end: + + collection.insertOne(record) + val result = collection.find().firstOrNull() + assertEquals(record, result) + } + // :snippet-start: annotated-data-class data class NetworkDevice( @BsonId diff --git a/source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt b/source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt new file mode 100644 index 00000000..f44390a4 --- /dev/null +++ b/source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt @@ -0,0 +1,7 @@ +val record = DataStorage("SSD", 120.0) +// Infixed query +DataStorage::productName.eq(record.productName) +// Nested query +val bson = eq(DataStorage::productName, record.productName) +// Kmongo DSL +val filter = DataStorage::productName eq record.productName diff --git a/source/examples/generated/DataClassTest.snippet.retrieve-diff-data-class.kt b/source/examples/generated/DataClassTest.snippet.retrieve-diff-data-class.kt index c37b141e..09e992cd 100644 --- a/source/examples/generated/DataClassTest.snippet.retrieve-diff-data-class.kt +++ b/source/examples/generated/DataClassTest.snippet.retrieve-diff-data-class.kt @@ -14,4 +14,4 @@ val result = collection .withDocumentClass() .findOneAndUpdate(filter, update, options) -println("Updated document: ${result}") +println("Updated document: $result") diff --git a/source/fundamentals/builders/filters.txt b/source/fundamentals/builders/filters.txt index aa585c0d..098ca35e 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/fundamentals/builders/filters.txt @@ -81,6 +81,13 @@ with the Kotlin driver: .. literalinclude:: /examples/generated/FiltersBuildersTest.snippet.paint-order-data-class.kt :language: kotlin +.. tip:: Filters and Data Class Properties + + You can use methods from the ``Filters`` directly with data class + properties. To learn more and view examples, see the + :ref:`kotlin-data-class-query` section of the Document Data Format: + Data Classes guide. + .. _comparison: Comparison 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 aa47b367..5c91ed35 100644 --- a/source/fundamentals/data-formats/document-data-format-data-class.txt +++ b/source/fundamentals/data-formats/document-data-format-data-class.txt @@ -14,12 +14,12 @@ Overview -------- In this guide, you can learn how to store and retrieve data in the -{+driver-long+} using **Kotlin data classes**. +{+driver-long+} by using **{+language+} data classes**. Serialize and Deserialize a Data Class -------------------------------------- -The driver natively supports encoding and decoding Kotlin data classes for +The driver natively supports encoding and decoding {+language+} data classes for MongoDB read and write operations using the **default codec registry**. The default codec registry is a collection of classes called **codecs** that define how to encode and decode Kotlin and Java types. @@ -85,6 +85,27 @@ operation adds the ``releaseDate`` field to the document with a For more information about this feature, see :ref:`Specify Return Type ` in the Databases and Collections guide. +.. _kotlin-data-class-query: + +Querying Data Classes +--------------------- + +You can use helpers from the ``Filter`` builders class to query on data +class properties. The following code uses the ``Filters.eq()`` method to +construct the same query on the ``DataStorage`` data class in multiple syntaxes: + +.. literalinclude:: /examples/generated/DataClassTest.snippet.filters-query-data-class.kt + :language: kotlin + +.. tip:: Filters and Data Class Annotations + + When you use ``Filters`` class helpers to construct queries on data + classes, the methods respect your data class annotations from the + ``bson-kotlin`` and ``bson-kotlinx`` packages. To learn more about + annotations, see the :ref:`fundamentals-data-class-annotations` + section of this guide and the :ref:`kotlin-data-class-annotation` + section in the {+language+} Serialization guide. + .. _fundamentals-data-class-annotations: Specify Component Conversion Using Annotations @@ -105,7 +126,7 @@ You can use the following annotations on data classes: - Description * - ``BsonId`` - - Marks a property to serialize as the _id property. + - Marks a property to serialize as the ``_id`` property. * - ``BsonProperty`` - Specifies a custom document field name when converting the data class diff --git a/source/whats-new.txt b/source/whats-new.txt index 7dc7c43d..08d5af1a 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -12,6 +12,7 @@ What's New Learn what's new in: +* :ref:`Version 5.3 ` * :ref:`Version 5.2 ` * :ref:`Version 5.1.3 ` * :ref:`Version 5.1.2 ` @@ -21,6 +22,20 @@ Learn what's new in: * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` +.. _kotlin-coroutine-version-5.3: + +What's New in 5.3 +----------------- + +The 5.2 driver release includes the following new features, +improvements, and fixes: + +.. .. sharedinclude:: dbx/jvm/v5.3-wn-items.rst + +- Support for using builder class methods directly with data class + properties. To learn more, see the :ref:`fundamentals-data-classes` + guide and the :ref:`kotlin-builders-landing` guides. + .. _kotlin-coroutine-version-5.2: What's New in 5.2 From e2575bec5f56426378a352c6f5f13147548c52cb Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 7 Jan 2025 17:13:59 -0500 Subject: [PATCH 02/18] fixes --- source/fundamentals/builders/filters.txt | 5 +++-- .../data-formats/document-data-format-data-class.txt | 7 +++++-- source/usage-examples/updateMany.txt | 2 +- source/usage-examples/updateOne.txt | 2 +- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/builders/filters.txt b/source/fundamentals/builders/filters.txt index 098ca35e..c01ac86b 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/fundamentals/builders/filters.txt @@ -62,7 +62,8 @@ type, which you can pass to any method that expects a query filter. import com.mongodb.client.model.Filters.* -Most of the ``Filter`` examples in this guide use the following sample collection ``paints``: +Most of the ``Filters`` examples in this guide use the following sample +collection ``paints``: .. code-block:: json @@ -83,7 +84,7 @@ with the Kotlin driver: .. tip:: Filters and Data Class Properties - You can use methods from the ``Filters`` directly with data class + You can use methods from the ``Filters`` class directly with data class properties. To learn more and view examples, see the :ref:`kotlin-data-class-query` section of the Document Data Format: Data Classes guide. 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 5c91ed35..a5a18910 100644 --- a/source/fundamentals/data-formats/document-data-format-data-class.txt +++ b/source/fundamentals/data-formats/document-data-format-data-class.txt @@ -90,8 +90,11 @@ For more information about this feature, see :ref:`Specify Return Type Querying Data Classes --------------------- -You can use helpers from the ``Filter`` builders class to query on data -class properties. The following code uses the ``Filters.eq()`` method to +You can use helpers from the ``Filters`` builders class to query on data +class properties. To learn more about this class, see the +:ref:`filters-builders` guide. + +The following code uses the ``Filters.eq()`` method to construct the same query on the ``DataStorage`` data class in multiple syntaxes: .. literalinclude:: /examples/generated/DataClassTest.snippet.filters-query-data-class.kt diff --git a/source/usage-examples/updateMany.txt b/source/usage-examples/updateMany.txt index 339cf083..ace9a0fb 100644 --- a/source/usage-examples/updateMany.txt +++ b/source/usage-examples/updateMany.txt @@ -56,7 +56,7 @@ bottom of this page. Example ------- -In this example, we use a ``Filter`` builder to filter our query for +In this example, we use a ``Filters`` builder to filter our query for movies in the genre "Frequently Discussed". Next, we update documents that match our query in the ``movies`` collection of the diff --git a/source/usage-examples/updateOne.txt b/source/usage-examples/updateOne.txt index 6cd6b11c..471a7a40 100644 --- a/source/usage-examples/updateOne.txt +++ b/source/usage-examples/updateOne.txt @@ -54,7 +54,7 @@ bottom of this page. Example ------- -In this example, we use a ``Filter`` builder to query the collection for +In this example, we use a ``Filters`` builder to query the collection for a movie with the title "Cool Runnings 2". Next, we perform the following updates to the first match for our query From 6050c93b3db391c89d0d42b65822e6463b16a508 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 7 Jan 2025 17:15:11 -0500 Subject: [PATCH 03/18] fixes --- source/whats-new.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index 08d5af1a..71cc4343 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -12,7 +12,7 @@ What's New Learn what's new in: -* :ref:`Version 5.3 ` +* :ref:`Version 5.3 ` * :ref:`Version 5.2 ` * :ref:`Version 5.1.3 ` * :ref:`Version 5.1.2 ` @@ -27,12 +27,12 @@ Learn what's new in: What's New in 5.3 ----------------- -The 5.2 driver release includes the following new features, +The 5.3 driver release includes the following new features, improvements, and fixes: .. .. sharedinclude:: dbx/jvm/v5.3-wn-items.rst -- Support for using builder class methods directly with data class +- Support for using builders class methods directly with data class properties. To learn more, see the :ref:`fundamentals-data-classes` guide and the :ref:`kotlin-builders-landing` guides. From 508d1ca15a9e835d296a3f731092250581fe1e25 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:05:45 -0500 Subject: [PATCH 04/18] PR restructure and pushing v5.3 changes --- config/redirects | 2 +- examples/build.gradle.kts | 11 +- examples/gradle.properties | 2 +- .../src/test/kotlin/BuildersDataClassTest.kt | 256 ++++++++++++++++++ examples/src/test/kotlin/DataClassTest.kt | 21 -- snooty.toml | 6 +- source/api-documentation.txt | 17 +- ...ClassTest.snippet.aggregates-data-class.kt | 13 + ...uildersDataClassTest.snippet.data-class.kt | 5 + ...ataClassTest.snippet.filters-data-class.kt | 15 + ...ataClassTest.snippet.indexes-data-class.kt | 5 + ...lassTest.snippet.projections-data-class.kt | 6 + ...sDataClassTest.snippet.sorts-data-class.kt | 6 + ...ataClassTest.snippet.updates-data-class.kt | 6 + source/fundamentals/builders.txt | 70 +++-- .../builders/builders-data-classes.txt | 244 +++++++++++++++++ source/fundamentals/builders/filters.txt | 6 +- .../document-data-format-data-class.txt | 24 -- .../data-formats/serialization.txt | 2 +- .../language-compatibility-table-kotlin.rst | 2 +- .../mongodb-compatibility-table-kotlin.rst | 2 +- source/whats-new.txt | 11 +- 22 files changed, 634 insertions(+), 98 deletions(-) create mode 100644 examples/src/test/kotlin/BuildersDataClassTest.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.aggregates-data-class.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.data-class.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.indexes-data-class.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.projections-data-class.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.sorts-data-class.kt create mode 100644 source/examples/generated/BuildersDataClassTest.snippet.updates-data-class.kt create mode 100644 source/fundamentals/builders/builders-data-classes.txt diff --git a/config/redirects b/config/redirects index 60527205..9fa68e38 100644 --- a/config/redirects +++ b/config/redirects @@ -1,6 +1,6 @@ define: prefix docs/drivers/kotlin/coroutine define: base https://www.mongodb.com/${prefix} -define: versions v4.10 v4.11 v5.0 v5.1 v5.2 master +define: versions v4.10 v4.11 v5.0 v5.1 v5.2 v5.3 master raw: ${prefix}/ -> ${base}/current/ diff --git a/examples/build.gradle.kts b/examples/build.gradle.kts index 4f0b93b6..b5cd3ff0 100644 --- a/examples/build.gradle.kts +++ b/examples/build.gradle.kts @@ -1,10 +1,10 @@ val kotlin_mongodb_version: String by project plugins { - kotlin("jvm") version "1.8.0" + id("org.jetbrains.kotlin.jvm") version "1.9.25" id("com.google.osdetector") version "1.7.3" application - kotlin("plugin.serialization") version "1.8.21" + id("org.jetbrains.kotlin.plugin.serialization") version "1.9.25" } group = "org.mongodb.docs.kotlin" @@ -26,10 +26,11 @@ dependencies { implementation("io.netty:netty-tcnative-boringssl-static:2.0.59.Final:${osdetector.classifier}") implementation("org.xerial.snappy:snappy-java:1.1.10.0") implementation("com.github.luben:zstd-jni:1.5.5-4") - implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.0") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3") implementation("org.mongodb:bson-kotlinx:$kotlin_mongodb_version") - implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.0") + implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1") + implementation("org.mongodb:mongodb-driver-kotlin-extensions:$kotlin_mongodb_version") } tasks.test { diff --git a/examples/gradle.properties b/examples/gradle.properties index 28ecde2d..1998c01e 100644 --- a/examples/gradle.properties +++ b/examples/gradle.properties @@ -1,2 +1,2 @@ kotlin.code.style=official -kotlin_mongodb_version=5.2.0 +kotlin_mongodb_version=5.3.0 diff --git a/examples/src/test/kotlin/BuildersDataClassTest.kt b/examples/src/test/kotlin/BuildersDataClassTest.kt new file mode 100644 index 00000000..a1231aee --- /dev/null +++ b/examples/src/test/kotlin/BuildersDataClassTest.kt @@ -0,0 +1,256 @@ +import com.mongodb.kotlin.client.model.Aggregates.count +import com.mongodb.client.model.Aggregates.group +import com.mongodb.client.model.Aggregates.limit +import com.mongodb.client.model.Aggregates.sort +import com.mongodb.kotlin.client.coroutine.MongoClient +import config.getConfig +import kotlinx.coroutines.flow.firstOrNull +import kotlinx.coroutines.runBlocking +import org.junit.jupiter.api.AfterAll +import org.junit.jupiter.api.AfterEach +import org.junit.jupiter.api.Assertions +import org.junit.jupiter.api.Test +import org.junit.jupiter.api.TestInstance + +import com.mongodb.kotlin.client.model.Filters.eq +import com.mongodb.kotlin.client.model.Filters.all +import com.mongodb.kotlin.client.model.Indexes +import com.mongodb.kotlin.client.model.Projections.excludeId +import com.mongodb.kotlin.client.model.Projections.fields +import com.mongodb.kotlin.client.model.Projections.include +import com.mongodb.client.model.Sorts.orderBy +import com.mongodb.kotlin.client.model.Accumulators.avg +import com.mongodb.kotlin.client.model.Sorts + +import com.mongodb.kotlin.client.model.Filters.gte +import com.mongodb.kotlin.client.model.Updates.addToSet +import com.mongodb.kotlin.client.model.Updates.combine +import com.mongodb.kotlin.client.model.Updates.max +import kotlin.test.assertEquals +import kotlin.test.assertTrue + +@TestInstance(TestInstance.Lifecycle.PER_CLASS) +internal class BuildersDataClassTest { + + companion object { + val config = getConfig() + val client = MongoClient.create(config.connectionUri) + val database = client.getDatabase("school") + + @AfterAll + @JvmStatic + fun afterAll() { + runBlocking { + client.close() + } + } + } + + @AfterEach + fun afterEach() { + runBlocking { + database.drop() + } + } + + // :snippet-start: data-class + data class Student( + val name: String, + val teachers: List, + val gradeAverage: Double + ) + // :snippet-end: + + + @Test + fun filtersTest() = runBlocking { + + val collection = database.getCollection("students") + + // :snippet-start: filters-data-class + val student = Student( + "Sandra Nook", + listOf("Alvarez", "Gruber"), + 85.7 + ) + + // Equivalent equality queries + Student::name.eq(student.name) + eq(Student::name, student.name) + Student::name eq student.name // Infix notation + + // Equivalent array queries + all(Student::teachers, student.teachers) + Student::teachers.all(student.teachers) + Student::teachers all student.teachers // Infix notation + // :snippet-end: + + collection.insertOne(student) + val filter = eq(Student::name, student.name) + val result = collection.find(filter).firstOrNull() + Assertions.assertEquals(student, result) + } + + @Test + fun indexesTest() = runBlocking { + + val collection = database.getCollection("students") + + // :snippet-start: indexes-data-class + val ascendingIdx = Indexes.ascending(Student::name) + val descendingIdx = Indexes.descending(Student::teachers) + + val ascIdxName = collection.createIndex(ascendingIdx) + val descIdxName = collection.createIndex(descendingIdx) + // :snippet-end: + + assertEquals("name_1", ascIdxName) + } + + @Test + fun projectionsTest() = runBlocking { + + val collection = database.getCollection("students") + + val student = Student( + "Sandra Nook", + listOf("Alvarez", "Gruber"), + 85.7 + ) + collection.insertOne(student) + + // :snippet-start: projections-data-class + val combinedProj = fields( + include(Student::name, Student::gradeAverage), + excludeId() + ) + + collection.find().projection(combinedProj) + // :snippet-end: + + data class Result(val name: String, val gradeAverage: Double) + val result = collection.find().projection(combinedProj).firstOrNull() + + if (result != null) { + assertEquals(85.7, result.gradeAverage) + } + } + + @Test + fun sortsTest() = runBlocking { + + val collection = database.getCollection("students") + + val student1 = Student( + "Sandra Nook", + listOf("Alvarez", "Gruber"), + 85.7 + ) + val student2 = Student( + "Paolo Sanchez", + listOf("Gruber", "Piselli"), + 89.3 + ) + collection.insertMany(listOf(student1, student2)) + + // :snippet-start: sorts-data-class + val sort = orderBy( + Sorts.descending(Student::gradeAverage), + Sorts.ascending(Student::name) + ) + + collection.find().sort(sort) + // :snippet-end: + + val result = collection.find().sort(sort).firstOrNull() + + if (result != null) { + assertEquals(89.3, result.gradeAverage) + } + } + + @Test + fun updatesTest() = runBlocking { + + val collection = database.getCollection("students") + + val students = listOf( + Student("Sandra Nook", listOf("Alvarez", "Gruber"),85.7), + Student("Paolo Sanchez", listOf("Gruber", "Piselli"),89.3) + ) + collection.insertMany(students) + + // :snippet-start: updates-data-class + val filter = Student::gradeAverage gte 85.0 + val update = combine( + addToSet(Student::teachers, "Soto"), + Student::gradeAverage.max(90.0) + ) + collection.updateMany(filter, update) + // :snippet-end: + + val result = collection.find().firstOrNull() + + if (result != null) { + assertTrue("Soto" in result.teachers) + assertEquals(result.gradeAverage, 90.0) + } + } + + @Test + fun aggregatesTest() = runBlocking { + + val collection = database.getCollection("students") + + val students = listOf( + Student("Sandra Nook", listOf("Alvarez", "Gruber"),85.7), + Student("Paolo Sanchez", listOf("Gruber", "Piselli"),89.3), + Student("Katerina Jakobsen", listOf("Alvarez", "Ender"),97.3), + Student("Emma Frank", listOf("Piselli", "Harbour"),93.4), + Student("Qasim Haq", listOf("Gruber", "Harbour"),80.6) + ) + collection.insertMany(students) + + // :snippet-start: aggregates-data-class + // Data class to store aggregation result + data class Summary ( val average: Double ) + + val pipeline = listOf( + // Sorts grades from high to low + sort(Sorts.descending(Student::gradeAverage)), + // Selects the top 3 students + limit(3), + // Calculates the average of their grades and stores value in a Summary instance + group(null, avg(Summary::average, "\$${Student::gradeAverage.name}")) + ) + + val result = collection.aggregate(pipeline) + // :snippet-end: + + val r = result.firstOrNull() + if (r != null) { + assertEquals(93.33333333333333, r.average) + } + } + + @Test + fun aggregatesCountTest() = runBlocking { + + val collection = database.getCollection("students") + + val students = listOf( + Student("Sandra Nook", listOf("Alvarez", "Gruber"),85.7), + Student("Paolo Sanchez", listOf("Gruber", "Piselli"),89.3), + ) + collection.insertMany(students) + + // :snippet-start: aggregates-data-class + val pipeline = listOf( + count(Student::name) + ) + + val result = collection.aggregate(pipeline) + result.collect { println(it) } + // :snippet-end: + } +} \ No newline at end of file diff --git a/examples/src/test/kotlin/DataClassTest.kt b/examples/src/test/kotlin/DataClassTest.kt index f21d307c..7aa3550c 100644 --- a/examples/src/test/kotlin/DataClassTest.kt +++ b/examples/src/test/kotlin/DataClassTest.kt @@ -1,6 +1,5 @@ import com.mongodb.client.model.Filters -import com.mongodb.client.model.Filters.eq import com.mongodb.client.model.FindOneAndUpdateOptions import com.mongodb.client.model.ReturnDocument import com.mongodb.client.model.Updates @@ -97,26 +96,6 @@ internal class DataClassTest { // :snippet-end: } - @Test - fun queryDataClassTest() = runBlocking { - - val collection = database.getCollection("data_storage") - - // :snippet-start: filters-query-data-class - val record = DataStorage("SSD", 120.0) - // Infixed query - DataStorage::productName.eq(record.productName) - // Nested query - val bson = eq(DataStorage::productName, record.productName) - // Kmongo DSL - val filter = DataStorage::productName eq record.productName - // :snippet-end: - - collection.insertOne(record) - val result = collection.find().firstOrNull() - assertEquals(record, result) - } - // :snippet-start: annotated-data-class data class NetworkDevice( @BsonId diff --git a/snooty.toml b/snooty.toml index 0abbf389..246feedd 100644 --- a/snooty.toml +++ b/snooty.toml @@ -19,8 +19,8 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" driver = "kotlin" driver-short = "Kotlin driver" driver-long = "MongoDB Kotlin Driver" -version = "5.2" -full-version = "{+version+}.1" +version = "5.3" +full-version = "{+version+}.0" language = "Kotlin" mdb-server = "MongoDB server" kotlin-docs = "https://kotlinlang.org" @@ -34,5 +34,5 @@ snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4" zstdVersion = "com.github.luben:zstd-jni:1.5.5-2" logbackVersion = "1.2.11" log4j2Version = "2.17.1" -serializationVersion = "1.5.1" +serializationVersion = "1.7.3" kotlinx-dt-version = "0.6.1" diff --git a/source/api-documentation.txt b/source/api-documentation.txt index b17649f0..6a83a4cd 100644 --- a/source/api-documentation.txt +++ b/source/api-documentation.txt @@ -7,16 +7,21 @@ API Documentation :maxdepth: 1 BSON kotlinx.serialization <{+api+}/apidocs/bson-kotlinx/index.html> - Core <{+api+}/apidocs/mongodb-driver-core/index.html> - Kotlin Coroutine Driver <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/index.html> - Kotlin Sync Driver <{+api+}/apidocs/mongodb-driver-kotlin-sync/index.html> + {+language+} Driver Extensions <{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html> + Driver Core <{+api+}/apidocs/mongodb-driver-core/index.html> + {+language+} Coroutine Driver <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/index.html> + {+language+} Sync Driver <{+api+}/apidocs/mongodb-driver-kotlin-sync/index.html> - `BSON kotlinx.serialization <{+api+}/apidocs/bson-kotlinx/index.html>`__ - classes for encoding and decoding between Kotlin data classes and the BSON data format using :github:`kotlinx.serialization `. -- `Core <{+api+}/apidocs/mongodb-driver-core/index.html>`__ - classes that +- `{+language+} Driver Extensions + <{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ - + classes that extend the core builder classes to support :ref:`data + classes `. +- `Driver Core <{+api+}/apidocs/mongodb-driver-core/index.html>`__ - classes that contain essential driver functionality. -- `Kotlin Coroutine Driver <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/index.html>`__ - +- `{+language+} Coroutine Driver <{+api+}/apidocs/mongodb-driver-kotlin-coroutine/index.html>`__ - classes for the current driver API using coroutines. -- `Kotlin Sync Driver <{+api+}/apidocs/mongodb-driver-kotlin-sync/index.html>`__ - +- `{+language+} Sync Driver <{+api+}/apidocs/mongodb-driver-kotlin-sync/index.html>`__ - classes for the current synchronous driver API. diff --git a/source/examples/generated/BuildersDataClassTest.snippet.aggregates-data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.aggregates-data-class.kt new file mode 100644 index 00000000..44fb35f9 --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.aggregates-data-class.kt @@ -0,0 +1,13 @@ +// Data class to store aggregation result +data class Summary ( val average: Double ) + +val pipeline = listOf( + // Sorts grades from high to low + sort(Sorts.descending(Student::gradeAverage)), + // Selects the top 3 students + limit(3), + // Calculates the average of their grades and stores value in a Summary instance + group(null, avg(Summary::average, "\$${Student::gradeAverage.name}")) +) + +val result = collection.aggregate(pipeline) diff --git a/source/examples/generated/BuildersDataClassTest.snippet.data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.data-class.kt new file mode 100644 index 00000000..8edca520 --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.data-class.kt @@ -0,0 +1,5 @@ +data class Student( + val name: String, + val teachers: List, + val gradeAverage: Double +) diff --git a/source/examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt new file mode 100644 index 00000000..f0c32ebb --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt @@ -0,0 +1,15 @@ +val student = Student( + "Sandra Nook", + listOf("Alvarez", "Gruber"), + 85.7 +) + +// Equivalent equality queries +Student::name.eq(student.name) +eq(Student::name, student.name) +Student::name eq student.name // Infix notation + +// Equivalent array queries +all(Student::teachers, student.teachers) +Student::teachers.all(student.teachers) +Student::teachers all student.teachers // Infix notation diff --git a/source/examples/generated/BuildersDataClassTest.snippet.indexes-data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.indexes-data-class.kt new file mode 100644 index 00000000..baeae8ac --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.indexes-data-class.kt @@ -0,0 +1,5 @@ +val ascendingIdx = Indexes.ascending(Student::name) +val descendingIdx = Indexes.descending(Student::teachers) + +val ascIdxName = collection.createIndex(ascendingIdx) +val descIdxName = collection.createIndex(descendingIdx) diff --git a/source/examples/generated/BuildersDataClassTest.snippet.projections-data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.projections-data-class.kt new file mode 100644 index 00000000..4da8cc23 --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.projections-data-class.kt @@ -0,0 +1,6 @@ +val combinedProj = fields( + include(Student::name, Student::gradeAverage), + excludeId() +) + +collection.find().projection(combinedProj) diff --git a/source/examples/generated/BuildersDataClassTest.snippet.sorts-data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.sorts-data-class.kt new file mode 100644 index 00000000..803372a9 --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.sorts-data-class.kt @@ -0,0 +1,6 @@ +val sort = orderBy( + Sorts.descending(Student::gradeAverage), + Sorts.ascending(Student::name) +) + +collection.find().sort(sort) diff --git a/source/examples/generated/BuildersDataClassTest.snippet.updates-data-class.kt b/source/examples/generated/BuildersDataClassTest.snippet.updates-data-class.kt new file mode 100644 index 00000000..a17d0ee5 --- /dev/null +++ b/source/examples/generated/BuildersDataClassTest.snippet.updates-data-class.kt @@ -0,0 +1,6 @@ +val filter = Student::gradeAverage gte 85.0 +val update = combine( + addToSet(Student::teachers, "Soto"), + Student::gradeAverage.max(90.0) +) +collection.updateMany(filter, update) diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 7bd54273..ef4a4dbd 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -12,6 +12,7 @@ Builders Projection Sort Update + Use Builders with Data Classes .. contents:: On this page :local: @@ -23,46 +24,47 @@ Overview -------- This section includes guides on how to use each of the available -builders, and demonstrates the utility the MongoDB Kotlin driver builder classes -provide. +builders and demonstrates the utility that the {+driver-short} builder +classes provide. -The Kotlin driver provides classes to simplify the process for developers -to use CRUD operations and the Aggregation API. The static utility methods allow you -to build a query more efficiently. +The {+driver-short} provides classes to simplify the process of +performing CRUD operations and the Aggregation API. The static utility +methods allow you to build queries and other kinds of documents more +efficiently. Why Use Builders? ----------------- -Using the builders class, you leverage the power of: +When you use builders classes, you leverage the following products: -- The Kotlin compiler and the IDE to find errors during development -- The IDE for discovery and code completion +- The {+language+} compiler to find errors during development +- The IDE for discovery, debugging, and code completion -When using builders, the Kotlin compiler and the IDE catch errors such as misspelled -operators early on. When using the MongoDB shell or plain Kotlin, you -write operators as strings and get no visual indication of a problem, -pushing these errors to runtime instead of compile time. +When using builders, the {+language+} compiler and the IDE catch errors +such as misspelled operators or missing parameters early on. If you use +the MongoDB shell or plain {+language+} instead, you write operators as +strings and get no visual indication of a problem, which pushes these +errors to runtime instead of compile time. -With the builder classes, you write operators as methods. The IDE -instantly underlines and gives you a red bar on the right indicating -something is wrong. While developing, the IDE also shows you the -methods you can use. It automatically completes your code with -placeholder parameters once you select which method you want to use. +By using builder classes, you cab write operators as methods. The IDE +instantly indicates whether your code has errors. While developing, the +IDE also shows you the methods you can use and can complete your code with +placeholder parameters. -Scenario --------- +Example Scenario +---------------- -Imagine we want to send a marketing email to all users in our ``users`` -collection with the following criteria: +Suppose you want to send a marketing email to all users in the ``users`` +collection that meet the following criteria: -- Users that identify as ``female`` gender -- Users that are older than ``29`` +- Users in which the value of the ``gender`` field is ``"female"`` +- Users in which the value of the ``age`` field is greater than ``29`` -We only want their email address, so we'll ensure our query doesn't -return data we pay bandwidth costs for but don't need. +You only want their email addresses, so your query won't +return data that you don't need. -The documents in the ``users`` collection are modeled with the following data class -in our application: +The documents in the ``users`` collection are modeled by the following +data class: .. literalinclude:: /examples/generated/BuildersTest.snippet.user-data-class.kt :language: kotlin @@ -70,6 +72,9 @@ in our application: Using the MongoDB Shell ~~~~~~~~~~~~~~~~~~~~~~~ +The following code provides the command you use in the MongoDB Shell to +perform the query: + .. code-block:: js collection.find({ "gender": "female", "age" : { "$gt": 29 }}, { "_id": 0, "email": 1 }) @@ -77,12 +82,18 @@ Using the MongoDB Shell Without Using Builders ~~~~~~~~~~~~~~~~~~~~~~ +The following code provides the find operation you create without +builders in the {+driver-short+}: + .. literalinclude:: /examples/generated/BuildersTest.snippet.no-builders.kt :language: kotlin Using Builders ~~~~~~~~~~~~~~ +The following code provides the find operation you create by using +builders in the {+driver-short+}: + .. code-block:: kotlin import com.mongodb.client.model.Filters @@ -100,3 +111,8 @@ Available Builders - :ref:`Projections ` for building projections. - :ref:`Sorts ` for building sort criteria. - :ref:`Updates ` for building updates. + +The :ref:`kotlin-builders-data-classes` guide provides examples on +how to use the preceding builders classes directly with data class +properties. This guide might help to make your application more type-safe +and improve {+language+} interoperability. diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt new file mode 100644 index 00000000..00564744 --- /dev/null +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -0,0 +1,244 @@ +.. _kotlin-builders-data-classes: + +============================== +Use Builders with Data Classes +============================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, data format, modeling, interoperability + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use your data class properties +directly with the builder classes available in +the {+driver-short+}. + +The {+driver-short+} implements extensions that allow you to reference +your data class properties when using builder methods instead of using +string field names. You can structure your code in this way to make your +code more type-safe and improve your applications {+language+} +interoperability. + +.. note:: + + This page provides a limited number of code + examples to demonstrate this functionality. To view examples for all of + the builder classes, see the :ref:`kotlin-builders-landing` guides. + +Add {+language+} Extensions to Your Project +------------------------------------- + +To implement this functionality, you must add the +``mongodb-driver-kotlin-extensions`` dependency to your dependencies +list. + +Select from the following tabs to see how to add the extension +dependency to your project by using the :guilabel:`Gradle` and +:guilabel:`Maven` package managers: + +.. tabs:: + + .. tab:: + :tabid: Gradle + + If you are using `Gradle `__ to manage your + dependencies, add the following to your ``build.gradle.kts`` dependencies list: + + .. code-block:: kotlin + :caption: build.gradle.kts + + implementation("org.mongodb:mongodb-driver-kotlin-extensions:{+full-version+}") + + .. tab:: + :tabid: Maven + + If you are using `Maven `__ to manage your + dependencies, add the following to your ``pom.xml`` dependencies list: + + .. code-block:: xml + :caption: pom.xml + + + org.mongodb + mongodb-driver-kotlin-extensions + {+full-version+} + + +After you install the extensions dependency, you can use the extension +methods by importing classes and methods from the +``com.mongodb.kotlin.client.model`` path. The standard builder classes +and methods are accessible from the ``com.mongodb.client.model`` path, +which allows you to mix calls that reference string field names and data +class properties in the same application. + +Builders Examples +----------------- + +This section contains examples that demonstrate how to use data class +properties directly with builder class methods from the extensions +package. + +.. tip:: Data Class Annotations + + When you the extension builder class methods data + classes, the methods respect your data class annotations from the + ``bson-kotlin`` and ``bson-kotlinx`` packages. To learn more about + annotations, see the :ref:`fundamentals-data-class-annotations` + section of the Document Data Format: Data Classes guide and the + :ref:`kotlin-data-class-annotation` section in the {+language+} + Serialization guide. + +Sample Data +~~~~~~~~~~~ + +The examples in this section use documents in the ``students`` +collection that describe students at a school. Documents in the +``students`` collection are modeled by the following {+language+} data +class: + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.data-class.kt + :language: kotlin + +.. _kotlin-data-class-filters: + +Filters +~~~~~~~ + +You can use helpers from the ``Filters`` builders class to query on data +class properties. To learn more about this class, see the +:ref:`filters-builders` guide. + +The following code shows different ways to use ``Filters`` extension +methods to perform queries on the ``Student`` data class: + +.. code-block:: kotlin + + import com.mongodb.kotlin.client.model.Filters.eq + import com.mongodb.kotlin.client.model.Filters.all + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt + :language: kotlin + +.. _kotlin-data-class-indexes: + +Indexes +~~~~~~~ + +You can use helpers from the ``Indexes`` builders class to create +indexes on data class properties. To learn more about this class, see the +:ref:`indexes-builders` guide. + +The following code shows different ways to use ``Indexes`` extension +methods to create indexes on the ``Student`` data class: + +.. code-block:: kotlin + + import com.mongodb.kotlin.client.model.Indexes.ascending + import com.mongodb.kotlin.client.model.Indexes.descending + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.indexes-data-class.kt + :language: kotlin + +.. _kotlin-data-class-projections: + +Projections +~~~~~~~~~~~ + +You can use helpers from the ``Projections`` builders class to create +projections for data class properties. To learn more about this class, see the +:ref:`projections-builders` guide. + +The following code shows how to use ``Projections`` extension +methods to create a projection on the ``Student`` data class: + +.. code-block:: kotlin + + import com.mongodb.kotlin.client.model.Projections.excludeId + import com.mongodb.kotlin.client.model.Projections.fields + import com.mongodb.kotlin.client.model.Projections.include + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.projections-data-class.kt + :language: kotlin + +.. _kotlin-data-class-sorts: + +Sorts +~~~~~ + +You can use helpers from the ``Sorts`` builders class to sort +on your data class properties. To learn more about this class, see the +:ref:`sorts-builders` guide. + +The following code shows how to use ``Sorts`` extension +methods to create different sorts on the ``Student`` data class: + +.. code-block:: kotlin + + import com.mongodb.client.model.Sorts.orderBy + import com.mongodb.kotlin.client.model.Sorts + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.sorts-data-class.kt + :language: kotlin + +.. _kotlin-data-class-updates: + +Updates +~~~~~~~ + +You can use helpers from the ``Updates`` builders class to perform +updates by using your data class properties. To learn more about this +class, see the :ref:`updates-builders` guide. + +The following code shows how to use ``Sorts`` extension +methods to create different sorts on the ``Student`` data class: + +.. code-block:: kotlin + + import com.mongodb.kotlin.client.model.Filters.gte + import com.mongodb.kotlin.client.model.Updates.addToSet + import com.mongodb.kotlin.client.model.Updates.combine + import com.mongodb.kotlin.client.model.Updates.max + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.updates-data-class.kt + :language: kotlin + +.. _kotlin-data-class-aggregates: + +Aggregates +~~~~~~~~~~ + +You can use helpers from the ``Aggregates`` and ``Accumulators`` +builders classes to perform aggregations by using you data class +properties. To learn more about these classes, see the +:ref:`aggregates-builders` guide. + +The following code shows how to use ``Accumulators`` extension +methods and ``Aggregates`` helper methods to perform an aggregation on +the ``Student`` data class: + +.. code-block:: kotlin + + import com.mongodb.client.model.Aggregates.group + import com.mongodb.client.model.Aggregates.limit + import com.mongodb.client.model.Aggregates.sort + import com.mongodb.kotlin.client.model.Accumulators.avg + +.. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.aggregates-data-class.kt + :language: kotlin + +API Documentation +----------------- + +- `{+driver-short+} Extensions + <{+api}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ diff --git a/source/fundamentals/builders/filters.txt b/source/fundamentals/builders/filters.txt index c01ac86b..0742481e 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/fundamentals/builders/filters.txt @@ -85,9 +85,9 @@ with the Kotlin driver: .. tip:: Filters and Data Class Properties You can use methods from the ``Filters`` class directly with data class - properties. To learn more and view examples, see the - :ref:`kotlin-data-class-query` section of the Document Data Format: - Data Classes guide. + properties by adding the optional {+driver-short +}extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. .. _comparison: 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 a5a18910..6109b24d 100644 --- a/source/fundamentals/data-formats/document-data-format-data-class.txt +++ b/source/fundamentals/data-formats/document-data-format-data-class.txt @@ -85,30 +85,6 @@ operation adds the ``releaseDate`` field to the document with a For more information about this feature, see :ref:`Specify Return Type ` in the Databases and Collections guide. -.. _kotlin-data-class-query: - -Querying Data Classes ---------------------- - -You can use helpers from the ``Filters`` builders class to query on data -class properties. To learn more about this class, see the -:ref:`filters-builders` guide. - -The following code uses the ``Filters.eq()`` method to -construct the same query on the ``DataStorage`` data class in multiple syntaxes: - -.. literalinclude:: /examples/generated/DataClassTest.snippet.filters-query-data-class.kt - :language: kotlin - -.. tip:: Filters and Data Class Annotations - - When you use ``Filters`` class helpers to construct queries on data - classes, the methods respect your data class annotations from the - ``bson-kotlin`` and ``bson-kotlinx`` packages. To learn more about - annotations, see the :ref:`fundamentals-data-class-annotations` - section of this guide and the :ref:`kotlin-data-class-annotation` - section in the {+language+} Serialization guide. - .. _fundamentals-data-class-annotations: Specify Component Conversion Using Annotations diff --git a/source/fundamentals/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt index 5be4d17b..16ca363a 100644 --- a/source/fundamentals/data-formats/serialization.txt +++ b/source/fundamentals/data-formats/serialization.txt @@ -54,7 +54,7 @@ The {+driver-short+} supports: - All Kotlin types that are supported by the Kotlin serialization library - All available :manual:`BSON types ` -Add Kotlin Serialization to Your Project +Add {+language+} Serialization to Your Project ---------------------------------------- Support for serialization in the {+driver-short+} depends on the official `Kotlin diff --git a/source/includes/language-compatibility-table-kotlin.rst b/source/includes/language-compatibility-table-kotlin.rst index 8b56e985..02d3f294 100644 --- a/source/includes/language-compatibility-table-kotlin.rst +++ b/source/includes/language-compatibility-table-kotlin.rst @@ -7,5 +7,5 @@ * - Kotlin Driver Version - Kotlin 1.8 - * - 4.10 to 5.2 + * - 4.10 to 5.3 - ✓ diff --git a/source/includes/mongodb-compatibility-table-kotlin.rst b/source/includes/mongodb-compatibility-table-kotlin.rst index dbd5fd4e..d77a7077 100644 --- a/source/includes/mongodb-compatibility-table-kotlin.rst +++ b/source/includes/mongodb-compatibility-table-kotlin.rst @@ -13,7 +13,7 @@ - MongoDB 4.0 - MongoDB 3.6 - * - 5.2 + * - 5.2 to 5.3 - ✓ - ✓ - ✓ diff --git a/source/whats-new.txt b/source/whats-new.txt index 71cc4343..5e7614c1 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -30,11 +30,14 @@ What's New in 5.3 The 5.3 driver release includes the following new features, improvements, and fixes: -.. .. sharedinclude:: dbx/jvm/v5.3-wn-items.rst - - Support for using builders class methods directly with data class - properties. To learn more, see the :ref:`fundamentals-data-classes` - guide and the :ref:`kotlin-builders-landing` guides. + properties. To learn more, see the :ref:`kotlin-builders-data-classes` + guide. This functionality is supported by the `{+driver-short+} + Extensions package + <{+api}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ + published with this release. + +.. sharedinclude:: dbx/jvm/v5.3-wn-items.rst .. _kotlin-coroutine-version-5.2: From 20c31c615d22596fc4d07e4d6236745f4a49dd6c Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:08:39 -0500 Subject: [PATCH 05/18] cross links --- source/fundamentals/builders/aggregates.txt | 8 ++++++++ source/fundamentals/builders/filters.txt | 2 +- source/fundamentals/builders/indexes.txt | 7 +++++++ source/fundamentals/builders/projections.txt | 8 +++++++- source/fundamentals/builders/sort.txt | 7 +++++++ source/fundamentals/builders/updates.txt | 7 +++++++ 6 files changed, 37 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index 1ee12e0e..afb8ce0b 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/fundamentals/builders/aggregates.txt @@ -54,6 +54,14 @@ modeled by the following ``Movie`` data class for use with the Kotlin driver: .. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.movie-data-class.kt :language: kotlin +.. tip:: Aggregates and Data Class Properties + + You can use methods from the ``Aggregates`` and + ``Accumulators`` classes directly with data class + properties by adding the optional {+driver-short +} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. + Match ----- diff --git a/source/fundamentals/builders/filters.txt b/source/fundamentals/builders/filters.txt index 0742481e..95518012 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/fundamentals/builders/filters.txt @@ -85,7 +85,7 @@ with the Kotlin driver: .. tip:: Filters and Data Class Properties You can use methods from the ``Filters`` class directly with data class - properties by adding the optional {+driver-short +}extensions + properties by adding the optional {+driver-short +} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/fundamentals/builders/indexes.txt b/source/fundamentals/builders/indexes.txt index 425f62dd..44f3359e 100644 --- a/source/fundamentals/builders/indexes.txt +++ b/source/fundamentals/builders/indexes.txt @@ -45,6 +45,13 @@ instance, which you can pass to import com.mongodb.client.model.Indexes.* +.. tip:: Indexes and Data Class Properties + + You can use methods from the ``Indexes`` class directly with data class + properties by adding the optional {+driver-short +} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. + .. _ascending-indexes: Ascending Indexes diff --git a/source/fundamentals/builders/projections.txt b/source/fundamentals/builders/projections.txt index fa62ccac..d8090ac7 100644 --- a/source/fundamentals/builders/projections.txt +++ b/source/fundamentals/builders/projections.txt @@ -40,7 +40,6 @@ to any method that expects a projection. import com.mongodb.client.model.Projections.* - Sample Documents and Examples ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -96,6 +95,13 @@ The following data class is used to represent the documents in the collection: .. literalinclude:: /examples/generated/ProjectionsBuildersTest.snippet.example-data-class.kt :language: kotlin +.. tip:: Projections and Data Class Properties + + You can use methods from the ``Projections`` class directly with data class + properties by adding the optional {+driver-short +} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. + Projection Operations --------------------- diff --git a/source/fundamentals/builders/sort.txt b/source/fundamentals/builders/sort.txt index 4fd07f02..98b1d6d3 100644 --- a/source/fundamentals/builders/sort.txt +++ b/source/fundamentals/builders/sort.txt @@ -53,6 +53,13 @@ This data is modeled with the following Kotlin data class: .. literalinclude:: /examples/generated/SortTest.snippet.sort-data-model.kt :language: kotlin +.. tip:: Sorts and Data Class Properties + + You can use methods from the ``Sorts`` class directly with data class + properties by adding the optional {+driver-short +} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. + The Sorts Class --------------- diff --git a/source/fundamentals/builders/updates.txt b/source/fundamentals/builders/updates.txt index 5f3e74e7..3b24506d 100644 --- a/source/fundamentals/builders/updates.txt +++ b/source/fundamentals/builders/updates.txt @@ -68,6 +68,13 @@ This example is modeled by the following data class unless otherwise noted: .. literalinclude:: /examples/generated/UpdatesBuildersTest.snippet.example-data-class.kt :language: kotlin +.. tip:: Updates and Data Class Properties + + You can use methods from the ``Updates`` class directly with data class + properties by adding the optional {+driver-short +} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. + .. _field_updates: Field Updates From b056571b493a40aabfea0fd1717f41549b2e8bc2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:11:52 -0500 Subject: [PATCH 06/18] fixes --- source/fundamentals/builders/builders-data-classes.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt index 00564744..ef39fa6f 100644 --- a/source/fundamentals/builders/builders-data-classes.txt +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -33,7 +33,7 @@ interoperability. .. note:: This page provides a limited number of code - examples to demonstrate this functionality. To view examples for all of + examples to demonstrate this functionality. To view examples for all the builder classes, see the :ref:`kotlin-builders-landing` guides. Add {+language+} Extensions to Your Project @@ -77,9 +77,9 @@ dependency to your project by using the :guilabel:`Gradle` and After you install the extensions dependency, you can use the extension methods by importing classes and methods from the -``com.mongodb.kotlin.client.model`` path. The standard builder classes -and methods are accessible from the ``com.mongodb.client.model`` path, -which allows you to mix calls that reference string field names and data +``com.mongodb.kotlin.client.model`` path. You can access the standard +builder classes and methods from the ``com.mongodb.client.model`` path, +so you can mix calls that reference string field names and data class properties in the same application. Builders Examples From f9fa8100c91a4796afa3998b2c508bab66a66e00 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:14:24 -0500 Subject: [PATCH 07/18] fixes --- .../src/test/kotlin/BuildersDataClassTest.kt | 21 ------------------- 1 file changed, 21 deletions(-) diff --git a/examples/src/test/kotlin/BuildersDataClassTest.kt b/examples/src/test/kotlin/BuildersDataClassTest.kt index a1231aee..bec953c9 100644 --- a/examples/src/test/kotlin/BuildersDataClassTest.kt +++ b/examples/src/test/kotlin/BuildersDataClassTest.kt @@ -232,25 +232,4 @@ internal class BuildersDataClassTest { assertEquals(93.33333333333333, r.average) } } - - @Test - fun aggregatesCountTest() = runBlocking { - - val collection = database.getCollection("students") - - val students = listOf( - Student("Sandra Nook", listOf("Alvarez", "Gruber"),85.7), - Student("Paolo Sanchez", listOf("Gruber", "Piselli"),89.3), - ) - collection.insertMany(students) - - // :snippet-start: aggregates-data-class - val pipeline = listOf( - count(Student::name) - ) - - val result = collection.aggregate(pipeline) - result.collect { println(it) } - // :snippet-end: - } } \ No newline at end of file From 5239a20e95df46263f2f05499800b1553ea893ec Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:16:09 -0500 Subject: [PATCH 08/18] shorten toc name --- source/fundamentals/builders.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index ef4a4dbd..5bd96785 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -12,7 +12,7 @@ Builders Projection Sort Update - Use Builders with Data Classes + Builders & Data Classes .. contents:: On this page :local: From c1e534b27791468b1b7ef597ebe14914efb15918 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:20:14 -0500 Subject: [PATCH 09/18] fix link --- source/fundamentals/builders/builders-data-classes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt index ef39fa6f..7c049f11 100644 --- a/source/fundamentals/builders/builders-data-classes.txt +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -241,4 +241,4 @@ API Documentation ----------------- - `{+driver-short+} Extensions - <{+api}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ + <{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ From d06be1f01093d331e985fcbf687dc73e763907cf Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 11:34:54 -0500 Subject: [PATCH 10/18] small version fixes --- examples/build.gradle.kts | 5 +++-- examples/src/test/kotlin/BuildersDataClassTest.kt | 1 - snooty.toml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/build.gradle.kts b/examples/build.gradle.kts index b5cd3ff0..c9ae5260 100644 --- a/examples/build.gradle.kts +++ b/examples/build.gradle.kts @@ -5,6 +5,7 @@ plugins { id("com.google.osdetector") version "1.7.3" application id("org.jetbrains.kotlin.plugin.serialization") version "1.9.25" + id("org.jetbrains.kotlin.plugin.scripting") version "1.9.25" } group = "org.mongodb.docs.kotlin" @@ -26,8 +27,8 @@ dependencies { implementation("io.netty:netty-tcnative-boringssl-static:2.0.59.Final:${osdetector.classifier}") implementation("org.xerial.snappy:snappy-java:1.1.10.0") implementation("com.github.luben:zstd-jni:1.5.5-4") - implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3") - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.6.0") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0") implementation("org.mongodb:bson-kotlinx:$kotlin_mongodb_version") implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1") implementation("org.mongodb:mongodb-driver-kotlin-extensions:$kotlin_mongodb_version") diff --git a/examples/src/test/kotlin/BuildersDataClassTest.kt b/examples/src/test/kotlin/BuildersDataClassTest.kt index bec953c9..6fdc67d6 100644 --- a/examples/src/test/kotlin/BuildersDataClassTest.kt +++ b/examples/src/test/kotlin/BuildersDataClassTest.kt @@ -1,4 +1,3 @@ -import com.mongodb.kotlin.client.model.Aggregates.count import com.mongodb.client.model.Aggregates.group import com.mongodb.client.model.Aggregates.limit import com.mongodb.client.model.Aggregates.sort diff --git a/snooty.toml b/snooty.toml index 246feedd..1c3375a3 100644 --- a/snooty.toml +++ b/snooty.toml @@ -34,5 +34,5 @@ snappyVersion = "org.xerial.snappy:snappy-java:1.1.8.4" zstdVersion = "com.github.luben:zstd-jni:1.5.5-2" logbackVersion = "1.2.11" log4j2Version = "2.17.1" -serializationVersion = "1.7.3" +serializationVersion = "1.6.0" kotlinx-dt-version = "0.6.1" From 0c0f1dedfb3c7d61c6fe1e658047c4b6e33b3e3a Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 14:26:17 -0500 Subject: [PATCH 11/18] add cross link --- source/fundamentals/builders/aggregates.txt | 2 +- source/fundamentals/builders/filters.txt | 2 +- source/fundamentals/builders/indexes.txt | 2 +- source/fundamentals/builders/projections.txt | 2 +- source/fundamentals/builders/sort.txt | 2 +- source/fundamentals/builders/updates.txt | 2 +- .../data-formats/document-data-format-data-class.txt | 7 +++++++ 7 files changed, 13 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index afb8ce0b..8d39eba8 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/fundamentals/builders/aggregates.txt @@ -58,7 +58,7 @@ modeled by the following ``Movie`` data class for use with the Kotlin driver: You can use methods from the ``Aggregates`` and ``Accumulators`` classes directly with data class - properties by adding the optional {+driver-short +} extensions + properties by adding the optional {+driver-short+} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/fundamentals/builders/filters.txt b/source/fundamentals/builders/filters.txt index 95518012..185c08fe 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/fundamentals/builders/filters.txt @@ -85,7 +85,7 @@ with the Kotlin driver: .. tip:: Filters and Data Class Properties You can use methods from the ``Filters`` class directly with data class - properties by adding the optional {+driver-short +} extensions + properties by adding the optional {+driver-short+} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/fundamentals/builders/indexes.txt b/source/fundamentals/builders/indexes.txt index 44f3359e..88f82a33 100644 --- a/source/fundamentals/builders/indexes.txt +++ b/source/fundamentals/builders/indexes.txt @@ -48,7 +48,7 @@ instance, which you can pass to .. tip:: Indexes and Data Class Properties You can use methods from the ``Indexes`` class directly with data class - properties by adding the optional {+driver-short +} extensions + properties by adding the optional {+driver-short+} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/fundamentals/builders/projections.txt b/source/fundamentals/builders/projections.txt index d8090ac7..cb78a045 100644 --- a/source/fundamentals/builders/projections.txt +++ b/source/fundamentals/builders/projections.txt @@ -98,7 +98,7 @@ The following data class is used to represent the documents in the collection: .. tip:: Projections and Data Class Properties You can use methods from the ``Projections`` class directly with data class - properties by adding the optional {+driver-short +} extensions + properties by adding the optional {+driver-short+} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/fundamentals/builders/sort.txt b/source/fundamentals/builders/sort.txt index 98b1d6d3..e3ee8329 100644 --- a/source/fundamentals/builders/sort.txt +++ b/source/fundamentals/builders/sort.txt @@ -56,7 +56,7 @@ This data is modeled with the following Kotlin data class: .. tip:: Sorts and Data Class Properties You can use methods from the ``Sorts`` class directly with data class - properties by adding the optional {+driver-short +} extensions + properties by adding the optional {+driver-short+} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/fundamentals/builders/updates.txt b/source/fundamentals/builders/updates.txt index 3b24506d..1dce3023 100644 --- a/source/fundamentals/builders/updates.txt +++ b/source/fundamentals/builders/updates.txt @@ -71,7 +71,7 @@ This example is modeled by the following data class unless otherwise noted: .. tip:: Updates and Data Class Properties You can use methods from the ``Updates`` class directly with data class - properties by adding the optional {+driver-short +} extensions + properties by adding the optional {+driver-short+} extensions dependency to your application. To learn more and view examples, see the :ref:`kotlin-builders-data-classes` guide. 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 6109b24d..8b3b6c3b 100644 --- a/source/fundamentals/data-formats/document-data-format-data-class.txt +++ b/source/fundamentals/data-formats/document-data-format-data-class.txt @@ -60,6 +60,13 @@ as shown in the following code: DataStorage(productName=tape, capacity=5.0) +.. tip:: Builders for Data Class Properties + + You can use methods from builder classes directly with data class + properties by adding the optional {+driver-short+} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. + You specify a class for documents returned from a collection, even if it is different than the class you specified when retrieving the collection. From c8a2c9c7255906b1c81592acd8db5768982f25a8 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 14 Jan 2025 17:21:46 -0500 Subject: [PATCH 12/18] RM PR fixes 1 --- source/fundamentals/builders.txt | 25 +++++++++++-------- source/fundamentals/builders/aggregates.txt | 8 +----- .../builders/builders-data-classes.txt | 7 +++--- source/fundamentals/builders/filters.txt | 7 +----- source/fundamentals/builders/indexes.txt | 7 +----- source/fundamentals/builders/projections.txt | 7 +----- source/fundamentals/builders/sort.txt | 7 +----- source/fundamentals/builders/updates.txt | 11 +++----- .../document-data-format-data-class.txt | 7 +----- .../fundamentals/builders-dataclass.rst | 6 +++++ source/whats-new.txt | 2 +- 11 files changed, 33 insertions(+), 61 deletions(-) create mode 100644 source/includes/fundamentals/builders-dataclass.rst diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 5bd96785..c41d982f 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -24,13 +24,13 @@ Overview -------- This section includes guides on how to use each of the available -builders and demonstrates the utility that the {+driver-short} builder +builders and demonstrates the utility that the {+driver-short+} builder classes provide. -The {+driver-short} provides classes to simplify the process of -performing CRUD operations and the Aggregation API. The static utility -methods allow you to build queries and other kinds of documents more -efficiently. +The {+driver-short+} provides classes to simplify the process of +performing CRUD operations and using the Aggregation API. The static +utility methods allow you to build queries and other kinds of documents +more efficiently. Why Use Builders? ----------------- @@ -46,10 +46,10 @@ the MongoDB shell or plain {+language+} instead, you write operators as strings and get no visual indication of a problem, which pushes these errors to runtime instead of compile time. -By using builder classes, you cab write operators as methods. The IDE -instantly indicates whether your code has errors. While developing, the -IDE also shows you the methods you can use and can complete your code with -placeholder parameters. +By using builder classes, you can write operators as methods, so that +your IDE instantly indicates whether your code has errors. While +developing, your IDE can also show you methods that you can use and can +complete your code with placeholder parameters. Example Scenario ---------------- @@ -60,8 +60,7 @@ collection that meet the following criteria: - Users in which the value of the ``gender`` field is ``"female"`` - Users in which the value of the ``age`` field is greater than ``29`` -You only want their email addresses, so your query won't -return data that you don't need. +You also need your query to return only their email addresses. The documents in the ``users`` collection are modeled by the following data class: @@ -88,6 +87,10 @@ builders in the {+driver-short+}: .. literalinclude:: /examples/generated/BuildersTest.snippet.no-builders.kt :language: kotlin +In this case, you could easily include an error when writing the +``"\$gt"`` operator in the filter, but you would see an error only at +runtime. + Using Builders ~~~~~~~~~~~~~~ diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index 8d39eba8..7f668291 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/fundamentals/builders/aggregates.txt @@ -54,13 +54,7 @@ modeled by the following ``Movie`` data class for use with the Kotlin driver: .. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.movie-data-class.kt :language: kotlin -.. tip:: Aggregates and Data Class Properties - - You can use methods from the ``Aggregates`` and - ``Accumulators`` classes directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst Match ----- diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt index 7c049f11..b8d29ef8 100644 --- a/source/fundamentals/builders/builders-data-classes.txt +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -77,10 +77,9 @@ dependency to your project by using the :guilabel:`Gradle` and After you install the extensions dependency, you can use the extension methods by importing classes and methods from the -``com.mongodb.kotlin.client.model`` path. You can access the standard -builder classes and methods from the ``com.mongodb.client.model`` path, -so you can mix calls that reference string field names and data -class properties in the same application. +``com.mongodb.kotlin.client.model`` path. You can mix usage of these methods and +the standard builder methods in the same application, as shown in the +:ref:`kotlin-data-class-aggregates` example in this guide. Builders Examples ----------------- diff --git a/source/fundamentals/builders/filters.txt b/source/fundamentals/builders/filters.txt index 185c08fe..a879fd4b 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/fundamentals/builders/filters.txt @@ -82,12 +82,7 @@ with the Kotlin driver: .. literalinclude:: /examples/generated/FiltersBuildersTest.snippet.paint-order-data-class.kt :language: kotlin -.. tip:: Filters and Data Class Properties - - You can use methods from the ``Filters`` class directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst .. _comparison: diff --git a/source/fundamentals/builders/indexes.txt b/source/fundamentals/builders/indexes.txt index 88f82a33..a3e05f82 100644 --- a/source/fundamentals/builders/indexes.txt +++ b/source/fundamentals/builders/indexes.txt @@ -45,12 +45,7 @@ instance, which you can pass to import com.mongodb.client.model.Indexes.* -.. tip:: Indexes and Data Class Properties - - You can use methods from the ``Indexes`` class directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst .. _ascending-indexes: diff --git a/source/fundamentals/builders/projections.txt b/source/fundamentals/builders/projections.txt index cb78a045..82316de6 100644 --- a/source/fundamentals/builders/projections.txt +++ b/source/fundamentals/builders/projections.txt @@ -95,12 +95,7 @@ The following data class is used to represent the documents in the collection: .. literalinclude:: /examples/generated/ProjectionsBuildersTest.snippet.example-data-class.kt :language: kotlin -.. tip:: Projections and Data Class Properties - - You can use methods from the ``Projections`` class directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst Projection Operations --------------------- diff --git a/source/fundamentals/builders/sort.txt b/source/fundamentals/builders/sort.txt index e3ee8329..6d9a41ec 100644 --- a/source/fundamentals/builders/sort.txt +++ b/source/fundamentals/builders/sort.txt @@ -53,12 +53,7 @@ This data is modeled with the following Kotlin data class: .. literalinclude:: /examples/generated/SortTest.snippet.sort-data-model.kt :language: kotlin -.. tip:: Sorts and Data Class Properties - - You can use methods from the ``Sorts`` class directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst The Sorts Class --------------- diff --git a/source/fundamentals/builders/updates.txt b/source/fundamentals/builders/updates.txt index 1dce3023..781aee45 100644 --- a/source/fundamentals/builders/updates.txt +++ b/source/fundamentals/builders/updates.txt @@ -1,3 +1,5 @@ +.. _updates-builders: + ================ Updates Builders ================ @@ -15,8 +17,6 @@ Updates Builders :depth: 2 :class: singlecol -.. _updates-builders: - Overview -------- @@ -68,12 +68,7 @@ This example is modeled by the following data class unless otherwise noted: .. literalinclude:: /examples/generated/UpdatesBuildersTest.snippet.example-data-class.kt :language: kotlin -.. tip:: Updates and Data Class Properties - - You can use methods from the ``Updates`` class directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst .. _field_updates: 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 8b3b6c3b..c20d3a77 100644 --- a/source/fundamentals/data-formats/document-data-format-data-class.txt +++ b/source/fundamentals/data-formats/document-data-format-data-class.txt @@ -60,12 +60,7 @@ as shown in the following code: DataStorage(productName=tape, capacity=5.0) -.. tip:: Builders for Data Class Properties - - You can use methods from builder classes directly with data class - properties by adding the optional {+driver-short+} extensions - dependency to your application. To learn more and view examples, see - the :ref:`kotlin-builders-data-classes` guide. +.. include:: /includes/fundamentals/builders-dataclass.rst You specify a class for documents returned from a collection, even if it is different than the class you specified when retrieving the diff --git a/source/includes/fundamentals/builders-dataclass.rst b/source/includes/fundamentals/builders-dataclass.rst new file mode 100644 index 00000000..2bf302f3 --- /dev/null +++ b/source/includes/fundamentals/builders-dataclass.rst @@ -0,0 +1,6 @@ +.. tip:: Builder Methods and Data Class Properties + + You can use the methods from builder classes directly with data + class properties by adding the optional {+driver-short+} extensions + dependency to your application. To learn more and view examples, see + the :ref:`kotlin-builders-data-classes` guide. diff --git a/source/whats-new.txt b/source/whats-new.txt index 5e7614c1..f211a5c6 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -34,7 +34,7 @@ improvements, and fixes: properties. To learn more, see the :ref:`kotlin-builders-data-classes` guide. This functionality is supported by the `{+driver-short+} Extensions package - <{+api}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ + <{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ published with this release. .. sharedinclude:: dbx/jvm/v5.3-wn-items.rst From 9311ba66f1a8ac889ce808d2b652c26ccd8dbf0e Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 09:59:51 -0500 Subject: [PATCH 13/18] add note to Kmongo page --- source/migrate-kmongo.txt | 69 +++++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 25 deletions(-) diff --git a/source/migrate-kmongo.txt b/source/migrate-kmongo.txt index 8b8938be..bfd23985 100644 --- a/source/migrate-kmongo.txt +++ b/source/migrate-kmongo.txt @@ -15,30 +15,31 @@ Overview -------- This page contains a high-level comparison of most of the ways the official -MongoDB Kotlin and the community-developed KMongo driver differ. +{+driver-long+} and the community-developed KMongo driver differ. You can use this page to identify the changes you need to make to migrate from -the deprecated KMongo driver to the official MongoDB Kotlin driver. +the deprecated KMongo driver to the official {+driver-long+}. .. include:: /includes/kmongo-description.rst -The MongoDB Kotlin driver is the officially supported and maintained MongoDB driver for -Kotlin. It is developed by the MongoDB team. +The {+driver-long+} is the officially supported and maintained MongoDB driver for +{+language+}. It is developed by the MongoDB team. -Although both drivers :ref:`support synchronous and asynchronous operations `, -the examples on this page will use asynchronous coroutine-based operations. +Although both drivers :ref:`support synchronous and asynchronous +operations `, the examples on this page will +use asynchronous coroutine-based operations. Connect to MongoDB Cluster -------------------------- Both drivers let you connect to and communicate with MongoDB clusters from a -Kotlin application. +{+language+} application. .. tabs:: .. tab:: :tabid: {+driver-long+} - To connect to a MongoDB cluster using the MongoDB Kotlin driver: + To connect to a MongoDB cluster using the {+driver-long+}: .. code-block:: kotlin @@ -77,7 +78,7 @@ Kotlin application. // Get a collection of documents of type Jedi val col = database.getCollection() - Unlike the MongoDB Kotlin driver, KMongo allows the collection name to be + Unlike the {+driver-long+}, KMongo allows the collection name to be inferred from the data class name. CRUD and Aggregation @@ -91,12 +92,12 @@ operations. .. tab:: :tabid: {+driver-long+} - The MongoDB Kotlin driver also provides functions for all basic CRUD operations: + The {+driver-long+} also provides functions for all basic CRUD operations: .. code-block:: kotlin // Insert a document - val jedi =a Jedi("Luke Skywalker", 19) + val jedi = Jedi("Luke Skywalker", 19) collection.insertOne(jedi) // Find a document @@ -168,6 +169,15 @@ operations. `Extensions Overview `__ KMongo documentation. +.. tip:: + + If you are accustomed to constructing query filters by using the + infix notation available in KMongo, you can also use this notation to + create filters in the official {+driver-short+} by using extension + methods from the ``mongodb-driver-kotlin-extensions`` package. To + learn more and view examples, see the + :ref:`kotlin-builders-data-classes` guide. + Construct Queries ----------------- @@ -178,7 +188,7 @@ Both drivers provide support for type-safe queries using property references. .. tab:: :tabid: {+driver-long+} - The MongoDB Kotlin driver uses the Builders API to construct queries. + The {+driver-long+} uses the Builders API to construct queries. Alternatively, you can use the ``Document`` class. .. code-block:: kotlin @@ -198,14 +208,14 @@ Both drivers provide support for type-safe queries using property references. val projection = Document().append("_id", 0).append("email", 1) val results = collection.find(filter).projection(projection) - To map a KMongo string query to the Kotlin driver, you can use the ``JsonObject`` class. + To map a KMongo string query to the {+driver-short+}, you can use the ``JsonObject`` class. .. code-block:: kotlin val query = JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}") val jsonResult = collection.find(query).firstOrNull() - For more information, see the following Kotlin driver documentation: + For more information, see the following {+driver-short+} documentation: - :ref:`Builders ` - :ref:`Documents ` guide @@ -250,10 +260,19 @@ Both drivers provide support for type-safe queries using property references. - `Typed Queries `_ - `Mongo Shell Queries `__ +.. tip:: + + If you are accustomed to constructing query filters by using the + infix notation available in KMongo, you can also use this notation to + create filters in the official {+driver-short+} by using extension + methods from the ``mongodb-driver-kotlin-extensions`` package. To + learn more and view examples, see the + :ref:`kotlin-builders-data-classes` guide. + Data Typing ----------- -Both drivers support the use of Kotlin data classes as well as the ``Document`` class to +Both drivers support the use of {+language+} data classes as well as the ``Document`` class to model the data stored in a MongoDB collection. The ``Document`` class lets you model data represented in a MongoDB collection in a flexible format. @@ -263,7 +282,7 @@ class lets you model data represented in a MongoDB collection in a flexible form :tabid: {+driver-long+} You can use data classes and ``Document`` classes to model data with the - MongoDB Kotlin driver: + {+driver-long+}: .. code-block:: kotlin @@ -302,17 +321,17 @@ Data Serialization ------------------ Both drivers provide support for serializing and deserializing data objects -in Kotlin to and from BSON. +in {+language+} to and from BSON. .. tabs:: .. tab:: :tabid: {+driver-long+} - You can serialize data classes in the Kotlin driver using both automatic + You can serialize data classes in the {+driver-short+} using both automatic data class codecs as well as the ``kotlinx.serialization`` library. The driver provides an efficient ``Bson`` serializer that handles the - serialization of Kotlin objects to BSON data. + serialization of {+language+} objects to BSON data. .. code-block:: kotlin @@ -326,7 +345,7 @@ in Kotlin to and from BSON. val manufacturer: String = "Acme" // Use instead of @BsonProperty ) - To learn more, see the :ref:`Kotlin Serialization ` + To learn more, see the :ref:`{+language+} Serialization ` documentation. If you use the ``Document`` class to represent your collection, you can @@ -381,9 +400,9 @@ Both drivers support synchronous and asynchronous operations. .. tab:: :tabid: {+driver-long+} - The MongoDB Kotlin driver also has separate libraries for synchronous and - asynchronous operations. However, the Kotlin driver only has built-in support - for coroutines as an asynchronous paradigm. The MongoDB Kotlin driver does not + The {+driver-long+} also has separate libraries for synchronous and + asynchronous operations. However, the {+driver-short+} only has built-in support + for coroutines as an asynchronous paradigm. The {+driver-long+} does not currently provide support for other asynchronous paradigms such as Reactive Streams, Reactor, or RxJava2. @@ -514,5 +533,5 @@ What Next? ---------- Now that you have learned about the differences between KMongo and the MongoDB -Kotlin driver, see the :ref:`Quick Start ` to get -started using the KMongo Kotlin driver. +{+driver-short+}, see the :ref:`Quick Start ` to get +started using the KMongo {+driver-short+}. From 050ac555144000595e9a43026cf7d892f924f809 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 13:22:01 -0500 Subject: [PATCH 14/18] vale fixes --- source/fundamentals/auth.txt | 2 +- source/fundamentals/builders.txt | 6 +++--- source/fundamentals/builders/aggregates.txt | 2 +- source/fundamentals/data-formats/documents.txt | 4 ++-- source/migrate-kmongo.txt | 9 +++++---- 5 files changed, 12 insertions(+), 11 deletions(-) diff --git a/source/fundamentals/auth.txt b/source/fundamentals/auth.txt index a2372f76..02c41cd9 100644 --- a/source/fundamentals/auth.txt +++ b/source/fundamentals/auth.txt @@ -501,5 +501,5 @@ mechanism: :language: kotlin For additional information on configuring your application to use -certificates as well as TLS/SSL options, see our +certificates and TLS/SSL options, see our :doc:`TLS/SSL guide `. diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index c41d982f..58a68f59 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -87,9 +87,9 @@ builders in the {+driver-short+}: .. literalinclude:: /examples/generated/BuildersTest.snippet.no-builders.kt :language: kotlin -In this case, you could easily include an error when writing the -``"\$gt"`` operator in the filter, but you would see an error only at -runtime. +In this case, you might easily include an error when writing the +``"\$gt"`` operator in the filter, but your IDE returns the relevant +error only at runtime. Using Builders ~~~~~~~~~~~~~~ diff --git a/source/fundamentals/builders/aggregates.txt b/source/fundamentals/builders/aggregates.txt index 7f668291..661b2fcc 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/fundamentals/builders/aggregates.txt @@ -532,7 +532,7 @@ to the ``name`` field: .. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.graph-lookup.kt :language: kotlin -Using ``GraphLookupOptions``, you can specify the depth to recurse as well as +Using ``GraphLookupOptions``, you can specify the depth to recurse and the name of the depth field, if desired. In this example, ``$graphLookup`` will recurse up to two times, and create a field called ``degrees`` with the recursion depth information for every document. diff --git a/source/fundamentals/data-formats/documents.txt b/source/fundamentals/data-formats/documents.txt index c19af974..339eb475 100644 --- a/source/fundamentals/data-formats/documents.txt +++ b/source/fundamentals/data-formats/documents.txt @@ -18,8 +18,8 @@ MongoDB Kotlin driver. A MongoDB document is a data structure that contains key/value fields in binary JSON (BSON) format. You can use documents and the data they contain -in their fields to store data as well as issue commands or queries in -MongoDB. +in their fields to store data, and you can use them to issue commands or +queries in MongoDB. For more information on the terminology, structure, and limitations of documents, read our page on :manual:`Documents ` in the MongoDB manual. diff --git a/source/migrate-kmongo.txt b/source/migrate-kmongo.txt index bfd23985..c0ffe76a 100644 --- a/source/migrate-kmongo.txt +++ b/source/migrate-kmongo.txt @@ -272,9 +272,10 @@ Both drivers provide support for type-safe queries using property references. Data Typing ----------- -Both drivers support the use of {+language+} data classes as well as the ``Document`` class to -model the data stored in a MongoDB collection. The ``Document`` -class lets you model data represented in a MongoDB collection in a flexible format. +Both drivers support the use of {+language+} data classes and the +``Document`` class to model the data stored in a MongoDB collection. The +``Document`` class lets you model data represented in a MongoDB +collection in a flexible format. .. tabs:: @@ -329,7 +330,7 @@ in {+language+} to and from BSON. :tabid: {+driver-long+} You can serialize data classes in the {+driver-short+} using both automatic - data class codecs as well as the ``kotlinx.serialization`` library. The + data class codecs and the ``kotlinx.serialization`` library. The driver provides an efficient ``Bson`` serializer that handles the serialization of {+language+} objects to BSON data. From 82b8d6749f52e63828a7094af377bcd5c32f2239 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 24 Jan 2025 10:50:40 -0500 Subject: [PATCH 15/18] NH tech review 2 --- ...ssTest.snippet.filters-query-data-class.kt | 7 - source/faq.txt | 37 ++--- .../builders/builders-data-classes.txt | 5 + source/index.txt | 6 +- source/migrate-kmongo.txt | 150 +++++++++++++----- 5 files changed, 121 insertions(+), 84 deletions(-) delete mode 100644 source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt diff --git a/source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt b/source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt deleted file mode 100644 index f44390a4..00000000 --- a/source/examples/generated/DataClassTest.snippet.filters-query-data-class.kt +++ /dev/null @@ -1,7 +0,0 @@ -val record = DataStorage("SSD", 120.0) -// Infixed query -DataStorage::productName.eq(record.productName) -// Nested query -val bson = eq(DataStorage::productName, record.productName) -// Kmongo DSL -val filter = DataStorage::productName eq record.productName diff --git a/source/faq.txt b/source/faq.txt index c42bd04d..6443300f 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -31,56 +31,37 @@ If you have trouble connecting to a MongoDB deployment, see the :ref:`Connection Troubleshooting Guide ` for possible solutions. -How is the Kotlin Driver Different from KMongo? +How is the {+language+} Driver Different from KMongo? ----------------------------------------------- -The Kotlin driver is the official MongoDB driver for Kotlin. It is -developed by the MongoDB team and provides a native API for Kotlin +The {+driver-short+} is the official MongoDB driver for {+language+}. It is +developed by the MongoDB team and provides a native API for {+language+} applications to connect to MongoDB and work with data. It is implemented by wrapping the :driver:`MongoDB Java driver `. .. include:: /includes/kmongo-description.rst -The Kotlin driver was developed in collaboration with the creator of KMongo, +The {+driver-short+} was developed in collaboration with the creator of KMongo, Julien Buret, to give users an officially-supported driver. -The official Kotlin driver and KMongo have generally similar APIs. -Notable similarities between the Kotlin driver and KMongo include: +The official {+driver-short+} and KMongo have generally similar APIs. +Notable similarities between the {+driver-short+} and KMongo include: - Support for synchronous and coroutine-based operations - Support using data classes to represent MongoDB documents -- Support KotlinX serialization -- Support for MongoDB CRUD APIs and aggregation +- Support for KotlinX serialization +- Support for MongoDB CRUD API and aggregation API -Although the official Kotlin driver and KMongo are similar, there are some +Although the official {+driver-short+} and KMongo are similar, there are some key differences: - The official driver does *not* have built-in support for `reactor `__, `rxjava2 `__, `Jackson `__, or `GSON `__. - The official driver does *not* support MongoDB shell commands. -- The official driver supports type-safe queries with the Builders API, - whereas KMongo uses infix functions and property references for - type-safe queries. For more detailed information, see :ref:`Migrate from KMongo `. -What is the Difference Between the Kotlin Driver and the Kotlin SDK? --------------------------------------------------------------------- - -MongoDB supports both mobile and server-side development in Kotlin. If -you are developing a mobile application for Android or Kotlin -Multiplatform (KMP), you can use the :realm:`MongoDB -Atlas Device Kotlin SDK ` to access Atlas App Services and -to manage your Realm data. - -The {+driver-short+} supports server-side development by providing a -complete library for building idiomatic Kotlin applications. You can -learn how to develop asynchronous applications in this documentation for -the Kotlin Coroutine Driver, or you can view the :driver:`Kotlin Sync -Driver documentation ` to learn more about synchronous -programming. - .. _kotlin-faq-connection-pool: How Does Connection Pooling Work in the Kotlin Driver? diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt index b8d29ef8..e5019c4d 100644 --- a/source/fundamentals/builders/builders-data-classes.txt +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -129,6 +129,11 @@ methods to perform queries on the ``Student`` data class: .. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt :language: kotlin +The preceding example includes a query written in **infix notation**, To +learn more about this notation, see `Infix notation +<{+kotlin-docs+}/docs/functions.html#infix-notation>`__ in the +{+language+} reference documentation. + .. _kotlin-data-class-indexes: Indexes diff --git a/source/index.txt b/source/index.txt index 84084892..745dde13 100644 --- a/source/index.txt +++ b/source/index.txt @@ -29,15 +29,11 @@ Download the driver by using `Maven `__ or `Gradle `__, or set up a runnable project by following our Quick Start guide. -.. tip:: Other Kotlin Platforms for MongoDB +.. tip:: {+language+} Sync Driver If your Kotlin application requires synchronous processing, use the :driver:`Sync Driver `, which uses synchronous operations to make blocking calls to MongoDB. - - If you are developing an Android or Kotlin Multiplatform (KMP) - application, you can use the :realm:`MongoDB Atlas Device Kotlin SDK ` - to access Atlas App Services and to manage your Realm data. Quick Start ----------- diff --git a/source/migrate-kmongo.txt b/source/migrate-kmongo.txt index c0ffe76a..3a271382 100644 --- a/source/migrate-kmongo.txt +++ b/source/migrate-kmongo.txt @@ -4,6 +4,14 @@ Migrate from KMongo =================== +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :description: Learn how to migrate your application from KMongo to the official MongoDB Kotlin driver. + :keywords: code example, adapt, syntax + .. contents:: On this page :local: :backlinks: none @@ -45,7 +53,7 @@ Both drivers let you connect to and communicate with MongoDB clusters from a import com.mongodb.kotlin.client.coroutine.MongoClient - data class Jedi(val name: String, val age: Int) + data class Jedi(val name: String, val age: Int) // Replace the placeholder with your MongoDB deployment's connection string val uri = CONNECTION_STRING_URI_PLACEHOLDER @@ -87,6 +95,15 @@ CRUD and Aggregation Both drivers provide support for all MongoDB CRUD APIs and aggregation operations. +.. tip:: + + If you are accustomed to constructing query filters by using the + infix notation available in KMongo, you can also use this notation to + create filters in the official {+driver-short+} by using extension + methods from the ``mongodb-driver-kotlin-extensions`` package. Select + the :guilabel:`Kotlin Driver Extensions` tab to view an example that + uses this query syntax in the {+driver-short+}. + .. tabs:: .. tab:: @@ -96,42 +113,71 @@ operations. .. code-block:: kotlin - // Insert a document - val jedi = Jedi("Luke Skywalker", 19) - collection.insertOne(jedi) + // Insert a document + val jedi = Jedi("Luke Skywalker", 19) + collection.insertOne(jedi) - // Find a document - val luke = collection.find(Jedi::name.name, "Luke Skywalker") - val jedis = collection.find(lt(Jedi::age.name, 30)).toList() + // Find a document + val luke = collection.find(Jedi::name.name, "Luke Skywalker") + val jedis = collection.find(lt(Jedi::age.name, 30)).toList() - // Update a document - val filter = Filters.eq(Jedi::name.name, "Luke Skywalker") - val update = Updates.set(Jedi::age.name, 20) - collection.updateOne(filter, update) + // Update a document + val filter = Filters.eq(Jedi::name.name, "Luke Skywalker") + val update = Updates.set(Jedi::age.name, 20) + collection.updateOne(filter, update) - // Delete a document - val filter = Filters.eq(Jedi::name.name, "Luke Skywalker") - collection.deleteOne(filter) + // Delete a document + val filter = Filters.eq(Jedi::name.name, "Luke Skywalker") + collection.deleteOne(filter) - Aggregation pipelines can be built using the ``aggregate`` method and the - ``pipeline`` function: + You can build aggregation pipelines by using the ``aggregate()`` + method and the ``pipeline`` function: .. code-block:: kotlin - data class Results(val avgAge: Double) + data class Results(val avgAge: Double) - val resultsFlow = collection.aggregate( - listOf( - Aggregates.match(Filters.ne(Jedi::name.name, "Luke Skywalker")), - Aggregates.group("\$${Jedi::name.name}", - Accumulators.avg("avgAge", "\$${Jedi::age.name}")) - ) - ) - resultsFlow.collect { println(it) } + val resultsFlow = collection.aggregate( + listOf( + Aggregates.match(Filters.ne(Jedi::name.name, "Luke Skywalker")), + Aggregates.group("\$${Jedi::name.name}", + Accumulators.avg("avgAge", "\$${Jedi::age.name}")) + ) + ) + resultsFlow.collect { println(it) } See the :ref:`CRUD Operations ` and :ref:`Aggregation ` documentation for more information. - + + .. tab:: + :tabid: Kotlin Driver Extensions + + You can use the Builders API from the + ``mongodb-driver-kotlin-extensions`` library to create query + filters and aggregation pipeline stages directly using data class + properties. This library also allows you to create queries by + using infix notation: + + .. code-block:: kotlin + + data class Jedi(val name: String, val age: Int) + + // Find documents + val luke = collection.find(Jedi::name eq "Luke Skywalker") + val jedis = collection.find(Jedi::age lt 30)).toList() + + // Update a document + val filter = Jedi::name eq "Luke Skywalker" + val update = Jedi::age.name set 20 + collection.updateOne(filter, update) + + // Delete a document + val filter = Jedi::name eq "Luke Skywalker" + collection.deleteOne(filter) + + To learn more and view examples that use all of the builder + classes, see the :ref:`kotlin-builders-data-classes` guide. + .. tab:: :tabid: KMongo @@ -169,19 +215,19 @@ operations. `Extensions Overview `__ KMongo documentation. +Construct Queries +----------------- + +Both drivers provide support for type-safe queries using property references. + .. tip:: If you are accustomed to constructing query filters by using the infix notation available in KMongo, you can also use this notation to create filters in the official {+driver-short+} by using extension - methods from the ``mongodb-driver-kotlin-extensions`` package. To - learn more and view examples, see the - :ref:`kotlin-builders-data-classes` guide. - -Construct Queries ------------------ - -Both drivers provide support for type-safe queries using property references. + methods from the ``mongodb-driver-kotlin-extensions`` package. Select + the :guilabel:`Kotlin Driver Extensions` tab to view an example that + uses this query syntax in the {+driver-short+}. .. tabs:: @@ -220,7 +266,32 @@ Both drivers provide support for type-safe queries using property references. - :ref:`Builders ` - :ref:`Documents ` guide - `JsonObject <{+api+}/apidocs/bson/org/bson/json/JsonObject.html>`__ API Documentation - + + .. tab:: + :tabid: Kotlin Driver Extensions + + You can use the Builders API from the + ``mongodb-driver-kotlin-extensions`` library to construct queries + directly on data class properties. This library also allows you to + create queries by using infix notation: + + .. code-block:: kotlin + + data class Person(val name: String, val gender: String, val age: Int) + data class Result(val name: String) + + val collection = database.getCollection("people") + + // Infix Notation Query + val filter = (Person::gender eq "female") and (Person::age gt 29)) + val projection = fields(excludeId(), include(Person::name)) + + val results = collection.find(filter).projection(projection) + + + To learn more and view examples that use all of the builder + classes, see the :ref:`kotlin-builders-data-classes` guide. + .. tab:: :tabid: KMongo @@ -260,15 +331,6 @@ Both drivers provide support for type-safe queries using property references. - `Typed Queries `_ - `Mongo Shell Queries `__ -.. tip:: - - If you are accustomed to constructing query filters by using the - infix notation available in KMongo, you can also use this notation to - create filters in the official {+driver-short+} by using extension - methods from the ``mongodb-driver-kotlin-extensions`` package. To - learn more and view examples, see the - :ref:`kotlin-builders-data-classes` guide. - Data Typing ----------- From 6fef9d5de5f23884a4b46160857c4f7c21a2f2e3 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 24 Jan 2025 10:56:02 -0500 Subject: [PATCH 16/18] wip --- .../fundamentals/builders/builders-data-classes.txt | 11 ++++++----- source/whats-new.txt | 13 ++++++------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt index e5019c4d..2c4879dd 100644 --- a/source/fundamentals/builders/builders-data-classes.txt +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -30,6 +30,12 @@ string field names. You can structure your code in this way to make your code more type-safe and improve your applications {+language+} interoperability. +The extensions library also allows you to construct +queries, update documents, and other statements by using infix notation. +To learn more about this notation, see `Infix notation +<{+kotlin-docs+}/docs/functions.html#infix-notation>`__ in the +{+language+} reference documentation. + .. note:: This page provides a limited number of code @@ -129,11 +135,6 @@ methods to perform queries on the ``Student`` data class: .. literalinclude:: /examples/generated/BuildersDataClassTest.snippet.filters-data-class.kt :language: kotlin -The preceding example includes a query written in **infix notation**, To -learn more about this notation, see `Infix notation -<{+kotlin-docs+}/docs/functions.html#infix-notation>`__ in the -{+language+} reference documentation. - .. _kotlin-data-class-indexes: Indexes diff --git a/source/whats-new.txt b/source/whats-new.txt index 87478763..94c617ac 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -30,13 +30,6 @@ What's New in 5.3 The 5.3 driver release includes the following new features, improvements, and fixes: -- Support for using builders class methods directly with data class - properties. To learn more, see the :ref:`kotlin-builders-data-classes` - guide. This functionality is supported by the `{+driver-short+} - Extensions package - <{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ - published with this release. - .. sharedinclude:: dbx/jvm/v5.3-wn-items.rst .. replacement:: vector-type-example-link @@ -50,6 +43,12 @@ improvements, and fixes: the :ref:`kotlin-fundamentals-change-document` and :ref:`kotlin-fundamentals-bulkwrite` guides +- Support for using builders class methods directly with data class + properties. To learn more, see the :ref:`kotlin-builders-data-classes` + guide. This functionality is supported by the `{+driver-short+} + Extensions package <{+api+}/apidocs/mongodb-driver-kotlin-extensions/index.html>`__ + published with this release. + - Implements a *client* bulk write API that allows you to perform write operations on multiple databases and collections in the same call. To learn more about this feature, see the :ref:`kotlin-client-bulk-write` From 19278b981975e7af2cc476c3df2e61864165d72f Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 24 Jan 2025 11:01:42 -0500 Subject: [PATCH 17/18] wip --- source/migrate-kmongo.txt | 60 +++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/source/migrate-kmongo.txt b/source/migrate-kmongo.txt index 3a271382..6b5e59f1 100644 --- a/source/migrate-kmongo.txt +++ b/source/migrate-kmongo.txt @@ -159,6 +159,10 @@ operations. using infix notation: .. code-block:: kotlin + + import com.mongodb.kotlin.client.model.Filters.eq + import com.mongodb.kotlin.client.model.Filters.lt + import com.mongodb.kotlin.client.model.Updates.set data class Jedi(val name: String, val age: Int) @@ -239,20 +243,20 @@ Both drivers provide support for type-safe queries using property references. .. code-block:: kotlin - data class Person(val name: String, val email: String, val gender: String, val age: Int) - data class Results(val email: String) - - val collection = database.getCollection("people") - - // Using Builders - val filter = and(eq("gender", "female"), gt("age", 29)) - val projection = fields(excludeId(), include("email")) - val results = collection.find(filter).projection(projection) - - // Using Document class - val filter = Document().append("gender", "female").append("age", Document().append("\$gt", 29)) - val projection = Document().append("_id", 0).append("email", 1) - val results = collection.find(filter).projection(projection) + data class Person(val name: String, val email: String, val gender: String, val age: Int) + data class Results(val email: String) + + val collection = database.getCollection("people") + + // Using Builders + val filter = and(eq("gender", "female"), gt("age", 29)) + val projection = fields(excludeId(), include("email")) + val results = collection.find(filter).projection(projection) + + // Using Document class + val filter = Document().append("gender", "female").append("age", Document().append("\$gt", 29)) + val projection = Document().append("_id", 0).append("email", 1) + val results = collection.find(filter).projection(projection) To map a KMongo string query to the {+driver-short+}, you can use the ``JsonObject`` class. @@ -277,17 +281,23 @@ Both drivers provide support for type-safe queries using property references. .. code-block:: kotlin - data class Person(val name: String, val gender: String, val age: Int) - data class Result(val name: String) + import com.mongodb.kotlin.client.model.Filters.eq + import com.mongodb.kotlin.client.model.Filters.and + import com.mongodb.kotlin.client.model.Filters.gt + import com.mongodb.kotlin.client.model.Projections.excludeId + import com.mongodb.kotlin.client.model.Projections.fields + import com.mongodb.kotlin.client.model.Projections.include - val collection = database.getCollection("people") + data class Person(val name: String, val gender: String, val age: Int) + data class Result(val name: String) - // Infix Notation Query - val filter = (Person::gender eq "female") and (Person::age gt 29)) - val projection = fields(excludeId(), include(Person::name)) - - val results = collection.find(filter).projection(projection) - + val collection = database.getCollection("people") + + // Infix Notation Query + val filter = (Person::gender eq "female") and (Person::age gt 29)) + val projection = fields(excludeId(), include(Person::name)) + + val results = collection.find(filter).projection(projection) To learn more and view examples that use all of the builder classes, see the :ref:`kotlin-builders-data-classes` guide. @@ -500,7 +510,7 @@ Both drivers support synchronous and asynchronous operations. val collection = database.getCollection("jedi") // Synchronous operations - val jedi =a Jedi("Luke Skywalker", 19) + val jedi = Jedi("Luke Skywalker", 19) collection.insertOne(jedi) To write asynchronous coroutine code: @@ -519,7 +529,7 @@ Both drivers support synchronous and asynchronous operations. runBlocking { // Async operations - val jedi =a Jedi("Luke Skywalker", 19) + val jedi = Jedi("Luke Skywalker", 19) collection.insertOne(jedi) } From 11d46864a98ac2a28655ad48321ccc40e92a973d Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 24 Jan 2025 11:06:01 -0500 Subject: [PATCH 18/18] wip --- source/fundamentals/builders/builders-data-classes.txt | 4 ++-- source/migrate-kmongo.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/builders/builders-data-classes.txt b/source/fundamentals/builders/builders-data-classes.txt index 2c4879dd..592b9a6c 100644 --- a/source/fundamentals/builders/builders-data-classes.txt +++ b/source/fundamentals/builders/builders-data-classes.txt @@ -31,8 +31,8 @@ code more type-safe and improve your applications {+language+} interoperability. The extensions library also allows you to construct -queries, update documents, and other statements by using infix notation. -To learn more about this notation, see `Infix notation +queries, update documents, and write other statements by using infix +notation. To learn more about this notation, see `Infix notation <{+kotlin-docs+}/docs/functions.html#infix-notation>`__ in the {+language+} reference documentation. diff --git a/source/migrate-kmongo.txt b/source/migrate-kmongo.txt index 6b5e59f1..fbf1f252 100644 --- a/source/migrate-kmongo.txt +++ b/source/migrate-kmongo.txt @@ -179,7 +179,7 @@ operations. val filter = Jedi::name eq "Luke Skywalker" collection.deleteOne(filter) - To learn more and view examples that use all of the builder + To learn more and view examples that use all the builder classes, see the :ref:`kotlin-builders-data-classes` guide. .. tab:: @@ -299,7 +299,7 @@ Both drivers provide support for type-safe queries using property references. val results = collection.find(filter).projection(projection) - To learn more and view examples that use all of the builder + To learn more and view examples that use all the builder classes, see the :ref:`kotlin-builders-data-classes` guide. .. tab::