diff --git a/snooty.toml b/snooty.toml index 9e1e3f4..98ce36b 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,6 +7,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", ] toc_landing_pages = [ + "/write-operations", "/get-started", "/read", "/connect", diff --git a/source/includes/write/delete.kt b/source/includes/write/delete.kt index 99a29c0..7719d23 100644 --- a/source/includes/write/delete.kt +++ b/source/includes/write/delete.kt @@ -11,7 +11,7 @@ fun main() { val mongoClient = MongoClient.create(uri) val database = mongoClient.getDatabase("sample_restaurants") - val collection = database.getCollection("restaurants") + val collection = database.getCollection("restaurants") // start-delete-one val filter = eq(Restaurant::name.name, "Happy Garden") diff --git a/source/includes/write/insert.kt b/source/includes/write/insert.kt new file mode 100644 index 0000000..49fb403 --- /dev/null +++ b/source/includes/write/insert.kt @@ -0,0 +1,42 @@ +import com.mongodb.client.model.DeleteOptions +import com.mongodb.client.model.Filters.* +import com.mongodb.client.model.InsertManyOptions +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-insert-one + val doc = Restaurant("Sea Shell Bar", "Queens") + val result = collection.insertOne(doc) + // end-insert-one + + // start-insert-many + val docs = listOf( + Restaurant("Full Moon Grill", "Queens"), + Restaurant("King's Cup", "Manhattan"), + ) + + val result = collection.insertMany(docs) + // end-insert-many + + // start-insert-opts + val opts = InsertManyOptions().bypassDocumentValidation(true) + val docs = listOf( + Restaurant("Full Moon Grill", "Queens"), + Restaurant("King's Cup", "Manhattan"), + ) + + val result = collection.insertMany(docs, opts) + // end-insert-opts + +} + diff --git a/source/write-operations.txt b/source/write-operations.txt index 593300b..cabd401 100644 --- a/source/write-operations.txt +++ b/source/write-operations.txt @@ -22,11 +22,11 @@ Write Data to MongoDB :titlesonly: :maxdepth: 1 + /write/insert /write/update /write/delete .. - /write/insert /write/replace /write/bulk-write /write/gridfs @@ -40,8 +40,8 @@ methods that you can use to write data to MongoDB by using the .. tip:: - To learn more about any of the methods shown on this page, see the link - provided in each section. + To learn more about any of the methods shown on this page, see the link + provided in each section. To use an example from this page, copy the code example into the :ref:`sample application ` or your own application. @@ -71,8 +71,8 @@ collection: :copyable: :dedent: -.. To learn more about the ``insert_one()`` method, see the :ref:`Insert Documents -.. ` guide. +To learn more about the ``insertOne()`` method, see the :ref:`Insert Documents +` guide. Insert Multiple --------------- @@ -87,8 +87,8 @@ collection: :copyable: :dedent: -.. To learn more about the ``insert_many()`` method, see the :ref:`Insert Documents -.. ` guide. +To learn more about the ``insertMany()`` method, see the :ref:`Insert Documents +` guide. Update One ---------- diff --git a/source/write/delete.txt b/source/write/delete.txt index 38b011a..e474b02 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -108,7 +108,7 @@ configure a ``DeleteOptions`` instance: :widths: 30 70 :header-rows: 1 - * - Property + * - Method - Description * - ``collation()`` @@ -140,6 +140,9 @@ configure a ``DeleteOptions`` instance: fields ` guide in the {+mdb-server+} manual for more information. +Modify Delete Example +````````````````````` + 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`` @@ -185,7 +188,7 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the methods or types discussed in this -guide, see the following API Documentation: +guide, see the following API documentation: - `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-one.html>`__ - `deleteMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__ diff --git a/source/write/insert.txt b/source/write/insert.txt new file mode 100644 index 0000000..9839df0 --- /dev/null +++ b/source/write/insert.txt @@ -0,0 +1,252 @@ +.. _kotlin-sync-write-insert: + +================ +Insert Documents +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code examples, write, save, create + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to add +documents to a MongoDB collection by performing **insert operations**. + +An insert operation inserts one or more documents into a MongoDB collection. +You can perform an insert operation by using the ``insertOne()`` and +``insertMany()`` methods. + +.. .. tip:: Interactive Lab + +.. This page includes a short interactive lab that demonstrates how to +.. insert data by using the ``insertOne()`` 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 `. 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: + +.. literalinclude:: /includes/write/delete.kt + :start-after: start-data-class + :end-before: end-data-class + :language: kotlin + :copyable: + :dedent: + +The ``_id`` Field +----------------- + +In a MongoDB collection, each document *must* contain an ``_id`` field +that has a unique value. + +MongoDB allows you to manage this field in two ways: + +- You can set this field for each document yourself, ensuring each + ``_id`` field value is unique. +- You can let the driver automatically generate a unique ``ObjectId`` + value for each document ``_id``. If you do not manually set an + ``_id`` value for a document, the driver populates the field + with an ``ObjectId``. + +Unless you can guarantee uniqueness, we recommend +letting the driver automatically generate ``_id`` values. + +.. note:: Duplicate _id Errors + + Setting duplicate ``_id`` values in a collection violates unique + index constraints, which causes the driver to return a ``WriteError`` from + the ``insertOne()`` method or a ``BulkWriteError`` from the + ``insertMany()`` method. + +To learn more about the ``_id`` field, see the +:manual:`Unique Indexes ` guide in the +{+mdb-server+} manual. + +To learn more about document structure and rules, see the +:manual:`Documents ` guide in the {+mdb-server+} manual. + +Insert One Document +------------------- + +To add a single document to a MongoDB collection, call the ``insertOne()`` +method and pass the document you want to add. + +The following example inserts a document into the ``restaurants`` +collection: + +.. literalinclude:: /includes/write/insert.kt + :start-after: start-insert-one + :end-before: end-insert-one + :language: kotlin + :copyable: + :dedent: + +Insert Multiple Documents +------------------------- + +To add multiple documents to a MongoDB collection, user the ``insertMany()`` +method and pass a list of documents you want to add. + +The following example inserts a list of documents into the +``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.kt + :start-after: start-insert-many + :end-before: end-insert-many + :language: kotlin + :copyable: + :dedent: + +Modify Insert Behavior +---------------------- + +The ``insertOne()`` method optionally accepts an ``InsertOneOptions`` +parameter that sets options to configure the insert operation. +If you don't specify any options, the driver performs the insert +operation with default settings. Pass options as the last parameter to +the ``insertOne()`` method. + +The following table describes the setter methods that you can use to +configure an ``InsertOneOptions`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``bypassDocumentValidation()`` + - | If set to ``true``, allows the driver to ignore + :manual:`document-level validation `. + | Defaults to ``false``. + + * - ``comment()`` + - | Sets a comment to attach to the operation. For more information, see the :manual:`insert command + fields ` guide in the + {+mdb-server+} manual for more information. + +You can set the preceding settings on the ``insertMany()`` method +by configuring an ``InsertManyOptions`` instance. You can also use the +``ordered()`` method setter method to specify the order in which the driver +inserts documents into MongoDB: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``ordered()`` + - | If set to ``true``, the driver sends documents to the + server in the order provided. If an error occurs, the driver + cancels all remaining insert operations. + | Defaults to ``true``. + +Pass options as the last parameter to the ``insertMany()`` method. + +Modify Insert Example +~~~~~~~~~~~~~~~~~~~~~ + +The following code uses the ``bypassDocumentValidation()`` method to +set the option to ignore document validation rules. Then, the example uses the +``insertMany()`` method to add new documents to the ``restaurants`` +collection. + +.. literalinclude:: /includes/write/insert.kt + :start-after: start-insert-opts + :end-before: end-insert-opts + :language: kotlin + :copyable: + :dedent: + +Return Value +------------ + +The ``insertOne()`` method returns an ``InsertOneResult`` instance, and +the ``insertMany()`` method returns an ``InsertManyResult`` instance. + +You can use the following methods to retrieve information from +an ``InsertOneResult`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedId()`` + - Indicates the ``_id`` value of the inserted document. + + * - ``wasAcknowledged()`` + - Returns ``true`` if the server acknowledges the result. + +You can use the following methods to retrieve information from +an ``InsertOneResult`` instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedIds()`` + - Indicates the ``_id`` values of the inserted documents. + + * - ``wasAcknowledged()`` + - Returns ``true`` if the server acknowledges the result. + +.. note:: + + If the ``wasAcknowledged()`` method returns ``false``, trying to + access the ``_id`` values results in an + ``InvalidOperation`` exception. The driver cannot + determine these values if the server does not acknowledge the write + operation. + +Additional Information +---------------------- + +For runnable code examples that demonstrate how to insert documents by +using the {+driver-short+}, see :ref:`kotlin-sync-write`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `insertOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-one.html>`__ +- `insertMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-many.html>`__ +- `InsertOneOptions <{+core-api+}/com/mongodb/client/model/InsertOneOptions.html>`__ +- `InsertManyOptions <{+core-api+}/com/mongodb/client/model/InsertManyOptions.html>`__ +- `InsertOneResult <{+core-api+}/com/mongodb/client/result/InsertOneResult.html>`__ +- `InsertManyResult <{+core-api+}/com/mongodb/client/result/InsertManyResult.html>`__ + +.. .. instruqt:: +.. :title: insertOne() Lesson +.. :drawer: \ No newline at end of file