|
| 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>`__ |
0 commit comments