Skip to content

Commit e5973db

Browse files
norareidynorareidy
authored
DOCSP-41967: Insert documents (#116)
* DOCSP-41967: Insert documents * build * snooty * edit * JS feedback * JT feedback * JT feedback 2
1 parent 017275c commit e5973db

File tree

4 files changed

+211
-2
lines changed

4 files changed

+211
-2
lines changed

‎snooty.toml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@ toc_landing_pages = [
2424
php-library = "MongoDB PHP Library"
2525

2626
[constants]
27-
2827
php-library = "MongoDB PHP Library"
2928
driver-short = "PHP library"
3029
stable-api = "Stable API"

‎source/includes/write/insert.php

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
8+
// start-db-coll
9+
$collection = $client->sample_restaurants->restaurants;
10+
// end-db-coll
11+
12+
// Inserts a document that stores a "name" value of "Mongo's Burgers" into the collection
13+
// start-insert-one
14+
$result = $collection->insertOne(['name' => 'Mongo\'s Burgers']);
15+
// end-insert-one
16+
17+
// Inserts documents representing restaurants into the collection
18+
// start-insert-many
19+
$restaurants = [
20+
['name' => 'Mongo\'s Burgers'],
21+
['name' => 'Mongo\'s Pizza']
22+
];
23+
24+
$result = $collection->insertMany($restaurants);
25+
// end-insert-many
26+
27+
// Inserts multiple documents and instructs the insert operation to skip document-level validation
28+
// start-modify
29+
$docs = [
30+
['name' => 'Mongo\'s Burgers'],
31+
['name' => 'Mongo\'s Pizza'],
32+
['name' => 'Mongo\'s Tacos']
33+
];
34+
35+
$result = $collection->insertMany($docs, ['bypassDocumentValidation' => true]);
36+
// end-modify
37+

‎source/write.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ Write Data to MongoDB
88
:titlesonly:
99
:maxdepth: 1
1010

11-
/write/update
11+
/write/insert
12+
/write/update

‎source/write/insert.txt

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _php-write-insert:
2+
3+
================
4+
Insert Documents
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code example, write, save, create
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+php-library+} to add
24+
documents to a MongoDB collection by performing **insert operations**.
25+
26+
An insert operation inserts one or more documents into a MongoDB collection.
27+
You can perform an insert operation by using the following methods:
28+
29+
- ``MongoDB\Collection::insertOne()`` method to insert a single document
30+
- ``MongoDB\Collection::insertMany()`` method to insert one or more documents
31+
32+
Sample Data
33+
~~~~~~~~~~~
34+
35+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
36+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
37+
from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
38+
and assign the following value to your ``collection`` variable:
39+
40+
.. literalinclude:: /includes/write/insert.php
41+
:language: php
42+
:dedent:
43+
:start-after: start-db-coll
44+
:end-before: end-db-coll
45+
46+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
47+
:atlas:`Get Started with Atlas </getting-started>` guide.
48+
49+
The ``_id`` Field
50+
-----------------
51+
52+
In a MongoDB collection, each document *must* contain an ``_id`` field
53+
with a unique field value.
54+
55+
MongoDB allows you to manage this field in two ways:
56+
57+
- Set the ``_id`` field for each document yourself, ensuring each
58+
value is unique.
59+
- Let the driver automatically generate unique ``ObjectId``
60+
values for each document ``_id`` field.
61+
62+
Unless you can guarantee uniqueness, we recommend
63+
letting the driver automatically generate ``_id`` values.
64+
65+
.. note::
66+
67+
Duplicate ``_id`` values violate unique index constraints, which
68+
causes the driver to return a ``MongoDB\Driver\Exception\BulkWriteException``
69+
error.
70+
71+
To learn more about the ``_id`` field, see the
72+
:manual:`Unique Indexes </core/index-unique/>` guide in the {+mdb-server+} manual.
73+
74+
To learn more about document structure and rules, see the
75+
:manual:`Documents </core/document>` guide in the {+mdb-server+} manual.
76+
77+
Insert One Document
78+
-------------------
79+
80+
To add a single document to a MongoDB collection, call the ``MongoDB\Collection::insertOne()``
81+
method and pass the document you want to add.
82+
83+
The following example inserts a document into the ``restaurants`` collection:
84+
85+
.. literalinclude:: /includes/write/insert.php
86+
:language: php
87+
:dedent:
88+
:start-after: start-insert-one
89+
:end-before: end-insert-one
90+
91+
Insert Multiple Documents
92+
-------------------------
93+
94+
To add multiple documents to a MongoDB collection, call the ``MongoDB\Collection::insertMany()``
95+
method and pass an array that contains the list of documents you want to add.
96+
97+
The following example inserts two documents into the ``restaurants`` collection:
98+
99+
.. literalinclude:: /includes/write/insert.php
100+
:language: php
101+
:dedent:
102+
:start-after: start-insert-many
103+
:end-before: end-insert-many
104+
105+
Modify Insert Behavior
106+
----------------------
107+
108+
You can modify the behavior of the ``MongoDB\Collection::insertOne()`` and
109+
``MongoDB\Collection::insertMany()`` methods by passing an array that specifies
110+
option values as a parameter. The following table describes some options
111+
you can set in the array:
112+
113+
.. list-table::
114+
:widths: 30 70
115+
:header-rows: 1
116+
117+
* - Field
118+
- Description
119+
120+
* - ``bypassDocumentValidation``
121+
- | If set to ``true``, allows the write operation to opt out of
122+
:manual:`document-level validation </core/schema-validation>`.
123+
| Defaults to ``false``.
124+
| **Type**: ``bool``
125+
126+
* - ``writeConcern``
127+
- | Sets the write concern for the operation.
128+
| Defaults to the write concern of the namespace.
129+
| **Type**: ``MongoDB\Driver\WriteConcern``
130+
131+
* - ``ordered``
132+
- | If set to ``true``, the operation stops inserting documents when one insert
133+
fails. If ``false``, the operation continues to insert the remaining documents
134+
when one insert fails. You cannot pass this option to the ``insertOne()`` method.
135+
| Defaults to ``true``.
136+
| **Type**: ``bool``
137+
138+
* - ``comment``
139+
- | A comment to attach to the operation. For more information, see the :manual:`insert command
140+
fields </reference/command/insert/#command-fields>` guide in the
141+
{+mdb-server+} manual.
142+
| **Type**: any valid BSON type
143+
144+
Example
145+
~~~~~~~
146+
147+
The following code uses the ``insertMany()`` method to insert three new
148+
documents into a collection. Because the ``bypassDocumentValidation`` field
149+
is set to ``true`` in an options array, this
150+
insert operation bypasses document-level validation:
151+
152+
.. literalinclude:: /includes/write/insert.php
153+
:language: php
154+
:dedent:
155+
:start-after: start-modify
156+
:end-before: end-modify
157+
158+
Additional Information
159+
----------------------
160+
161+
.. TODO:
162+
For runnable code examples of inserting documents with the {+php-library+}, see
163+
:ref:`php-write`.
164+
165+
API Documentation
166+
~~~~~~~~~~~~~~~~~
167+
168+
To learn more about any of the methods or types discussed in this
169+
guide, see the following API documentation:
170+
171+
- `MongoDB\\Collection::insertOne() <{+api+}/method/MongoDBCollection-insertOne/>`__
172+
- `MongoDB\\Collection::insertMany() <{+api+}/method/MongoDBCollection-insertMany/>`__

0 commit comments

Comments
 (0)