From 82ee59608ec513efc3d082638975e746c7acb70c Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 16:28:06 -0400 Subject: [PATCH 1/7] add find one --- source/crud/query/find.txt | 30 ++++++++++++++++++++++++++++++ source/includes/read/retrieve.kt | 9 +++++++++ 2 files changed, 39 insertions(+) diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index e51ae9b5..19e0bf53 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -53,6 +53,36 @@ collection. To learn more about query filters, see the :ref:`kotlin-sync-specify-query` guide. +Find One Document Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example chains the ``first()`` method to the ``find()`` method call to find +the first document in which the value of the ``cuisine`` field is ``"Spanish"``: + +.. literalinclude:: /includes/read/retrieve.kt + :start-after: start-find-one + :end-before: end-find-one + :language: kotlin + :copyable: + :dedent: + +The ``find()`` operation in the preceding example returns a MongoDB document +which you can print, as shown in the following example: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/read/retrieve.kt + :start-after: start-find-iterate + :end-before: end-find-iterate + :language: kotlin + :dedent: + + .. output:: + :visible: false + + Restaurant(name=Tropicoso Club, cuisine=Spanish) + Find Documents Example ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/read/retrieve.kt b/source/includes/read/retrieve.kt index 6a9df06c..8e5f52e6 100644 --- a/source/includes/read/retrieve.kt +++ b/source/includes/read/retrieve.kt @@ -26,6 +26,10 @@ fun main() { val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")) // end-find + // start-find-one + val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")).firstOrNull() + // end-find-one + // start-find-iterate val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")) results.forEach { result -> @@ -33,6 +37,11 @@ fun main() { } // end-find-iterate + // start-find-one-print + val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")) + println(results) + // end-find-one-print + // start-find-all val results = collection.find() // end-find-all From 7ce6b081796b9e4a4c94df1bbfd5dca8ab98f0e3 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 17:20:52 -0400 Subject: [PATCH 2/7] fix code --- source/crud/query/find.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index 19e0bf53..6f89f3ea 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -73,8 +73,8 @@ which you can print, as shown in the following example: :copyable: true .. input:: /includes/read/retrieve.kt - :start-after: start-find-iterate - :end-before: end-find-iterate + :start-after: start-find-one-print + :end-before: end-find-one-print :language: kotlin :dedent: From 197e237fbfae820d2bdf5c5b9aed3e31c185dce6 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 17:21:33 -0400 Subject: [PATCH 3/7] edit code --- source/includes/read/retrieve.kt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/read/retrieve.kt b/source/includes/read/retrieve.kt index 8e5f52e6..e7774ae2 100644 --- a/source/includes/read/retrieve.kt +++ b/source/includes/read/retrieve.kt @@ -27,7 +27,7 @@ fun main() { // end-find // start-find-one - val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")).firstOrNull() + val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")).first() // end-find-one // start-find-iterate @@ -38,7 +38,7 @@ fun main() { // end-find-iterate // start-find-one-print - val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")) + val results = collection.find(eq(Restaurant::cuisine.name, "Spanish")).first() println(results) // end-find-one-print From 9d765ad5e7291ea23cae244862e1aae15fb1a125 Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 10 Jul 2025 10:47:30 -0400 Subject: [PATCH 4/7] add table entries --- source/crud/query/find.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index 6f89f3ea..e46e61ba 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -154,6 +154,13 @@ modifying queries: - | Specifies a string to attach to the query. This can help you trace and interpret the operation in the server logs and in profile data. + * - ``first()`` + - | Returns the first document that matches the query or throws a MongoClientException + if no matching documents exist. + + * - ``firstOrNull()`` + - | Returns the first document that matches the query or null if no matching documents exist. + * - ``hint()`` - | Specifies the index to use for the query. From 46bd0d948d1218cb3df6561ab5821460baca5ea5 Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 10 Jul 2025 10:58:47 -0400 Subject: [PATCH 5/7] formatting --- source/crud/query/find.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index e46e61ba..14fbf07d 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -155,7 +155,7 @@ modifying queries: operation in the server logs and in profile data. * - ``first()`` - - | Returns the first document that matches the query or throws a MongoClientException + - | Returns the first document that matches the query or throws a ``MongoClientException`` if no matching documents exist. * - ``firstOrNull()`` From 4c208b637938e0f24fb5c234226ada9c8268c9bc Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 10 Jul 2025 10:59:14 -0400 Subject: [PATCH 6/7] monospace --- source/crud/query/find.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index 14fbf07d..928a8a0e 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -159,7 +159,7 @@ modifying queries: if no matching documents exist. * - ``firstOrNull()`` - - | Returns the first document that matches the query or null if no matching documents exist. + - | Returns the first document that matches the query or ``null`` if no matching documents exist. * - ``hint()`` - | Specifies the index to use for the query. From f3a42909df836822085fd34b5e783b6a448b403f Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 10 Jul 2025 13:36:09 -0400 Subject: [PATCH 7/7] mw feedback --- source/crud/query/find.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index 928a8a0e..32f2ada3 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -66,8 +66,8 @@ the first document in which the value of the ``cuisine`` field is ``"Spanish"``: :copyable: :dedent: -The ``find()`` operation in the preceding example returns a MongoDB document -which you can print, as shown in the following example: +The ``find()`` operation in the preceding example returns a MongoDB document, which you +can print, as shown in the following example: .. io-code-block:: :copyable: true