From 4104261f71cfcb5568781675702c34c6d8ee6d8f Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 22 Jul 2024 17:23:55 -0400 Subject: [PATCH 1/4] DOCSP-41128: delete docs --- snooty.toml | 3 +- source/includes/write/delete.kt | 35 ++++++ source/write-operations.txt | 28 ++--- source/write/delete.txt | 198 ++++++++++++++++++++++++++++++++ 4 files changed, 250 insertions(+), 14 deletions(-) create mode 100644 source/includes/write/delete.kt create mode 100644 source/write/delete.txt diff --git a/snooty.toml b/snooty.toml index 7f974e8..a3b8f5f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -23,4 +23,5 @@ version = "v{+version-number+}" patch-version-number = "{+version-number+}.0" mdb-server = "MongoDB Server" stable-api = "Stable API" -api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" \ No newline at end of file +api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" +core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/" diff --git a/source/includes/write/delete.kt b/source/includes/write/delete.kt new file mode 100644 index 0000000..1624151 --- /dev/null +++ b/source/includes/write/delete.kt @@ -0,0 +1,35 @@ +import com.mongodb.client.model.DeleteOptions +import com.mongodb.client.model.Filters.* +import com.mongodb.kotlin.client.MongoClient + +// start-data-class +data class Restaurant(val name: String, val borough: String) +// end-data-class + +fun main() { + val uri = "" + + val mongoClient = MongoClient.create(uri) + val database = mongoClient.getDatabase("sample_restaurants") + val collection = database.getCollection("restaurants") + + // start-delete-one + val filter = eq(Restaurant::name.name, "Happy Garden") + val result = collection.deleteOne(filter) + // end-delete-one + + // start-delete-many + val filter = and( + eq(Restaurant::name.name, "Happy Garden"), + eq(Restaurant::name.name, "Starbucks") + ) + val result = collection.deleteMany(filter) + // end-delete-many + + // start-delete-options + val opts = DeleteOptions().comment("sample comment") + val filter = regex(Restaurant::name.name, "Red") + val result = collection.deleteOne(filter, opts) + // end-delete-options + +} \ No newline at end of file diff --git a/source/write-operations.txt b/source/write-operations.txt index 42d7e68..d87bc4d 100644 --- a/source/write-operations.txt +++ b/source/write-operations.txt @@ -18,16 +18,18 @@ Write Data to MongoDB :description: Learn how to use the Kotlin Sync driver to write data to MongoDB. :keywords: usage examples, save, crud, create, code example -.. .. toctree:: -.. :titlesonly: -.. :maxdepth: 1 +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /write/delete + .. -.. /write/insert -.. /write/update -.. /write/replace -.. /write/delete -.. /write/bulk-write -.. /write/gridfs + /write/insert + /write/update + /write/replace + /write/bulk-write + /write/gridfs Overview -------- @@ -149,8 +151,8 @@ collection: :copyable: :dedent: -.. To learn more about the ``delete_one()`` method, see the -.. :ref:`Delete Documents ` guide. +To learn more about the ``deleteOne()`` method, see the +:ref:`Delete Documents ` guide. Delete Multiple --------------- @@ -165,8 +167,8 @@ collection: :copyable: :dedent: -.. To learn more about the ``delete_many()`` method, see the -.. :ref:`Delete Documents ` guide. +To learn more about the ``deleteMany()`` method, see the +:ref:`Delete Documents ` guide. Bulk Write ---------- diff --git a/source/write/delete.txt b/source/write/delete.txt new file mode 100644 index 0000000..9f5af4f --- /dev/null +++ b/source/write/delete.txt @@ -0,0 +1,198 @@ +.. _kotlin-sync-write-delete: + +================ +Delete Documents +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: remove, drop, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to remove +documents from a MongoDB collection by performing **delete operations**. + +A delete operation removes one or more documents from a MongoDB collection. +You can perform a delete operation by using the ``delete_one()`` or +``delete_many()`` methods. + +.. TODO .. tip:: Interactive Lab + +.. This page includes a short interactive lab that demonstrates how to +.. modify data by using the ``deleteMany()`` method. You can complete this +.. lab directly in your browser window without installing MongoDB or a code editor. + +.. To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the +.. top of the page. To expand the lab to a full-screen format, click the +.. full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``sample_restaurants.restaurants`` collection +from the :atlas:`Atlas sample datasets `. + +.. TODO To learn how to create a +.. free MongoDB Atlas cluster and load the sample datasets, see the +.. :ref:`` tutorial. + +The documents in this collection are modeled by the following {+language+} data class: + +.. literalinclude:: /includes/write/delete.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + +Delete Operations +----------------- + +You can perform delete operations in MongoDB by using the following methods: + +- ``deleteOne()``, which deletes *the first document* that matches the search criteria +- ``deleteMany()``, which deletes *all documents* that match the search criteria + +Each delete method requires a **query filter** document, which specifies the +search criteria that determine which documents to select for removal. +For more information about query filters, see the +:manual:`Query Filter Documents section ` in +the {+mdb-server+} manual. + +Delete One Document +~~~~~~~~~~~~~~~~~~~ + +The following example uses the ``deleteOne()`` method to remove a +document in which the value of the ``name`` field is ``"Happy Garden"``: + +.. literalinclude:: /includes/write/delete.kt + :start-after: start-delete-one + :end-before: end-delete-one + :language: kotlin + :copyable: + +Delete Multiple Documents +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example uses the ``deleteMany()`` method to remove all documents +in which the value of the ``borough`` field is ``"Brooklyn"`` and the +value of the ``name`` field is ``"Starbucks"``: + +.. literalinclude:: /includes/write/delete.kt + :start-after: start-delete-many + :end-before: end-delete-many + :language: kotlin + :copyable: + +Customize the Delete Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``deleteOne()`` and ``deleteMany()`` methods optionally accept a +``DeleteOptions`` parameter, which represents options you can use to +configure the delete operation. If you don't specify any additional +options, the driver performs the delete operation with default settings. + +The following table describes the setter methods that you can use to +configure a ``DeleteOptions`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Property + - Description + + * - ``collation()`` + - | Specifies the kind of language collation to use when sorting + results. For more information, see :manual:`Collation ` + in the {+mdb-server+} manual. + + * - ``hint()`` + - | Specifies the index to use when matching documents. + For more information, see the :manual:`hint statement ` + in the {+mdb-server+} manual. + + * - ``hintString()`` + - | Specifies the index as a string to use when matching documents. + For more information, see the :manual:`hint statement ` + in the {+mdb-server+} manual. + + * - ``let()`` + - | Provides a map of parameter names and values to set top-level + variables for the operation. Values must be constant or closed + expressions that don't reference document fields. For more information, + see the :manual:`let statement + ` in the + {+mdb-server+} manual. + + * - ``comment()`` + - | Sets a comment to attach to the operation. For more + information, see the :manual:`delete command + fields ` guide in the + {+mdb-server+} manual for more information. + +The following code uses the ``deleteMany()`` method to delete all +documents in the ``restaurants`` collection in which the value of the +``name`` field includes the string ``"Red"``. The example also uses the +``comment()`` method to add a comment to the operation and passes the +resulting ``DeleteOptions`` instance to the ``deleteMany()`` method: + +.. literalinclude:: /includes/write/delete.kt + :start-after: start-delete-options + :end-before: end-delete-options + :language: kotlin + :copyable: + +.. tip:: + + If the preceding example used the ``deleteOne()`` method instead of + the ``deleteMany()`` method, the driver would delete only the first + document that matched the query filter. + +Return Value +~~~~~~~~~~~~ + +The ``deleteOne()`` and ``deleteMany()`` methods each return a +``DeleteResult`` instance. You can access the following information from +a ``DeleteResult`` instance: + +- ``deletedCount``, which indicates the number of documents deleted +- ``wasAcknowledged()``, which returns ``true`` if the server + acknowledges the result + +.. note:: + + If the ``wasAcknowledged()`` method returns ``false``, trying to + access the ``deletedCount`` property results in an + ``InvalidOperation`` exception. The driver cannot + determine these values if the server does not acknowledge the write + operation. + +If the query filter does not match any documents, the driver doesn't delete any +documents and ``deletedCount`` is ``0``. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API Documentation: + +- `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-one.html>`__ +- `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__ +- `DeleteResult <{+core-api+}/com/mongodb/client/result/DeleteResult.html>`__ + +.. .. _kotlin-sync-delete-instruqt-lab: + +.. .. instruqt:: /mongodb-docs/tracks/... +.. :title: deleteMany() Lesson +.. :drawer: \ No newline at end of file From f83b95a10da8d32bcdd9dc766a69697e3d6ed283 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 22 Jul 2024 17:29:30 -0400 Subject: [PATCH 2/4] first pass fixes --- source/write/delete.txt | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/source/write/delete.txt b/source/write/delete.txt index 9f5af4f..704d70e 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -24,8 +24,8 @@ In this guide, you can learn how to use the {+driver-short+} to remove documents from a MongoDB collection by performing **delete operations**. A delete operation removes one or more documents from a MongoDB collection. -You can perform a delete operation by using the ``delete_one()`` or -``delete_many()`` methods. +You can perform a delete operation by using the ``deleteOne()`` or +``deleteMany()`` methods. .. TODO .. tip:: Interactive Lab @@ -54,6 +54,7 @@ The documents in this collection are modeled by the following {+language+} data :end-before: end-data-class :language: kotlin :copyable: + :dedent: Delete Operations ----------------- @@ -80,6 +81,7 @@ document in which the value of the ``name`` field is ``"Happy Garden"``: :end-before: end-delete-one :language: kotlin :copyable: + :dedent: Delete Multiple Documents ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -93,6 +95,7 @@ value of the ``name`` field is ``"Starbucks"``: :end-before: end-delete-many :language: kotlin :copyable: + :dedent: Customize the Delete Operation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,17 +144,18 @@ configure a ``DeleteOptions`` instance: fields ` guide in the {+mdb-server+} manual for more information. -The following code uses the ``deleteMany()`` method to delete all -documents in the ``restaurants`` collection in which the value of the -``name`` field includes the string ``"Red"``. The example also uses the -``comment()`` method to add a comment to the operation and passes the -resulting ``DeleteOptions`` instance to the ``deleteMany()`` method: +The following code creates options and uses the ``comment()`` method to +add a comment to the delete operation. Then, the example uses the +``deleteMany()`` method to delete all documents in the ``restaurants`` +collection in which the value of the ``name`` field includes the string +``"Red"``. .. literalinclude:: /includes/write/delete.kt :start-after: start-delete-options :end-before: end-delete-options :language: kotlin :copyable: + :dedent: .. tip:: @@ -170,6 +174,9 @@ a ``DeleteResult`` instance: - ``wasAcknowledged()``, which returns ``true`` if the server acknowledges the result +If the query filter does not match any documents, the driver doesn't delete any +documents and the value of ``deletedCount`` is ``0``. + .. note:: If the ``wasAcknowledged()`` method returns ``false``, trying to @@ -178,9 +185,6 @@ a ``DeleteResult`` instance: determine these values if the server does not acknowledge the write operation. -If the query filter does not match any documents, the driver doesn't delete any -documents and ``deletedCount`` is ``0``. - API Documentation ~~~~~~~~~~~~~~~~~ @@ -188,7 +192,7 @@ To learn more about any of the methods or types discussed in this guide, see the following API Documentation: - `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-one.html>`__ -- `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__ +- `deleteMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__ - `DeleteResult <{+core-api+}/com/mongodb/client/result/DeleteResult.html>`__ .. .. _kotlin-sync-delete-instruqt-lab: From 26eeefe87846ef2d9f3950dec4dfee8cad680e7d Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 23 Jul 2024 10:06:27 -0400 Subject: [PATCH 3/4] MM PR fixes 1 --- source/includes/write/delete.kt | 2 +- source/write/delete.txt | 14 +++++--------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/source/includes/write/delete.kt b/source/includes/write/delete.kt index 1624151..99a29c0 100644 --- a/source/includes/write/delete.kt +++ b/source/includes/write/delete.kt @@ -20,7 +20,7 @@ fun main() { // start-delete-many val filter = and( - eq(Restaurant::name.name, "Happy Garden"), + eq(Restaurant::borough.name, "Brooklyn"), eq(Restaurant::name.name, "Starbucks") ) val result = collection.deleteMany(filter) diff --git a/source/write/delete.txt b/source/write/delete.txt index 704d70e..546429e 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -41,11 +41,9 @@ Sample Data ~~~~~~~~~~~ The examples in this guide use the ``sample_restaurants.restaurants`` collection -from the :atlas:`Atlas sample datasets `. - -.. TODO To learn how to create a -.. free MongoDB Atlas cluster and load the sample datasets, see the -.. :ref:`` tutorial. +from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. The documents in this collection are modeled by the following {+language+} data class: @@ -66,9 +64,7 @@ You can perform delete operations in MongoDB by using the following methods: Each delete method requires a **query filter** document, which specifies the search criteria that determine which documents to select for removal. -For more information about query filters, see the -:manual:`Query Filter Documents section ` in -the {+mdb-server+} manual. +To learn more about query filters, see the :ref:`kotlin-sync-specify-query` guide. Delete One Document ~~~~~~~~~~~~~~~~~~~ @@ -102,7 +98,7 @@ Customize the Delete Operation The ``deleteOne()`` and ``deleteMany()`` methods optionally accept a ``DeleteOptions`` parameter, which represents options you can use to -configure the delete operation. If you don't specify any additional +configure the delete operation. If you don't specify any options, the driver performs the delete operation with default settings. The following table describes the setter methods that you can use to From d229efda47619e1c9ce547df805eac034d386bc9 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 23 Jul 2024 10:09:45 -0400 Subject: [PATCH 4/4] vale fix --- source/write/delete.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/write/delete.txt b/source/write/delete.txt index 546429e..38b011a 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -155,9 +155,9 @@ collection in which the value of the ``name`` field includes the string .. tip:: - If the preceding example used the ``deleteOne()`` method instead of - the ``deleteMany()`` method, the driver would delete only the first - document that matched the query filter. + If you use the the ``deleteOne()`` method in the preceding example + instead of the ``deleteMany()`` method, the driver deletes only the + first document that matches the query filter. Return Value ~~~~~~~~~~~~