From 9311ba66f1a8ac889ce808d2b652c26ccd8dbf0e Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 09:59:51 -0500 Subject: [PATCH] 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+}.