Skip to content

Commit ce91c70

Browse files
DOCSP-37507 Databases and Collections (#63)
1 parent ff1ba56 commit ce91c70

File tree

9 files changed

+340
-512
lines changed

9 files changed

+340
-512
lines changed

source/connect/connection-options.txt

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,61 @@ Authentication
203203

204204
For more information about the connection option in this section, see :ref:`pymongo-auth`.
205205

206+
Read and Write Operations
207+
~~~~~~~~~~~~~~~~~~~~~~~~~
208+
209+
.. list-table::
210+
:header-rows: 1
211+
:widths: 30 70
212+
213+
* - Connection Option
214+
- Description
215+
216+
* - **replicaSet**
217+
- | Specifies the name of the replica set to connect to.
218+
|
219+
| **Data Type**: {+string-data-type+}
220+
| **Default**: ``null``
221+
| **MongoClient Example**: ``replicaSet='replicaSetName'``
222+
| **Connection URI Example**: ``replicaSet=replicaSetName``
223+
224+
* - **readPreference**
225+
- | Specifies the client's read-preference settings.
226+
|
227+
| **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__
228+
| **Default**: ``ReadPreference.Primary``
229+
| **MongoClient Example**: ``readPreference=ReadPreference.SECONDARY_PREFERRED``
230+
| **Connection URI Example**: ``readPreference=secondaryPreferred``
231+
232+
* - **readConcern**
233+
- | Specifies the client's read-concern settings. For more information, see :manual:`</reference/read-concern/>`.
234+
|
235+
| **Data Type**: {+string-data-type+}
236+
| **Default**: ``None``
237+
| **MongoClient Example**: ``readConcern="majority"``
238+
| **Connection URI Example**: ``readConcern=majority``
239+
240+
* - **writeConcern**
241+
- | Specifies the client's write-concern settings. For more information, see
242+
:manual:`</reference/write-concern/>`.
243+
|
244+
| **Data Type**: {+string-data-type+}
245+
| **Default**: ``None``
246+
| **MongoClient Example**: ``writeConcern="majority"``
247+
| **Connection URI Example**: ``writeConcern=majority``
248+
249+
* - **localThresholdMS**
250+
- | The latency window for a replica-set members eligibility. If a member's
251+
round trip ping takes longer than the fastest server's round-trip ping
252+
time plus this value, the server isn't eligible for selection.
253+
|
254+
| **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__
255+
| **Default**: ``{+int-data-type+}``
256+
| **MongoClient Example**: ``localThresholdMS=35``
257+
| **Connection URI Example**: ``localThresholdMS=35``
258+
259+
For more information about the connection option in this section, see :ref:`pymongo-databases-collections`.
260+
206261
.. _secondary-reads:
207262

208263
Secondary Reads

source/databases-collections.txt

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
.. _pymongo-databases-collections:
2+
3+
=========================
4+
Databases and Collections
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: table, row, organize, storage
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use MongoDB databases and
24+
collections with {+driver-short+}.
25+
26+
MongoDB organizes data into a hierarchy of the following levels:
27+
28+
- **Databases**: The top level of data organization in a MongoDB instance.
29+
- **Collections**: MongoDB stores documents in collections. They are analogous to tables in relational databases.
30+
- **Documents**: Contain literal data such as string, numbers, dates, and other embedded documents.
31+
32+
For more information about document field types and structure, see the
33+
:manual:`Documents </core/document/>` guide in the MongoDB Server manual.
34+
35+
.. TODO: Add a diagram here
36+
37+
Access a Database
38+
-----------------
39+
40+
Access a database by using dictionary-style access on your ``MongoClient`` instance.
41+
42+
The following example accesses a database named "test_database":
43+
44+
.. code-block:: python
45+
46+
database = client["test_database"]
47+
48+
Access a Collection
49+
-------------------
50+
51+
Access a collection by using dictionary-style access on an instance of your database.
52+
53+
The following example accesses a collection named "test_collection":
54+
55+
.. code-block:: python
56+
:emphasize-lines: 2
57+
58+
database = client["test_database"]
59+
collection = database["test_collection"]
60+
61+
.. tip::
62+
63+
If the provided collection name does not already exist in the database,
64+
MongoDB implicitly creates the collection when you first insert data
65+
into it.
66+
67+
Create a Collection
68+
-------------------
69+
70+
Use the ``create_collection()`` method to explicitly create a collection in a
71+
MongoDB database.
72+
73+
The following example creates a collection called ``"example_collection"``:
74+
75+
.. code-block:: python
76+
:emphasize-lines: 2
77+
78+
database = client["test_database"]
79+
database.create_collection("example_collection")
80+
81+
You can specify collection options, such as maximum size and document
82+
validation rules, by passing them in as keyword arguments. For a full list of
83+
optional parameters, see the `create_collection() API documentation
84+
<{+api-root+}pymongo/database.html#pymongo.database.Database.create_collection>`__.
85+
86+
Get a List of Collections
87+
-------------------------
88+
89+
You can query for a list of collections in a database by calling the
90+
``list_collections()`` method. The method returns a cursor containing all
91+
collections in the database and their associated metadata.
92+
93+
The following example calls the ``list_collections()`` method and iterates over
94+
the cursor to print the results:
95+
96+
.. code-block:: python
97+
98+
collection_list = database.list_collections()
99+
100+
for c in collection_list:
101+
print(c)
102+
103+
To query for only the names of the collections in the database, call the
104+
``list_collection_name()`` method as follows:
105+
106+
.. code-block:: python
107+
108+
collection_list = database.list_collection_names()
109+
110+
for c in collection_list:
111+
print(c)
112+
113+
For more information about iterating over a cursor, see :ref:`pymongo-cursors`.
114+
115+
Delete a Collection
116+
-------------------
117+
118+
You can delete a collection from the database by using the ``drop_collection()``
119+
method.
120+
121+
The following example deletes the ``test_collection`` collection:
122+
123+
.. code-block:: python
124+
125+
collection = database["test_collection"];
126+
collection.drop();
127+
128+
.. warning:: Dropping a Collection Deletes All Data in the Collection
129+
130+
Dropping a collection from your database permanently deletes all
131+
documents and all indexes within that collection.
132+
133+
Drop a collection only if the data in it is no longer needed.
134+
135+
Configure Read and Write Operations
136+
-----------------------------------
137+
138+
You can control how the driver routes read operations by setting a **read preference**.
139+
You can also control options for how the driver waits for acknowledgment of
140+
read and write operations on a replica set by setting a **read concern** and a
141+
**write concern**.
142+
143+
By default, databases inherit these settings from the ``MongoClient`` instance,
144+
and collections inherit them from the database. However, you can change these
145+
settings on your database or collection by using one of the following methods:
146+
147+
- ``get_database()``: Gets the database and applies the client's read
148+
preference, read concern, and write preference.
149+
- ``database.with_options()``: Gets the database and applies its current read
150+
preference, read concern, and write preference.
151+
- ``get_collection()``: Gets the collection and applies its current read preference, read concern, and write preference.
152+
- ``collection.with_options()``: Gets the collection and applies the database's read
153+
preference, read concern, and write preference.
154+
155+
To change read or write settings with the preceding methods, call the method and
156+
pass in the collection or database name, and the new read preference, read
157+
concern, or write preference.
158+
159+
The following example shows how to change the read preference, read concern and
160+
write preference of a database called ``test-database`` with the ``get_database()`` method:
161+
162+
.. code-block:: python
163+
164+
client.get_database("test-database",
165+
read_preference=ReadPreference.SECONDARY,
166+
read_concern="local",
167+
write_concern="majority")
168+
169+
The following example shows how to change read and write settings of a
170+
collection called ``test-collection`` with the ``get_collection()`` method:
171+
172+
.. code-block:: python
173+
174+
database.get_collection("test-collection",
175+
read_preference=ReadPreference.SECONDARY,
176+
read_concern="local",
177+
write_concern="majority")
178+
179+
The following example shows how to change read and write settings of a
180+
collection called ``test-collection`` with the ``with_options()`` method:
181+
182+
.. code-block:: python
183+
184+
collection.with_options(read_preference=ReadPreference.SECONDARY,
185+
read_concern="local",
186+
write_concern="majority")
187+
188+
.. tip::
189+
190+
To see the types of read preferences available in the ``ReadPreference`` enum, see the
191+
`API documentation <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.ReadPreference>`__.
192+
193+
To learn more about the read and write settings, see the following guides in the
194+
MongoDB Server manual:
195+
196+
- :manual:`Read Preference </core/read-preference/>`
197+
- :manual:`Read Concern </reference/read-concern/>`
198+
- :manual:`Write Concern </reference/write-concern/>`
199+
200+
Tag Sets
201+
~~~~~~~~
202+
203+
In MongoDB Server, you can apply key-value :manual:`tags
204+
</core/read-preference-tags/>` to replica-set
205+
members according to any criteria you choose. You can then use
206+
those tags to target one or more members for a read operation.
207+
208+
By default, {+driver-short+} ignores tags
209+
when choosing a member to read from. To instruct {+driver-short+}
210+
to prefer certain tags, pass them as a parameter to your
211+
`read preference class <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.Primary>`__
212+
constructor.
213+
214+
In the following code example, the tag set passed to the ``read_preference`` parameter
215+
instructs {+driver-short+} to prefer reads from the
216+
New York data center (``'dc': 'ny'``) and to fall back to the San Francisco data
217+
center (``'dc': 'sf'``):
218+
219+
.. code-block:: python
220+
221+
db = client.get_database(
222+
'test', read_preference=Secondary([{'dc': 'ny'}, {'dc': 'sf'}]))
223+
224+
Local Threshold
225+
~~~~~~~~~~~~~~~
226+
227+
If multiple replica-set members match the read preference and tag sets you specify,
228+
{+driver-short+} reads from the nearest replica-set members, chosen according to
229+
their ping time.
230+
231+
By default, the driver uses only those members whose ping times are within 15 milliseconds
232+
of the nearest member for queries. To distribute reads between members with
233+
higher latencies, pass the ``localThresholdMS`` option to the ``MongoClient()`` constructor.
234+
235+
The following example specifies a local threshold of 35 milliseconds:
236+
237+
.. code-block:: python
238+
:emphasize-lines: 3
239+
240+
client = MongoClient(replicaSet='repl0',
241+
readPreference=ReadPreference.SECONDARY_PREFERRED,
242+
localThresholdMS=35)
243+
244+
In the preceding example, {+driver-short+} distributes reads between matching members
245+
within 35 milliseconds of the closest member's ping time.
246+
247+
.. note::
248+
249+
{+driver-short+} ignores the value of ``localThresholdMS`` when communicating with a
250+
replica set through a ``mongos`` instance. In this case, use the
251+
:manual:`localThreshold </reference/program/mongos/#std-option-mongos.--localThreshold>`
252+
command-line option.
253+
254+
Troubleshooting
255+
---------------
256+
257+
.. include:: /includes/troubleshooting/read-write-options.rst
258+
259+
API Documentation
260+
-----------------
261+
262+
To learn more about any of the methods or types discussed in this
263+
guide, see the following API documentation:
264+
265+
- `create_collection() <{+api-root+}pymongo/database.html#pymongo.database.Database.create_collection>`__
266+
- `list_collections() <{+api-root+}pymongo/database.html#pymongo.database.Database.list_collections>`__
267+
- `list_collection_names() <{+api-root+}pymongo/database.html#pymongo.database.Database.list_collection_names>`__
268+
- `get_database() <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient.get_database>`__
269+
- `get_collection() <{+api-root+}pymongo/database.html#pymongo.database.Database.get_collection>`__
270+
- `database.with_options() <{+api-root+}pymongo/database.html#pymongo.database.Database.with_options>`__
271+
- `collection.with_options() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.with_options>`__

source/fundamentals.txt

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,11 @@ Fundamentals
1212
:maxdepth: 1
1313

1414
/fundamentals/collations
15-
/fundamentals/databases-and-collections
1615
/fundamentals/dates-and-times
1716
/fundamentals/gridfs
1817
/fundamentals/type-hints
1918

2019
- :ref:`pymongo-collations`
21-
- :ref:`pymongo-databases-collections`
2220
- :ref:`pymongo-dates-times`
2321
- :ref:`pymongo-gridfs`
2422
- :ref:`pymongo-type-hints`

0 commit comments

Comments
 (0)