diff --git a/source/includes/write/insert.rb b/source/includes/write/insert.rb new file mode 100644 index 00000000..818f3121 --- /dev/null +++ b/source/includes/write/insert.rb @@ -0,0 +1,41 @@ +require 'bundler/inline' +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = "" + +Mongo::Client.new(uri) do |client| + + # start-db-coll + database = client.use('sample_restaurants') + collection = database[:restaurants] + # end-db-coll + + # Inserts a single document + # start-insert-one + document = { name: 'Neighborhood Bar & Grill', borough: 'Queens' } + collection.insert_one(document) + # end-insert-one + + # Inserts multiple documents + # start-insert-many + documents = [ + { name: 'Metropolitan Cafe', borough: 'Queens' }, + { name: 'Yankee Bistro', borough: 'Bronx' } + ] + collection.insert_many(documents) + # end-insert-many + + # Inserts multiple documents while enabling the bypass_document_validation option + # start-insert-options + documents = [ + { name: 'Cloudy Day', borough: 'Brooklyn' }, + { name: 'Squall or Shine', borough: 'Staten Island' } + { name: 'Rose Field', borough: 'Queens' } + ] + options = { bypass_document_validation: true } + collection.insert_many(documents, options) + # end-insert-options +end \ No newline at end of file diff --git a/source/write/insert.txt b/source/write/insert.txt new file mode 100644 index 00000000..fb620522 --- /dev/null +++ b/source/write/insert.txt @@ -0,0 +1,167 @@ +.. _ruby-write-insert: + +================ +Insert Documents +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, 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 following methods: + +- ``insert_one`` to insert a single document +- ``insert_many`` to insert one or more documents + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your {+language+} application, create a ``Mongo::Client`` object that connects to an Atlas cluster +and assign the following values to your ``database`` and ``collection`` variables: + +.. literalinclude:: /includes/write/insert.rb + :language: ruby + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +The _id Field +------------- + +In a MongoDB collection, each document *must* contain an ``_id`` field +with a unique field value. + +MongoDB allows you to manage this field in two ways: + +- Set the ``_id`` field for each document yourself, ensuring each + value is unique. +- Let the driver automatically generate unique ``BSON::ObjectId`` + values for each document ``_id`` field. + +Unless you can guarantee uniqueness, we recommend +letting the driver automatically generate ``_id`` values. + +.. note:: + + Duplicate ``_id`` values violate unique index constraints, which + causes the driver to return an error. + +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 ``insert_one`` +method and pass the document you want to insert. + +The following example inserts a document into the ``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.rb + :language: ruby + :start-after: start-insert-one + :end-before: end-insert-one + :dedent: + :copyable: + +Insert Multiple Documents +------------------------- + +To add multiple documents to a MongoDB collection, call the ``insert_many`` +method and pass a list of documents you want to insert. + +The following example inserts two documents into the ``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.rb + :language: ruby + :start-after: start-insert-many + :end-before: end-insert-many + :dedent: + :copyable: + +Modify Insert Behavior +---------------------- + +You can pass a ``Hash`` object as a parameter to the ``insert_one`` +method to set options to configure the insert operation. If you don't specify any options, +the driver performs the insert operation with default settings. + +The following table describes the options you can set to +configure the ``insert_one`` operation: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``bypass_document_validation`` + - | Instructs the driver whether to ignore document-level validation. For more information, + see :manual:`Schema Validation ` in the {+mdb-server+} manual. + | 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. + + * - ``session`` + - | Sets the session to use for the operation. To learn more about sessions, see + :manual:`Client Sessions and Causal Consistency Guarantees ` + in the {+mdb-server+} manual. + + * - ``write_concern`` + - | Sets the write concern for the operation. For more information, see the + :manual:`Write Concern ` guide in the {+mdb-server+} manual. + +You can set the preceding settings on the ``insert_many`` method +by passing a ``Hash`` as a parameter to the method call. You can also use the +``ordered`` option to specify the order in which the driver +inserts documents into MongoDB. + +Example +~~~~~~~ + +The following code uses the ``insert_many`` method to insert +three new documents into a collection. Because the ``bypass_document_validation`` +option is enabled, this insert operation bypasses document-level validation. + +.. literalinclude:: /includes/write/insert.rb + :language: ruby + :start-after: start-insert-options + :end-before: end-insert-options + :dedent: + :copyable: + +Additional Information +---------------------- + +To learn more about any of the methods discussed in this +guide, see the following API documentation: + +- `insert_one <{+api-root+}/Mongo/Collection.html#insert_one-instance_method>`_ +- `insert_many <{+api-root+}/Mongo/Collection.html#insert_many-instance_method>`_ \ No newline at end of file