Skip to content

Commit

Permalink
add note to Kmongo page
Browse files Browse the repository at this point in the history
  • Loading branch information
rustagir committed Jan 15, 2025
1 parent c8a2c9c commit 9311ba6
Showing 1 changed file with 44 additions and 25 deletions.
69 changes: 44 additions & 25 deletions source/migrate-kmongo.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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 <kotlin-sync-async-support>`,
the examples on this page will use asynchronous coroutine-based operations.
Although both drivers :ref:`support synchronous and asynchronous
operations <kotlin-sync-async-support>`, 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

Expand Down Expand Up @@ -77,7 +78,7 @@ Kotlin application.
// Get a collection of documents of type Jedi
val col = database.getCollection<Jedi>()

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
Expand All @@ -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
Expand Down Expand Up @@ -168,6 +169,15 @@ operations.
`Extensions Overview <https://litote.org/kmongo/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
-----------------

Expand All @@ -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
Expand All @@ -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<Results>(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 <kotlin-builders-landing>`
- :ref:`Documents <kotlin-document-format>` guide
Expand Down Expand Up @@ -250,10 +260,19 @@ Both drivers provide support for type-safe queries using property references.
- `Typed Queries <https://litote.org/kmongo/typed-queries/>`_
- `Mongo Shell Queries <https://litote.org/kmongo/mongo-shell-support/>`__

.. 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

Check failure on line 275 in source/migrate-kmongo.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules

[vale] reported by reviewdog 🐶 [MongoDB.ConciseTerms] 'and' is preferred over 'as well as'. Raw Output: {"message": "[MongoDB.ConciseTerms] 'and' is preferred over 'as well as'.", "location": {"path": "source/migrate-kmongo.txt", "range": {"start": {"line": 275, "column": 59}}}, "severity": "ERROR"}
model the data stored in a MongoDB collection. The ``Document``
class lets you model data represented in a MongoDB collection in a flexible format.

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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 <fundamentals-kotlin-serialization>`
To learn more, see the :ref:`{+language+} Serialization <fundamentals-kotlin-serialization>`
documentation.

If you use the ``Document`` class to represent your collection, you can
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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 <kotlin-quickstart>` to get
started using the KMongo Kotlin driver.
{+driver-short+}, see the :ref:`Quick Start <kotlin-quickstart>` to get
started using the KMongo {+driver-short+}.

0 comments on commit 9311ba6

Please sign in to comment.