diff --git a/snooty.toml b/snooty.toml index 8383cbf5..de32d84e 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,7 +24,6 @@ toc_landing_pages = [ php-library = "MongoDB PHP Library" [constants] - php-library = "MongoDB PHP Library" driver-short = "PHP library" stable-api = "Stable API" diff --git a/source/includes/write/insert.php b/source/includes/write/insert.php new file mode 100644 index 00000000..3561a65e --- /dev/null +++ b/source/includes/write/insert.php @@ -0,0 +1,37 @@ +sample_restaurants->restaurants; +// end-db-coll + +// Inserts a document that stores a "name" value of "Mongo's Burgers" into the collection +// start-insert-one +$result = $collection->insertOne(['name' => 'Mongo\'s Burgers']); +// end-insert-one + +// Inserts documents representing restaurants into the collection +// start-insert-many +$restaurants = [ + ['name' => 'Mongo\'s Burgers'], + ['name' => 'Mongo\'s Pizza'] +]; + +$result = $collection->insertMany($restaurants); +// end-insert-many + +// Inserts multiple documents and instructs the insert operation to skip document-level validation +// start-modify +$docs = [ + ['name' => 'Mongo\'s Burgers'], + ['name' => 'Mongo\'s Pizza'], + ['name' => 'Mongo\'s Tacos'] +]; + +$result = $collection->insertMany($docs, ['bypassDocumentValidation' => true]); +// end-modify + diff --git a/source/write.txt b/source/write.txt index 9053d5a4..9352ca49 100644 --- a/source/write.txt +++ b/source/write.txt @@ -8,4 +8,5 @@ Write Data to MongoDB :titlesonly: :maxdepth: 1 - /write/update \ No newline at end of file + /write/insert + /write/update diff --git a/source/write/insert.txt b/source/write/insert.txt new file mode 100644 index 00000000..340c9410 --- /dev/null +++ b/source/write/insert.txt @@ -0,0 +1,172 @@ +.. _php-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 {+php-library+} 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: + +- ``MongoDB\Collection::insertOne()`` method to insert a single document +- ``MongoDB\Collection::insertMany()`` method 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 PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following value to your ``collection`` variable: + +.. literalinclude:: /includes/write/insert.php + :language: php + :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 ``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 a ``MongoDB\Driver\Exception\BulkWriteException`` + 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 ``MongoDB\Collection::insertOne()`` +method and pass the document you want to add. + +The following example inserts a document into the ``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.php + :language: php + :dedent: + :start-after: start-insert-one + :end-before: end-insert-one + +Insert Multiple Documents +------------------------- + +To add multiple documents to a MongoDB collection, call the ``MongoDB\Collection::insertMany()`` +method and pass an array that contains the list of documents you want to add. + +The following example inserts two documents into the ``restaurants`` collection: + +.. literalinclude:: /includes/write/insert.php + :language: php + :dedent: + :start-after: start-insert-many + :end-before: end-insert-many + +Modify Insert Behavior +---------------------- + +You can modify the behavior of the ``MongoDB\Collection::insertOne()`` and +``MongoDB\Collection::insertMany()`` methods by passing an array that specifies +option values as a parameter. The following table describes some options +you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Field + - Description + + * - ``bypassDocumentValidation`` + - | If set to ``true``, allows the write operation to opt out of + :manual:`document-level validation `. + | Defaults to ``false``. + | **Type**: ``bool`` + + * - ``writeConcern`` + - | Sets the write concern for the operation. + | Defaults to the write concern of the namespace. + | **Type**: ``MongoDB\Driver\WriteConcern`` + + * - ``ordered`` + - | If set to ``true``, the operation stops inserting documents when one insert + fails. If ``false``, the operation continues to insert the remaining documents + when one insert fails. You cannot pass this option to the ``insertOne()`` method. + | Defaults to ``true``. + | **Type**: ``bool`` + + * - ``comment`` + - | A comment to attach to the operation. For more information, see the :manual:`insert command + fields ` guide in the + {+mdb-server+} manual. + | **Type**: any valid BSON type + +Example +~~~~~~~ + +The following code uses the ``insertMany()`` method to insert three new +documents into a collection. Because the ``bypassDocumentValidation`` field +is set to ``true`` in an options array, this +insert operation bypasses document-level validation: + +.. literalinclude:: /includes/write/insert.php + :language: php + :dedent: + :start-after: start-modify + :end-before: end-modify + +Additional Information +---------------------- + +.. TODO: + For runnable code examples of inserting documents with the {+php-library+}, see + :ref:`php-write`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Collection::insertOne() <{+api+}/method/MongoDBCollection-insertOne/>`__ +- `MongoDB\\Collection::insertMany() <{+api+}/method/MongoDBCollection-insertMany/>`__ \ No newline at end of file