diff --git a/config/redirects b/config/redirects index e5b0c99a..1ae71b70 100644 --- a/config/redirects +++ b/config/redirects @@ -14,7 +14,68 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/ [*-master]: ${prefix}/${version}/security/enterprise-authentication/ -> ${base}/${version}/security/authentication/ [*-master]: ${prefix}/${version}/faq/ -> ${base}/${version}/ [*-master]: ${prefix}/${version}/connect/connection-pools/ -> ${base}/${version}/connect/connection-options/#connection-pools -[v4.7-*]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/run-sample-query/ +[*-master]: ${prefix}/${version}/get-started/download-and-install/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/create-a-deployment/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/create-a-connection-string/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/connect-to-mongodb/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/next-steps/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/connect/csot/ -> ${base}/${version}/connect/connection-options/csot/ +[*-master]: ${prefix}/${version}/connect/network-compression/ -> ${base}/${version}/connect/connection-options/network-compression/ +[*-master]: ${prefix}/${version}/connect/server-selection/ -> ${base}/${version}/connect/connection-options/server-selection/ +[*-master]: ${prefix}/${version}/connect/stable-api/ -> ${base}/${version}/connect/connection-options/stable-api/ +[*-master]: ${prefix}/${version}/connect/tls/ -> ${base}/${version}/security/tls/ +[*-master]: ${prefix}/${version}/write/bulk-write/ -> ${base}/${version}/crud/bulk-write/ +[*-master]: ${prefix}/${version}/databases-collections/#configure-read-and-write-operations/ -> ${base}/${version}/crud/configure/ +[*-master]: ${prefix}/${version}/write/delete/ -> ${base}/${version}/crud/delete/ +[*-master]: ${prefix}/${version}/write/gridfs/ -> ${base}/${version}/crud/gridfs/ +[*-master]: ${prefix}/${version}/write/insert/ -> ${base}/${version}/crud/insert/ +[*-master]: ${prefix}/${version}/write/transactions/ -> ${base}/${version}/crud/transactions/ +[*-master]: ${prefix}/${version}/write/update/ -> ${base}/${version}/crud/update/ +[*-master]: ${prefix}/${version}/write/replace/ -> ${base}/${version}/crud/update/replace/ +[*-master]: ${prefix}/${version}/read/ -> ${base}/${version}/crud/query/ +[*-master]: ${prefix}/${version}/read/count/ -> ${base}/${version}/crud/query/count/ +[*-master]: ${prefix}/${version}/read/cursors/ -> ${base}/${version}/crud/query/cursors/ +[*-master]: ${prefix}/${version}/read/distinct/ -> ${base}/${version}/crud/query/distinct/ +[*-master]: ${prefix}/${version}/read/retrieve/ -> ${base}/${version}/crud/query/find/ +[*-master]: ${prefix}/${version}/read/project/ -> ${base}/${version}/crud/query/project/ +[*-master]: ${prefix}/${version}/read/specify-documents-to-return/ -> ${base}/${version}/crud/query/specify-documents-to-return/ +[*-master]: ${prefix}/${version}/read/specify-a-query/ -> ${base}/${version}/crud/query/specify-query/ +[*-master]: ${prefix}/${version}/read/change-streams/ -> ${base}/${version}/monitoring-and-logging/change-streams/ +[*-master]: ${prefix}/${version}/logging/ -> ${base}/${version}/monitoring-and-logging/logging/ +[*-master]: ${prefix}/${version}/monitoring/ -> ${base}/${version}/monitoring-and-logging/monitoring/ +[*-master]: ${prefix}/${version}/data-formats/custom-types/ -> ${base}/${version}/data-formats/custom-types/type-codecs/ +[*-master]: ${prefix}/${version}/serialization/#binary-data -> ${base}/${version}/reference/compatibility/ +[*-master]: ${prefix}/${version}/compatibility/ -> ${base}/${version}/reference/compatibility/ +[*-master]: ${prefix}/${version}/get-started/connect-to-mongodb/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/create-a-connection-string/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/create-a-deployment/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/download-and-install/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/get-started/next-steps/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/motor-async-migration/ -> ${base}/${version}/reference/migration/ +[*-master]: ${prefix}/${version}/pymongo-to-async-guide/ -> ${base}/${version}/reference/migration/ +[*-master]: ${prefix}/${version}/previous-versions/ -> ${base}/${version}/reference/previous-versions/ +[*-master]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/reference/release-notes/ +[*-master]: ${prefix}/${version}/tools/ -> ${base}/${version}/integrations/ +[*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/reference/upgrade/ +[*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/[v4.7-*]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/run-sample-query/ +[*-master]: ${prefix}/${version}/work-with-indexes/ -> ${base}/${version}/indexes/ + +[*-master]: ${prefix}/${version}/indexes/single-field-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/compound-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/multikey-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/atlas-search-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/text-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/geospatial-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/unique-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/wildcard-index/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/indexes/clustered-index/ -> ${base}/${version}/indexes/ + +[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/ -> ${base}/${version}/aggregation/ +[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/filtered-subset/ -> ${base}/${version}/aggregation/filtered-subset/ +[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/group-total/ -> ${base}/${version}/aggregation/group-total/ +[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/multi-field-join/ -> ${base}/${version}/aggregation/multi-field-join/ +[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/one-to-one-join/ -> ${base}/${version}/aggregation/one-to-one-join/ +[*-master]: ${prefix}/${version}/aggregation/aggregation-tutorials/unpack-arrays/ -> ${base}/${version}/aggregation/unpack-arrays/ # temp redirect until DOP deletes unversioned URLs [master]: ${prefix}/compatibility/ -> ${base}/current/compatibility/ diff --git a/snooty.toml b/snooty.toml index 33d8d906..5970157d 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,17 +2,16 @@ name = "pymongo" title = "PyMongo Driver" toc_landing_pages = [ "/get-started", - "/write-operations", - "/read", "/connect", - "/indexes", - "work-with-indexes", "/aggregation", - "/aggregation/aggregation-tutorials", "/security", "/security/authentication", - "/aggregation-tutorials", "/data-formats", + "/connect/connection-options", + "crud", + "/crud/query", + "/crud/update", + "monitoring-and-logging" ] intersphinx = [ diff --git a/source/aggregation.txt b/source/aggregation.txt index 82d4160f..184acdd7 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -9,7 +9,7 @@ Transform Your Data with Aggregation :values: reference .. meta:: - :keywords: code example, transform, computed, pipeline + :keywords: code example, transform, computed, pipeline, runnable app :description: Learn how to use {+driver-short+} to perform aggregation operations. .. contents:: On this page @@ -22,7 +22,11 @@ Transform Your Data with Aggregation :titlesonly: :maxdepth: 1 - Tutorials + Filtered Subset + Group & Total + Unpack Arrays & Group + One-to-One Join + Multi-Field Join Overview -------- @@ -254,7 +258,36 @@ Aggregation Tutorials ~~~~~~~~~~~~~~~~~~~~~ To view step-by-step explanations of common aggregation tasks, see -:ref:`pymongo-aggregation-tutorials-landing`. +the following tutorials: + +- :ref:`pymongo-aggregation-filtered-subset` +- :ref:`pymongo-aggregation-group-total` +- :ref:`pymongo-aggregation-arrays` +- :ref:`pymongo-aggregation-one-to-one` +- :ref:`pymongo-aggregation-multi-field` + +Aggregation tutorials provide detailed explanations of common +aggregation tasks in a step-by-step format. The tutorials are adapted +from examples in the `Practical MongoDB Aggregations book +`__ by Paul Done. + +Each tutorial includes the following sections: + +- **Introduction**, which describes the purpose and common use cases of the + aggregation type. This section also describes the example and desired + outcome that the tutorial demonstrates. + +- **Before You Get Started**, which describes the necessary databases, + collections, and sample data that you must have before building the + aggregation pipeline and performing the aggregation. + +- **Tutorial**, which describes how to build and run the aggregation + pipeline. This section describes each stage of the completed + aggregation tutorial, and then explains how to run and interpret the + output of the aggregation. + +At the end of each aggregation tutorial, you can find a link to a fully +runnable Python code file that you can run in your environment. API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/aggregation/aggregation-tutorials.txt b/source/aggregation/aggregation-tutorials.txt deleted file mode 100644 index 7be3e3d8..00000000 --- a/source/aggregation/aggregation-tutorials.txt +++ /dev/null @@ -1,112 +0,0 @@ -.. _pymongo-aggregation-tutorials-landing: - -===================== -Aggregation Tutorials -===================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: python, code example, runnable app - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. toctree:: - - Filtered Subset - Group & Total - Unpack Arrays & Group - One-to-One Join - Multi-Field Join - -Overview --------- - -Aggregation tutorials provide detailed explanations of common -aggregation tasks in a step-by-step format. The tutorials are adapted -from examples in the `Practical MongoDB Aggregations book -`__ by Paul Done. - -Each tutorial includes the following sections: - -- **Introduction**, which describes the purpose and common use cases of the - aggregation type. This section also describes the example and desired - outcome that the tutorial demonstrates. - -- **Before You Get Started**, which describes the necessary databases, - collections, and sample data that you must have before building the - aggregation pipeline and performing the aggregation. - -- **Tutorial**, which describes how to build and run the aggregation - pipeline. This section describes each stage of the completed - aggregation tutorial, and then explains how to run and interpret the - output of the aggregation. - -At the end of each aggregation tutorial, you can find a link to a fully -runnable Python code file that you can run in your environment. - -.. _pymongo-agg-tutorial-template-app: - -Aggregation Template App ------------------------- - -Before you begin following an aggregation tutorial, you must set up a -new Python app. You can use this app to connect to a MongoDB -deployment, insert sample data into MongoDB, and run the aggregation -pipeline in each tutorial. - -.. tip:: - - To learn how to install the driver and connect to MongoDB, - see :ref:`pymongo-get-started` - -Once you install the driver, create a file called -``agg_tutorial.py``. Paste the following code in this file to create an -app template for the aggregation tutorials: - -.. literalinclude:: /includes/aggregation/template-app.py - :language: python - :copyable: true - -.. important:: - - In the preceding code, read the code comments to find the sections of - the code that you must modify for the tutorial you are following. - - If you attempt to run the code without making any changes, you will - encounter a connection error. - -For every tutorial, you must replace the connection string placeholder with -your deployment's connection string. To learn how to locate your deployment's connection -string, see :ref:`pymongo-get-started-connection-string`. - -For example, if your connection string is -``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles -the following: - -.. code-block:: python - :copyable: false - - uri = "mongodb+srv://mongodb-example:27017"; - -To run the completed file after you modify the template for a -tutorial, run the following command in your shell: - -.. code-block:: bash - - python3 agg_tutorial.py - -Available Tutorials -------------------- - -- :ref:`pymongo-aggregation-filtered-subset` -- :ref:`pymongo-aggregation-group-total` -- :ref:`pymongo-aggregation-arrays` -- :ref:`pymongo-aggregation-one-to-one` -- :ref:`pymongo-aggregation-multi-field` \ No newline at end of file diff --git a/source/aggregation/aggregation-tutorials/filtered-subset.txt b/source/aggregation/filtered-subset.txt similarity index 97% rename from source/aggregation/aggregation-tutorials/filtered-subset.txt rename to source/aggregation/filtered-subset.txt index e9a738b1..d50146b4 100644 --- a/source/aggregation/aggregation-tutorials/filtered-subset.txt +++ b/source/aggregation/filtered-subset.txt @@ -42,9 +42,7 @@ date of birth, vocation, and other details. Before You Get Started ---------------------- -Before you start this tutorial, complete the -:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working -Python application. +.. include:: /includes/aggregation-tutorial-intro.rst After you set up the app, access the ``persons`` collection by adding the following code to the application: diff --git a/source/aggregation/aggregation-tutorials/group-total.txt b/source/aggregation/group-total.txt similarity index 98% rename from source/aggregation/aggregation-tutorials/group-total.txt rename to source/aggregation/group-total.txt index f71a89ab..ff39eb0e 100644 --- a/source/aggregation/aggregation-tutorials/group-total.txt +++ b/source/aggregation/group-total.txt @@ -44,9 +44,7 @@ only one customer, the order documents are grouped by the Before You Get Started ---------------------- -Before you start this tutorial, complete the -:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working -Python application. +.. include:: /includes/aggregation-tutorial-intro.rst After you set up the app, access the ``orders`` collection by adding the following code to the application: diff --git a/source/aggregation/aggregation-tutorials/multi-field-join.txt b/source/aggregation/multi-field-join.txt similarity index 98% rename from source/aggregation/aggregation-tutorials/multi-field-join.txt rename to source/aggregation/multi-field-join.txt index b6f5ad6a..974f59a0 100644 --- a/source/aggregation/aggregation-tutorials/multi-field-join.txt +++ b/source/aggregation/multi-field-join.txt @@ -66,9 +66,7 @@ the ``orders`` collection. Before You Get Started ---------------------- -Before you start this tutorial, complete the -:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working -Python application. +.. include:: /includes/aggregation-tutorial-intro.rst After you set up the app, access the ``products`` and ``orders`` collections by adding the following code to the application: diff --git a/source/aggregation/aggregation-tutorials/one-to-one-join.txt b/source/aggregation/one-to-one-join.txt similarity index 98% rename from source/aggregation/aggregation-tutorials/one-to-one-join.txt rename to source/aggregation/one-to-one-join.txt index d3d36704..0242348f 100644 --- a/source/aggregation/aggregation-tutorials/one-to-one-join.txt +++ b/source/aggregation/one-to-one-join.txt @@ -61,9 +61,7 @@ that exists in documents in both collections. Before You Get Started ---------------------- -Before you start this tutorial, complete the -:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working -Python application. +.. include:: /includes/aggregation-tutorial-intro.rst After you set up the app, access the ``orders`` and ``products`` collections by adding the following code to the application: diff --git a/source/aggregation/aggregation-tutorials/unpack-arrays.txt b/source/aggregation/unpack-arrays.txt similarity index 97% rename from source/aggregation/aggregation-tutorials/unpack-arrays.txt rename to source/aggregation/unpack-arrays.txt index 7a311a22..61727938 100644 --- a/source/aggregation/aggregation-tutorials/unpack-arrays.txt +++ b/source/aggregation/unpack-arrays.txt @@ -46,9 +46,7 @@ into individual product order documents. Before You Get Started ---------------------- -Before you start this tutorial, complete the -:ref:`pymongo-agg-tutorial-template-app` instructions to set up a working -Python application. +.. include:: /includes/aggregation-tutorial-intro.rst After you set up the app, access the ``orders`` collection by adding the following code to the application: diff --git a/source/connect.txt b/source/connect.txt index 6c983b01..ef2c17b4 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,11 +25,6 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options - Configure TLS - Compress Network Traffic - Customize Server Selection - Stable API - Limit Server Execution Time Overview -------- @@ -85,81 +80,6 @@ Replica Set uri = "mongodb://:/?replicaSet=" client = MongoClient(uri) -Transport Layer Security (TLS) ------------------------------- - -Enable TLS -~~~~~~~~~~ - -.. include:: /includes/connect/tls-tabs.rst - -To learn more about enabling TLS, see :ref:`pymongo-enable-tls` in -the TLS configuration guide. - -Specify a Certificate Authority (CA) File -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/ca-file-tabs.rst - -To learn more about specifying a CA file, see :ref:`pymongo-specify-ca-file` in -the TLS configuration guide. - -Disable OCSP Checks -~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/ocsp-tabs.rst - -To learn more about disabling OCSP checks, see :ref:`pymongo-disable-ocsp` in -the TLS configuration guide. - -Specify a Certificate Revocation List (CRL) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/crl-tabs.rst - -To learn more about specifying a CRL, see :ref:`pymongo-crl` in -the TLS configuration guide. - -Present a Client Certificate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/client-cert-tabs.rst - -To learn more about specifying a client certificate, see :ref:`pymongo-client-cert` in -the TLS configuration guide. - -Provide a Certificate Key File Password -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/key-file-password.rst - -To learn more about providing a key file password, see :ref:`pymongo-key-file-password` in -the TLS configuration guide. - -Allow Insecure TLS -~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/insecure-tls-tabs.rst - -To learn more about allowing insecure TLS, see :ref:`pymongo-insecure-tls` in -the TLS configuration guide. - -Disable Certificate Validation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/disable-cert-validation-tabs.rst - -To learn more about disabling certificate validation, see :ref:`pymongo-insecure-tls` in -the TLS configuration guide. - -Disable Hostname Verification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/connect/disable-host-verification-tabs.rst - -To learn more about disabling hostname verification, see :ref:`pymongo-insecure-tls` in -the TLS configuration guide. - Network Compression ------------------- diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 0a9e5234..4aed4b87 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -17,11 +17,21 @@ Specify Connection Options .. meta:: :keywords: connection string, URI, server, Atlas, settings, configure +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Compress Network Traffic + Customize Server Selection + Stable API + Limit Server Execution Time + Connection Pools + Overview -------- This section describes the MongoDB connection and authentication options -available in {+driver-short+}. You can configure your connection using either +available in {+driver-short+}. You can configure your connection by using either the connection URI or arguments to the ``MongoClient`` constructor. .. _pymongo-connection-uri: @@ -59,314 +69,26 @@ connection options: Connection Options ------------------ -The following sections describe the connection options available in {+driver-short+}. -If a ``MongoClient`` parameter maps to more than one -option in the connection string, the **Connection URI Example** shows all -relevant options. - -.. todo: .. note:: - If you're using a query parameter for a time duration, the value must be in - milliseconds. For example, to specify 60 seconds, use the value ``60000``. If you're - using a ``MongoClientSettings`` object for a time duration, use the appropriate - ``TimeSpan`` value. - -Network Compression -~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Connection Option - - Description - - * - ``compressors`` - - | The preferred compression types, in order, for wire-protocol messages sent to - | or received from the server. The driver uses the first of these compression types - | that the server supports. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``None`` - | **MongoClient Example**: ``compressors = "snappy,zstd,zlib"`` - | **Connection URI Example**: ``compressors=snappy,zstd,zlib`` - - * - ``zlibCompressionLevel`` - - | The compression level for zlib to use. This option accepts - | an integer value between ``-1`` and ``9``: - | - | - **-1:** (Default). zlib uses its default compression level (usually ``6``). - | - **0:** No compression. - | - **1:** Fastest speed but lowest compression. - | - **9:** Best compression but slowest speed. - | - | **Data Type**: {+int-data-type+} - | **Default**: ``-1`` - | **MongoClient Example**: ``zlibCompressionLevel = 3`` - | **Connection URI Example**: ``zlibCompressionLevel=3`` - -Timeouts -~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Connection Option - - Description - - * - ``timeoutMS`` - - | The number of milliseconds each driver operation must complete within. If an - | operation doesn't finish in the specified time, {+driver-short+} raises a timeout exception. - | For more information, see :ref:``. - | - | **Data Type**: ``int`` - | **Default**: ``None`` - | **MongoClient Example**: ``timeoutMS = 10000`` - | **Connection URI Example**: ``timeoutMs=10000`` - -Server Selection -~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Connection Option - - Description - - * - ``server_selector`` - - | A user-defined Python function called by {+driver-short+} to choose the server - | to run an operation against. For more information, see - | :ref:``. - | - | **Data Type**: ``callable`` - | **Default**: ``None`` - | **MongoClient Example**: ``server_selector = your_function`` - | **Connection URI Example**: N/A - -Connection Pools -~~~~~~~~~~~~~~~~ - -A **connection pool** is a cache of open database connections maintained by {+driver-short+}. -When your application requests a connection to MongoDB, {+driver-short+} -gets a connection from the pool, performs operations, and returns the connection -to the pool for reuse. Connection pools help reduce application latency and the number -of times that {+driver-short+} must create new connections. - -To learn more about connection pools, see -:manual:`Connection Pool Overview ` -in the {+mdb-server+} manual. - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Setting - - Description - - * - ``connectTimeoutMS`` - - | The time that {+driver-short+} waits when establishing a new - connection before timing out. - | - | **Data Type**: ``int`` - | **Default**: ``20000`` - | **MongoClient Example**: ``connectTimeoutMS = 40000`` - | **Connection URI Example**: ``connectTimeoutMS=40000`` - - * - ``maxConnecting`` - - | The maximum number of connections that each pool can establish concurrently. - If this limit is reached, further requests wait until a connection is established - or another in-use connection is checked back into the pool. - | - | **Data Type**: ``int`` - | **Default**: ``2`` - | **MongoClient Example**: ``maxConnecting = 3`` - | **Connection URI Example**: ``maxConnecting=3`` - - * - ``maxIdleTimeMS`` - - | The maximum time that a connection can remain idle in the pool. When a connection - exceeds this limit, {+driver-short+} closes the connection and removes it from - the pool. - | - | **Data Type**: ``int`` - | **Default**: ``None`` (no limit) - | **MongoClient Example**: ``maxIdleTimeMS = 60000`` - | **Connection URI Example**: ``maxIdleTimeMS=60000`` - - * - ``maxPoolSize`` - - | The maximum number of concurrent connections that the pool maintains. - If the maximum pool size is reached, further requests wait until a connection - becomes available. - | - | **Data Type**: ``int`` - | **Default**: ``100`` - | **MongoClient Example**: ``maxPoolSize = 150`` - | **Connection URI Example**: ``maxPoolSize=150`` - - * - ``minPoolSize`` - - | The minimum number of concurrent connections that the pool maintains. If - the number of open connections falls below this value due to network errors, - {+driver-short+} attempts to create new connections to maintain this minimum. - | - | **Data Type**: ``int`` - | **Default**: ``0`` - | **MongoClient Example**: ``minPoolSize = 3`` - | **Connection URI Example**: ``minPoolSize=3`` - - * - ``socketTimeoutMS`` - - | The length of time that {+driver-short+} waits for a response from the server - before timing out. - | - | **Data Type**: ``int`` - | **Default**: ``None`` (no timeout) - | **MongoClient Example**: ``socketTimeoutMS = 100000`` - | **Connection URI Example**: ``socketTimeoutMS=100000`` - - * - ``waitQueueTimeoutMS`` - - | How long a thread waits for a connection to become available in the connection pool - before timing out. - | - | **Data Type**: ``int`` - | **Default**: ``None`` (no timeout) - | **MongoClient Example**: ``waitQueueTimeoutMS = 100000`` - | **Connection URI Example**: ``waitQueueTimeoutMS=100000`` - -Authentication -~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Connection Option - - Description - - * - ``authMechanism`` - - | The mechanism {+driver-short+} uses to authenticate the application. Valid - | options are defined in `MECHANISMS. <{+api-root+}pymongo/database.html#pymongo.auth.MECHANISMS>`__ - | - | **Data Type**: {+string-data-type+} - | **Default**: ``"SCRAM-SHA-256"`` when connecting to MongoDB v4.0 or later. - | ``"SCRAM-SHA-1"`` when connecting to MongoDB v3.0 through v3.13. - | **MongoClient Example**: ``authMechanism = "MONGODB-X509"`` - | **Connection URI Example**: ``authMechanism=MONGODB-X509`` - - * - ``authMechanismProperties`` - - | Options specific to the authentication mechanism. Not needed for all authentication - | mechanisms. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``""`` - | **MongoClient Example**: ``authMechanismProperties = "AWS_SESSION_TOKEN:12345"`` - | **Connection URI Example**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435`` - - * - ``authSource`` - - | The database to authenticate against. - | - | **Data Type**: {+string-data-type+} - | **Default**: The database in the connection URI, or ``"admin"`` if none is provided - | **MongoClient Example**: ``authSource = "admin"`` - | **Connection URI Example**: ``authSource=admin`` - - * - ``username`` - - | The username for authentication. When this option is included in a connection - | URI, you must percent-escape it. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``""`` - | **MongoClient Example**: ``username = "my user"`` - | **Connection URI Example**: ``username=my+user`` - - * - ``password`` - - | The password for authentication. When this option is included in a connection - | URI, you must percent-escape it. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``""`` - | **MongoClient Example**: ``password = "strong password"`` - | **Connection URI Example**: ``password=strong+password`` - -For more information about the connection option in this section, see :ref:`pymongo-auth`. - -Read and Write Operations -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Connection Option - - Description - - * - ``replicaSet`` - - | Specifies the name of the replica set to connect to. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``null`` - | **MongoClient Example**: ``replicaSet='replicaSetName'`` - | **Connection URI Example**: ``replicaSet=replicaSetName`` - - * - ``directConnection`` - - | Whether to connect only to the primary member of the replica set. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``False`` - | **MongoClient Example**: ``directConnection=True`` - | **Connection URI Example**: ``directConnection=true`` - - * - ``readPreference`` - - | Specifies the client's read-preference settings. - | - | **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__ - | **Default**: ``ReadPreference.Primary`` - | **MongoClient Example**: ``readPreference=ReadPreference.SECONDARY_PREFERRED`` - | **Connection URI Example**: ``readPreference=secondaryPreferred`` +To learn about the connection options available in {+driver-short+}, see the following +sections: - * - ``readConcern`` - - | Specifies the client's read-concern settings. For more information, see :manual:``. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``None`` - | **MongoClient Example**: ``readConcern="majority"`` - | **Connection URI Example**: ``readConcern=majority`` +- :ref:`Enable Authentication ` +- :ref:`Compress Network Traffic ` +- :ref:`Customize Server Selection ` +- :ref:`Stable API ` +- :ref:`Limit Server Execution Time ` +- :ref:`Connection Pools ` +- :ref:`Configure CRUD Operations ` - * - ``writeConcern`` - - | Specifies the client's write-concern settings. For more information, see - :manual:``. - | - | **Data Type**: {+string-data-type+} - | **Default**: ``None`` - | **MongoClient Example**: ``writeConcern="majority"`` - | **Connection URI Example**: ``writeConcern=majority`` +.. tip:: Authentication and Encryption - * - ``localThresholdMS`` - - | The latency window for a replica-set members eligibility. If a member's - round trip ping takes longer than the fastest server's round-trip ping - time plus this value, the server isn't eligible for selection. - | - | **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__ - | **Default**: {+int-data-type+} - | **MongoClient Example**: ``localThresholdMS=35`` - | **Connection URI Example**: ``localThresholdMS=35`` + To learn how to enable TLS encryption and authentication in {+driver-short+}, + see :ref:`pymongo-tls` and :ref:`pymongo-auth` in the Security section. - * - ``retryReads`` - - | Specifies whether the client retries supported read operations. For more - information, see :manual:`Retryable Reads ` in the {+mdb-server+} - manual. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``True`` - | **MongoClient Example**: ``retryReads=False`` - | **Connection URI Example**: ``retryReads=false`` +API Documentation +----------------- - * - ``retryWrites`` - - | Specifies whether the client retries supported write operations. For more - information, see :manual:`Retryable Writes ` in the {+mdb-server+} - manual. - | - | **Data Type**: {+bool-data-type+} - | **Default**: ``True`` - | **MongoClient Example**: ``retryWrites=False`` - | **Connection URI Example**: ``retryWrites=false`` +To learn more about creating a ``MongoClient`` object in {+driver-short+}, +see the following API documentation: -For more information about the connection options in this section, see :ref:`pymongo-databases-collections`. +- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ \ No newline at end of file diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt new file mode 100644 index 00000000..2dfde47f --- /dev/null +++ b/source/connect/connection-options/connection-pools.txt @@ -0,0 +1,138 @@ +.. _pymongo-connection-pools: + +================ +Connection Pools +================ + +.. facet:: + :name: genre + :values: reference + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about how {+driver-short+} uses connection pools to manage +connections to a MongoDB deployment and how you can configure connection pool settings +in your application. + +A connection pool is a cache of open database connections maintained by {+driver-short+}. +When your application requests a connection to MongoDB, {+driver-short+} seamlessly +gets a connection from the pool, performs operations, and returns the connection +to the pool for reuse. + +Connection pools help reduce application latency and the number of times new connections +are created by {+driver-short+}. + +Configuring Connection Pools +---------------------------- + +You can specify the following connection pool settings in your ``MongoClient`` object or in +your connection URI: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Setting + - Description + + * - ``connectTimeoutMS`` + - | The time that {+driver-short+} waits when establishing a new + connection before timing out. + | + | **Data Type**: ``int`` + | **Default**: ``20000`` + | **MongoClient Example**: ``connectTimeoutMS = 40000`` + | **Connection URI Example**: ``connectTimeoutMS=40000`` + + * - ``maxConnecting`` + - | The maximum number of connections that each pool can establish concurrently. + If this limit is reached, further requests wait until a connection is established + or another in-use connection is checked back into the pool. + | + | **Data Type**: ``int`` + | **Default**: ``2`` + | **MongoClient Example**: ``maxConnecting = 3`` + | **Connection URI Example**: ``maxConnecting=3`` + + * - ``maxIdleTimeMS`` + - | The maximum time that a connection can remain idle in the pool. When a connection + exceeds this limit, {+driver-short+} closes the connection and removes it from + the pool. + | + | **Data Type**: ``int`` + | **Default**: ``None`` (no limit) + | **MongoClient Example**: ``maxIdleTimeMS = 60000`` + | **Connection URI Example**: ``maxIdleTimeMS=60000`` + + * - ``maxPoolSize`` + - | The maximum number of concurrent connections that the pool maintains. + If the maximum pool size is reached, further requests wait until a connection + becomes available. + | + | **Data Type**: ``int`` + | **Default**: ``100`` + | **MongoClient Example**: ``maxPoolSize = 150`` + | **Connection URI Example**: ``maxPoolSize=150`` + + * - ``minPoolSize`` + - | The minimum number of concurrent connections that the pool maintains. If + the number of open connections falls below this value due to network errors, + {+driver-short+} attempts to create new connections to maintain this minimum. + | + | **Data Type**: ``int`` + | **Default**: ``0`` + | **MongoClient Example**: ``minPoolSize = 3`` + | **Connection URI Example**: ``minPoolSize=3`` + + * - ``socketTimeoutMS`` + - | The length of time that {+driver-short+} waits for a response from the server + before timing out. + | + | **Data Type**: ``int`` + | **Default**: ``None`` (no timeout) + | **MongoClient Example**: ``socketTimeoutMS = 100000`` + | **Connection URI Example**: ``socketTimeoutMS=100000`` + + * - ``waitQueueTimeoutMS`` + - | How long a thread waits for a connection to become available in the connection pool + before timing out. + | + | **Data Type**: ``int`` + | **Default**: ``None`` (no timeout) + | **MongoClient Example**: ``waitQueueTimeoutMS = 100000`` + | **Connection URI Example**: ``waitQueueTimeoutMS=100000`` + +The following code creates a client with a maximum connection pool size of ``50`` by using the +``maxPoolSize`` parameter: + +.. code-block:: python + + client = MongoClient(host, port, maxPoolSize=50) + +The following code creates a client with the same configuration as the preceding example, +but uses a connection URI: + +.. code-block:: python + + client = MongoClient("mongodb://:/?maxPoolSize=50") + +Additional Information +---------------------- + +To learn more about connection pools, see :manual:`Connection Pool Overview ` +in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ \ No newline at end of file diff --git a/source/connect/csot.txt b/source/connect/connection-options/csot.txt similarity index 100% rename from source/connect/csot.txt rename to source/connect/connection-options/csot.txt diff --git a/source/connect/network-compression.txt b/source/connect/connection-options/network-compression.txt similarity index 91% rename from source/connect/network-compression.txt rename to source/connect/connection-options/network-compression.txt index 8348fdfe..6171ba79 100644 --- a/source/connect/network-compression.txt +++ b/source/connect/connection-options/network-compression.txt @@ -20,10 +20,16 @@ Compress Network Traffic Overview -------- -{+driver-short+} provides a connection option to compress messages, which reduces the amount +{+driver-short+} provides connection options to compress messages, which reduce the amount of data passed over the network between MongoDB and your application. -{+driver-short+} supports the following compression algorithms. +.. _pymongo-enable-compression: +.. _pymongo-compression-algorithms: + +Specify Compression Algorithms +------------------------------ + +{+driver-short+} supports the following compression algorithms: 1. `Snappy `__: Available in MongoDB 3.6 and later. This option requires the `python-snappy `__ package. @@ -34,18 +40,9 @@ of data passed over the network between MongoDB and your application. 3. `Zstandard `__: Available in MongoDB 4.2 and later. This option requires the `zstandard `__ package. -If you don't specify a compression algorithm, {+driver-short+} doesn't compress your -network traffic. If you specify multiple compression algorithms, the driver selects the -first one in the list supported by your MongoDB instance. - -.. _pymongo-enable-compression: - -Specify Compression Algorithms ------------------------------- - To enable compression for the connection to your MongoDB instance, use the ``compressors`` connection option and specify the compression algorithms you want to use. -You can do this in two ways: +You can do this in two ways: - Pass the algorithms as an argument to the ``MongoClient`` constructor. - Specify the algorithms in your connection string. @@ -54,8 +51,12 @@ The following code example shows both options: .. include:: /includes/connect/compression-tabs.rst -Set the zlib Compression Level -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you don't specify a compression algorithm, {+driver-short+} doesn't compress your +network traffic. If you specify multiple compression algorithms, the driver selects the +first one in the list supported by your MongoDB instance. + +Specify the zlib Compression Level +---------------------------------- If you specify ``zlib`` as one of your compression algorithms, you can also use the ``zlibCompressionLevel`` option to specify a compression level. This option accepts diff --git a/source/connect/server-selection.txt b/source/connect/connection-options/server-selection.txt similarity index 100% rename from source/connect/server-selection.txt rename to source/connect/connection-options/server-selection.txt diff --git a/source/connect/stable-api.txt b/source/connect/connection-options/stable-api.txt similarity index 100% rename from source/connect/stable-api.txt rename to source/connect/connection-options/stable-api.txt diff --git a/source/crud.txt b/source/crud.txt new file mode 100644 index 00000000..fff036c2 --- /dev/null +++ b/source/crud.txt @@ -0,0 +1,227 @@ +.. _pymongo-crud: + +=============== +CRUD Operations +=============== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use {+driver-short+} to read and write MongoDB data. + :keywords: usage examples, query, find, code example, save, create + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Insert Documents + Query Documents + Update Documents + Replace Documents + Delete Documents + Bulk Write Operations + Transactions + Store Large Files + Configure CRUD Operations + +Overview +-------- + +This page contains code examples that show how to connect your Python application +to MongoDB with various settings. + +.. tip:: + + To learn more about the connection options on this page, see the link + provided in each section. + +To use a connection example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Be sure to replace all placeholders in the code examples, such as ````, with +the relevant values for your MongoDB deployment. + +.. _pymongo-crud-sample: + +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/crud-sample-app.py + :language: python + :copyable: true + :linenos: + :emphasize-lines: 4-6 + +Insert One +---------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-insert-one + :end-before: end-insert-one + :language: python + :copyable: + +To learn more about the ``insert_one()`` method, see the :ref:`Insert Documents +` guide. + +Insert Multiple +--------------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-insert-multiple + :end-before: end-insert-multiple + :language: python + :copyable: + +To learn more about the ``insert_many()`` method, see the :ref:`Insert Documents +` guide. + +Update One +---------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-update-one + :end-before: end-update-one + :language: python + :copyable: + +To learn more about the ``update_one()`` method, see the +:ref:`Update Documents ` guide. + +Update Multiple +--------------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-update-multiple + :end-before: end-update-multiple + :language: python + :copyable: + +To learn more about the ``update_many()`` method, see the +:ref:`Update Documents ` guide. + +Replace One +----------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-replace-one + :end-before: end-replace-one + :language: python + :copyable: + +To learn more about the ``replace_one()`` method, see the +:ref:`Replace Documents ` guide. + +Delete One +---------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-delete-one + :end-before: end-delete-one + :language: python + :copyable: + +To learn more about the ``delete_one()`` method, see the +:ref:`Delete Documents ` guide. + +Delete Multiple +--------------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-delete-multiple + :end-before: end-delete-multiple + :language: python + :copyable: + +To learn more about the ``delete_many()`` method, see the +:ref:`Delete Documents ` guide. + +Bulk Write +---------- + +.. literalinclude:: /includes/usage-examples/write-code-examples.py + :start-after: start-bulk-write + :end-before: end-bulk-write + :language: python + :copyable: + +To learn more about the ``bulk_write()`` method, see the +:ref:`Bulk Write ` guide. + +Find One +-------- + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-find-one + :end-before: end-find-one + :language: python + :copyable: + +To learn more about the ``find_one()`` method, see :ref:`pymongo-retrieve-find-one` in +the Retrieve Data guide. + +Find Multiple +------------- + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-find + :end-before: end-find + :language: python + :copyable: + +To learn more about the ``find()`` method, see :ref:`pymongo-retrieve-find-multiple` in +the Retrieve Data guide. + +Count Documents in a Collection +------------------------------- + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-count-all + :end-before: end-count-all + :language: python + :copyable: + +To learn more about the ``count_documents()`` method, see the +:ref:`pymongo-accurate-count` guide. + +Count Documents Returned from a Query +------------------------------------- + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-count-query + :end-before: end-count-query + :language: python + :copyable: + +To learn more about the ``count_documents()`` method, see the +:ref:`pymongo-accurate-count` guide. + +Estimated Document Count +------------------------ + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-estimated-count + :end-before: end-estimated-count + :language: python + :copyable: + +To learn more about the ``estimated_document_count()`` method, see the +:ref:`pymongo-estimated-count` guide. + +Retrieve Distinct Values +------------------------ + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-distinct + :end-before: end-distinct + :language: python + :copyable: + +To learn more about the ``distinct()`` method, see the +:ref:`pymongo-distinct` guide. diff --git a/source/write/bulk-write.txt b/source/crud/bulk-write.txt similarity index 100% rename from source/write/bulk-write.txt rename to source/crud/bulk-write.txt diff --git a/source/crud/configure.txt b/source/crud/configure.txt new file mode 100644 index 00000000..7af6a9c7 --- /dev/null +++ b/source/crud/configure.txt @@ -0,0 +1,181 @@ +.. _pymongo-configure-crud: +.. _pymongo-config-read-write: + +========================= +Configure CRUD Operations +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert, update, replace, delete, options, code example + +Overview +-------- + +In this guide, you can learn how to configure read and write operations in {+driver-short+}. + +Read and Write Settings +----------------------- + +You can control how the driver routes read operations by setting a **read preference**. +You can also control options for how the driver waits for acknowledgment of +read and write operations on a replica set by setting a **read concern** and a +**write concern**. + +By default, databases inherit these settings from the ``MongoClient`` instance, +and collections inherit them from the database. However, you can change these +settings on your database or collection by using one of the following methods: + +- ``get_database()``: Gets the database and applies the client's read + preference, read concern, and write preference. +- ``database.with_options()``: Gets the database and applies its current read + preference, read concern, and write preference. +- ``get_collection()``: Gets the collection and applies its current read preference, read concern, and write preference. +- ``collection.with_options()``: Gets the collection and applies the database's read + preference, read concern, and write preference. + +To change read or write settings with the preceding methods, call the method and +pass in the collection or database name, and the new read preference, read +concern, or write preference. + +The following example shows how to change the read preference, read concern and +write preference of a database called ``test-database`` with the ``get_database()`` method: + +.. code-block:: python + + client.get_database("test-database", + read_preference=ReadPreference.SECONDARY, + read_concern="local", + write_concern="majority") + +The following example shows how to change read and write settings of a +collection called ``test-collection`` with the ``get_collection()`` method: + +.. code-block:: python + + database.get_collection("test-collection", + read_preference=ReadPreference.SECONDARY, + read_concern="local", + write_concern="majority") + +The following example shows how to change read and write settings of a +collection called ``test-collection`` with the ``with_options()`` method: + +.. code-block:: python + + collection.with_options(read_preference=ReadPreference.SECONDARY, + read_concern="local", + write_concern="majority") + +.. tip:: + + To see the types of read preferences available in the ``ReadPreference`` enum, see the + `API documentation <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.ReadPreference>`__. + +To learn more about the read and write settings, see the following guides in the +MongoDB Server manual: + +- :manual:`Read Preference ` +- :manual:`Read Concern ` +- :manual:`Write Concern ` + +Tag Sets +-------- + +In {+mdb-server+}, you can apply key-value :manual:`tags +` to replica-set +members according to any criteria you choose. You can then use +those tags to target one or more members for a read operation. + +By default, {+driver-short+} ignores tags +when choosing a member to read from. To instruct {+driver-short+} +to prefer certain tags, pass them as a parameter to your +`read preference class <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.Primary>`__ +constructor. + +In the following code example, the tag set passed to the ``read_preference`` parameter +instructs {+driver-short+} to prefer reads from the +New York data center (``'dc': 'ny'``) and to fall back to the San Francisco data +center (``'dc': 'sf'``): + +.. code-block:: python + + db = client.get_database( + 'test', read_preference=Secondary([{'dc': 'ny'}, {'dc': 'sf'}])) + +Local Threshold +--------------- + +If multiple replica-set members match the read preference and tag sets you specify, +{+driver-short+} reads from the nearest replica-set members, chosen according to +their ping time. + +By default, the driver uses only those members whose ping times are within 15 milliseconds +of the nearest member for queries. To distribute reads between members with +higher latencies, pass the ``localThresholdMS`` option to the ``MongoClient()`` constructor. + +The following example specifies a local threshold of 35 milliseconds: + +.. code-block:: python + :emphasize-lines: 3 + + client = MongoClient(replicaSet='repl0', + readPreference=ReadPreference.SECONDARY_PREFERRED, + localThresholdMS=35) + +In the preceding example, {+driver-short+} distributes reads between matching members +within 35 milliseconds of the closest member's ping time. + +.. note:: + + {+driver-short+} ignores the value of ``localThresholdMS`` when communicating with a + replica set through a ``mongos`` instance. In this case, use the + :manual:`localThreshold ` + command-line option. + +Retryable Reads and Writes +-------------------------- + +{+driver-short+} automatically retries certain read and write operations a single time +if they fail due to a network or server error. + +You can explicitly disable retryable reads or retryable writes by setting the ``retryReads`` or +``retryWrites`` option to ``False`` in the ``MongoClient()`` constructor. The following +example disables retryable reads and writes for a client: + +.. code-block:: python + + client = MongoClient("", + retryReads=False, retryWrites=False) + +To learn more about supported retryable read operations, see :manual:`Retryable Reads ` +in the {+mdb-server+} manual. To learn more about supported retryable write +operations, see :manual:`Retryable Writes ` in the {+mdb-server+} manual. + +Collation +--------- + +When you create a collection, you can specify a default **collation** for all operations +you perform on the collection. + +.. include:: /includes/collation-description.rst + +The following example creates the same collection as the previous example, +but with a default collation of ``fr_CA``: + +.. code-block:: python + :emphasize-lines: 4 + + from pymongo.collation import Collation + + database = client["test_database"] + database.create_collection("example_collection", collation=Collation(locale='fr_CA')) \ No newline at end of file diff --git a/source/write/delete.txt b/source/crud/delete.txt similarity index 99% rename from source/write/delete.txt rename to source/crud/delete.txt index b265809b..d94d0000 100644 --- a/source/write/delete.txt +++ b/source/crud/delete.txt @@ -1,4 +1,5 @@ .. _pymongo-write-delete: +.. _pymongo-delete: ================ Delete Documents diff --git a/source/write/gridfs.txt b/source/crud/gridfs.txt similarity index 100% rename from source/write/gridfs.txt rename to source/crud/gridfs.txt diff --git a/source/write/insert.txt b/source/crud/insert.txt similarity index 99% rename from source/write/insert.txt rename to source/crud/insert.txt index 39b41cc8..2ff21666 100644 --- a/source/write/insert.txt +++ b/source/crud/insert.txt @@ -1,4 +1,5 @@ .. _pymongo-write-insert: +.. _pymongo-insert: ================ Insert Documents @@ -327,7 +328,7 @@ Additional Information ---------------------- For runnable code examples of inserting documents with {+driver-short+}, see -:ref:`pymongo-write`. +:ref:`pymongo-crud`. API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/read.txt b/source/crud/query.txt similarity index 75% rename from source/read.txt rename to source/crud/query.txt index 5fe466b0..c1dfff27 100644 --- a/source/read.txt +++ b/source/crud/query.txt @@ -1,8 +1,8 @@ -.. _pymongo-read: +.. _pymongo-query: -========= -Read Data -========= +===== +Query +===== .. contents:: On this page :local: @@ -13,7 +13,7 @@ Read Data .. facet:: :name: genre :values: reference - + .. meta:: :description: Learn how to use {+driver-short+} to read data from MongoDB. :keywords: usage examples, query, find, code example @@ -22,20 +22,19 @@ Read Data :titlesonly: :maxdepth: 1 - Query - Retrieve Data - Specify Fields to Return - Specify Documents to Return - Count Documents - Distinct Field Values - Access Data from a Cursor - Monitor Data Changes + Specify a Query + Find Documents + Specify Documents to Return + Specify Fields to Return + Count Documents + Distinct Field Values + Access Data from a Cursor Overview -------- On this page, you can see copyable code examples that show common -methods you can use to retrieve documents with {+driver-short+}. +methods you can use to find documents with {+driver-short+}. .. tip:: @@ -43,15 +42,15 @@ methods you can use to retrieve documents with {+driver-short+}. provided in each section. To use an example from this page, copy the code example into the -:ref:`sample application ` or your own application. +:ref:`sample application ` or your own application. Be sure to replace all placeholders in the code examples, such as ````, with the relevant values for your MongoDB deployment. -.. _pymongo-read-sample: +.. _pymongo-query-sample: .. include:: /includes/usage-examples/sample-app-intro.rst -.. literalinclude:: /includes/usage-examples/sample-app.py +.. literalinclude:: /includes/usage-examples/crud-sample-app.py :language: python :copyable: :linenos: @@ -129,14 +128,3 @@ Retrieve Distinct Values To learn more about the ``distinct()`` method, see the :ref:`pymongo-distinct` guide. -Monitor Data Changes --------------------- - -.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py - :start-after: start-watch-for-changes - :end-before: end-watch-for-changes - :language: python - :copyable: - -To learn more about the ``watch()`` method, see the -:ref:`pymongo-change-streams` guide. \ No newline at end of file diff --git a/source/read/count.txt b/source/crud/query/count.txt similarity index 100% rename from source/read/count.txt rename to source/crud/query/count.txt diff --git a/source/read/cursors.txt b/source/crud/query/cursors.txt similarity index 98% rename from source/read/cursors.txt rename to source/crud/query/cursors.txt index c818b1ae..c788f7bd 100644 --- a/source/read/cursors.txt +++ b/source/crud/query/cursors.txt @@ -35,7 +35,8 @@ Sample Data The examples in this guide use the ``sample_restaurants.restaurants`` collection from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. +free MongoDB Atlas cluster and load the sample datasets, see the :ref:`` +tutorial. .. _pymongo-cursors-iterate: diff --git a/source/read/distinct.txt b/source/crud/query/distinct.txt similarity index 100% rename from source/read/distinct.txt rename to source/crud/query/distinct.txt diff --git a/source/read/retrieve.txt b/source/crud/query/find.txt similarity index 98% rename from source/read/retrieve.txt rename to source/crud/query/find.txt index 392e6ae3..38e5ee91 100644 --- a/source/read/retrieve.txt +++ b/source/crud/query/find.txt @@ -1,8 +1,9 @@ .. _pymongo-retrieve: +.. _pymongo-find: -============= -Retrieve Data -============= +============== +Find Documents +============== .. contents:: On this page :local: @@ -35,12 +36,13 @@ Sample Data The examples in this guide use the ``sample_restaurants.restaurants`` collection from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. +free MongoDB Atlas cluster and load the sample datasets, see the :ref:`` +tutorial. .. _pymongo-retrieve-find: -Find Documents --------------- +Finding Documents +----------------- {+driver-short+} includes two methods for retrieving documents from a collection: ``find_one()`` and ``find()``. @@ -215,7 +217,7 @@ To learn more about PyMongoArrow, see the To learn more about query filters, see :ref:`pymongo-specify-query`. For runnable code examples of retrieving documents with {+driver-short+}, see -:ref:`pymongo-read`. +:ref:`pymongo-query`. API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/read/project.txt b/source/crud/query/project.txt similarity index 100% rename from source/read/project.txt rename to source/crud/query/project.txt diff --git a/source/read/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt similarity index 99% rename from source/read/specify-documents-to-return.txt rename to source/crud/query/specify-documents-to-return.txt index e9d0b5ab..d2eed17f 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -32,7 +32,8 @@ Sample Data The examples in this guide use the ``sample_restaurants.restaurants`` collection from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. +free MongoDB Atlas cluster and load the sample datasets, see the :ref:`` +tutorial. Limit ----- diff --git a/source/read/specify-a-query.txt b/source/crud/query/specify-query.txt similarity index 100% rename from source/read/specify-a-query.txt rename to source/crud/query/specify-query.txt diff --git a/source/write/replace.txt b/source/crud/replace.txt similarity index 100% rename from source/write/replace.txt rename to source/crud/replace.txt diff --git a/source/write/transactions.txt b/source/crud/transactions.txt similarity index 100% rename from source/write/transactions.txt rename to source/crud/transactions.txt diff --git a/source/write/update.txt b/source/crud/update.txt similarity index 99% rename from source/write/update.txt rename to source/crud/update.txt index e9cab858..a1968a2d 100644 --- a/source/write/update.txt +++ b/source/crud/update.txt @@ -1,4 +1,5 @@ .. _pymongo-write-update: +.. _pymongo-update: ================ Update Documents diff --git a/source/data-formats/custom-types.txt b/source/data-formats/custom-types.txt index 1f33b152..12c5adc8 100644 --- a/source/data-formats/custom-types.txt +++ b/source/data-formats/custom-types.txt @@ -1,5 +1,6 @@ .. _pymongo-custom-types: +============ Custom Types ============ @@ -12,641 +13,13 @@ Custom Types .. facet:: :name: genre :values: reference - -.. meta:: - :keywords: class, code examples - -Overview --------- - -This guide explains how to use {+driver-short+} to encode and decode custom types. - -Encode a Custom Type --------------------- - -You might need to define a custom type if you want to store a data type that -the driver doesn't understand. For example, the -BSON library's ``Decimal128`` type is distinct -from Python's built-in ``Decimal`` type. Attempting -to save an instance of ``Decimal`` with {+driver-short+} results in an -``InvalidDocument`` exception, as shown in the following code example. Select the -:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - from decimal import Decimal - - num = Decimal("45.321") - db["coll"].insert_one({"num": num}) - - .. output:: - :language: shell - - Traceback (most recent call last): - ... - bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), of - type: - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - from decimal import Decimal - - num = Decimal("45.321") - await db["coll"].insert_one({"num": num}) - - .. output:: - :language: shell - - Traceback (most recent call last): - ... - bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), of - type: - -The following sections show how to define a custom type for this ``Decimal`` type. - -Define a Type Codec Class -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To encode a custom type, you must first define a **type codec.** A type codec -describes how an instance of a custom type is -converted to and from a type that the ``bson`` module can already encode. - -When you define a type codec, your class must inherit from one of the base classes in the -``codec_options`` module. The following table describes these base classes, and when -and how to implement them: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 10 10 20 - - * - Base Class - - When to Use - - Members to Implement - - * - ``codec_options.TypeEncoder`` - - Inherit from this class to define a codec that - encodes a custom Python type to a known BSON type. - - - ``python_type`` attribute: The custom Python type that's encoded by this type codec - - ``transform_python()`` method: Function that transforms a custom type value into a type - that BSON can encode - - * - ``codec_options.TypeDecoder`` - - Inherit from this class to define a codec that - decodes a specified BSON type into a custom Python type. - - - ``bson_type`` attribute: The BSON type that's decoded by this type codec - - ``transform_bson()`` method: Function that transforms a standard BSON type value - into the custom type - - * - ``codec_options.TypeCodec`` - - Inherit from this class to define a codec that - can both encode and decode a custom type. - - - ``python_type`` attribute: The custom Python type that's encoded by this type codec - - ``bson_type`` attribute: The BSON type that's decoded by this type codec - - ``transform_bson()`` method: Function that transforms a standard BSON type value - into the custom type - - ``transform_python()`` method: Function that transforms a custom type value into a type - that BSON can encode - -Because the example ``Decimal`` custom type can be converted to and from a -``Decimal128`` instance, you must define how to encode and decode this type. -Therefore, the ``Decimal`` type codec class must inherit from -the ``TypeCodec`` base class: - -.. code-block:: python - - from bson.decimal128 import Decimal128 - from bson.codec_options import TypeCodec - - class DecimalCodec(TypeCodec): - python_type = Decimal - bson_type = Decimal128 - - def transform_python(self, value): - return Decimal128(value) - - def transform_bson(self, value): - return value.to_decimal() - -Add Codec to the Type Registry -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After defining a custom type codec, you must add it to {+driver-short+}'s **type registry**, -the list of types the driver can encode and decode. -To do so, create an instance of the ``TypeRegistry`` class, passing in an instance -of your type codec class inside a list. If you create multiple custom codecs, you can -pass them all to the ``TypeRegistry`` constructor. - -The following code examples adds an instance of the ``DecimalCodec`` type codec to -the type registry: - -.. code-block:: python - - from bson.codec_options import TypeRegistry - - decimal_codec = DecimalCodec() - type_registry = TypeRegistry([decimal_codec]) - -.. note:: - - Once instantiated, registries are immutable and the only way to add codecs - to a registry is to create a new one. - -Get a Collection Reference -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Finally, define a ``codec_options.CodecOptions`` instance, passing your ``TypeRegistry`` -object as a keyword argument. Pass your ``CodecOptions`` object to the -``get_collection()`` method to obtain a collection that can use your custom type: - -.. code-block:: python - - from bson.codec_options import CodecOptions - - codec_options = CodecOptions(type_registry=type_registry) - collection = db.get_collection("test", codec_options=codec_options) - -You can then encode and decode instances of the ``Decimal`` class. Select the -:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - - collection.insert_one({"num": Decimal("45.321")}) - my_doc = collection.find_one() - pprint.pprint(my_doc) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal('45.321')} - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - - await collection.insert_one({"num": Decimal("45.321")}) - my_doc = await collection.find_one() - pprint.pprint(my_doc) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal('45.321')} - -To see how MongoDB stores an instance of the custom type, -create a new collection object without the customized codec options, then use it -to retrieve the document containing the custom type. The following example shows -that {+driver-short+} stores an instance of the ``Decimal`` class as a ``Decimal128`` -value. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the -corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - - new_collection = db.get_collection("test") - pprint.pprint(new_collection.find_one()) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal128('45.321')} - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - - new_collection = db.get_collection("test") - pprint.pprint(await new_collection.find_one()) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal128('45.321')} - -Encode a Subtype ----------------- - -You might also need to encode one or more types that inherit from your custom type. -Consider the following subtype of the ``Decimal`` class, which contains a method to -return its value as an integer: - -.. code-block:: python - - class DecimalInt(Decimal): - def get_int(self): - return int(self) - -If you try to save an instance of the ``DecimalInt`` class without first registering a type -codec for it, {+driver-short+} raises an error. Select the -:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - collection.insert_one({"num": DecimalInt("45.321")}) - - .. output:: - :language: shell - - Traceback (most recent call last): - ... - bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), - of type: - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - await collection.insert_one({"num": DecimalInt("45.321")}) - - .. output:: - :language: shell - - Traceback (most recent call last): - ... - bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), - of type: - -To encode an instance of the ``DecimalInt`` class, you must define a type codec for -the class. This type codec must inherit from the parent class's codec, ``DecimalCodec``, -as shown in the following example: -.. code-block:: python - - class DecimalIntCodec(DecimalCodec): - @property - def python_type(self): - # The Python type encoded by this type codec - return DecimalInt - -You can then add the sublcass's type codec to the type registry and encode instances -of the custom type. Select the -:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - from bson.codec_options import CodecOptions - - decimal_int_codec = DecimalIntCodec() - type_registry = TypeRegistry([decimal_codec, decimal_int_codec]) - codec_options = CodecOptions(type_registry=type_registry) - - collection = db.get_collection("test", codec_options=codec_options) - collection.insert_one({"num": DecimalInt("45.321")}) - - my_doc = collection.find_one() - pprint.pprint(my_doc) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal('45.321')} - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - from bson.codec_options import CodecOptions - - decimal_int_codec = DecimalIntCodec() - type_registry = TypeRegistry([decimal_codec, decimal_int_codec]) - codec_options = CodecOptions(type_registry=type_registry) - - collection = db.get_collection("test", codec_options=codec_options) - await collection.insert_one({"num": DecimalInt("45.321")}) - - my_doc = await collection.find_one() - pprint.pprint(my_doc) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal('45.321')} - -.. note:: - - The ``transform_bson()`` method of the ``DecimalCodec`` class results in - these values being decoded as ``Decimal``, not ``DecimalInt``. - -Define a Fallback Encoder -------------------------- - -You can also register a **fallback encoder**, a callable to encode types not recognized -by BSON and for which no type codec has been registered. -The fallback encoder accepts an unencodable -value as a parameter and returns a BSON-encodable value. - -The following fallback encoder encodes Python's ``Decimal`` type to a ``Decimal128``: - -.. code-block:: python - - def fallback_encoder(value): - if isinstance(value, Decimal): - return Decimal128(value) - return value - -After declaring a fallback encoder, perform the following steps: - -- Construct a new instance of the ``TypeRegistry`` class. Use the ``fallback_encoder`` - keyword argument to pass in the fallback encoder. -- Construct a new instance of the ``CodecOptions`` class. Use the ``type_registry`` - keyword argument to pass in the ``TypeRegistry`` instance. -- Call the ``get_collection()`` method. Use the ``codec_options`` keyword argument - to pass in the ``CodecOptions`` instance. - -The following code example shows this process: - -.. code-block:: python - - type_registry = TypeRegistry(fallback_encoder=fallback_encoder) - codec_options = CodecOptions(type_registry=type_registry) - collection = db.get_collection("test", codec_options=codec_options) - -You can then use this reference to a collection to store instances of the ``Decimal`` -class. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the -corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - - collection.insert_one({"num": Decimal("45.321")}) - my_doc = collection.find_one() - pprint.pprint(my_doc) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal128('45.321')} - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - import pprint - - await collection.insert_one({"num": Decimal("45.321")}) - my_doc = await collection.find_one() - pprint.pprint(my_doc) - - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal128('45.321')} - -.. note:: - - Fallback encoders are invoked *after* attempts to encode the given value - with standard BSON encoders and any configured type encoders have failed. - Therefore, in a type registry configured with a type encoder and fallback - encoder that both target the same custom type, the behavior specified in - the type encoder takes precedence. - -Encode Unknown Types -~~~~~~~~~~~~~~~~~~~~ -.. TODO: consider new example - -Because fallback encoders don't need to declare the types that they encode -beforehand, you can use them in cases where a ``TypeEncoder`` doesn't work. -For example, you can use a fallback encoder to save arbitrary objects to MongoDB. -Consider the following arbitrary custom types: - -.. code-block:: python - - class MyStringType(object): - def __init__(self, value): - self.__value = value - - def __repr__(self): - return "MyStringType('%s')" % (self.__value,) - - - class MyNumberType(object): - def __init__(self, value): - self.__value = value - - def __repr__(self): - return "MyNumberType(%s)" % (self.__value,) - -You can define a fallback encoder that pickles the objects it receives -and returns them as ``Binary`` instances with a custom -subtype. This custom subtype allows you to define a ``TypeDecoder`` class that -identifies pickled artifacts upon retrieval and transparently decodes them -back into Python objects: - -.. code-block:: python - - import pickle - from bson.binary import Binary, USER_DEFINED_SUBTYPE - from bson.codec_options import TypeDecoder - - def fallback_pickle_encoder(value): - return Binary(pickle.dumps(value), USER_DEFINED_SUBTYPE) - - class PickledBinaryDecoder(TypeDecoder): - bson_type = Binary - - def transform_bson(self, value): - if value.subtype == USER_DEFINED_SUBTYPE: - return pickle.loads(value) - return value - -You can then add the ``PickledBinaryDecoder`` to the codec options for a collection -and use it to encode and decode your custom types. Select the -:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: - -.. tabs:: - - .. tab:: Synchronous - :tabid: sync - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - from bson.codec_options import CodecOptions,TypeRegistry - - codec_options = CodecOptions( - type_registry=TypeRegistry( - [PickledBinaryDecoder()], fallback_encoder=fallback_pickle_encoder - ) - ) - - collection = db.get_collection("test", codec_options=codec_options) - collection.insert_one( - {"_id": 1, "str": MyStringType("hello world"), "num": MyNumberType(2)} - ) - my_doc = collection.find_one() - - print(isinstance(my_doc["str"], MyStringType)) - print(isinstance(my_doc["num"], MyNumberType)) - - .. output:: - :language: shell - - True - True - - .. tab:: Asynchronous - :tabid: async - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - from bson.codec_options import CodecOptions,TypeRegistry - - codec_options = CodecOptions( - type_registry=TypeRegistry( - [PickledBinaryDecoder()], fallback_encoder=fallback_pickle_encoder - ) - ) - - collection = db.get_collection("test", codec_options=codec_options) - await collection.insert_one( - {"_id": 1, "str": MyStringType("hello world"), "num": MyNumberType(2)} - ) - my_doc = await collection.find_one() - - print(isinstance(my_doc["str"], MyStringType)) - print(isinstance(my_doc["num"], MyNumberType)) - - .. output:: - :language: shell - - True - True - -Limitations ------------ - -{+driver-short+} type codecs and fallback encoders have the following -limitations: - -- You can't customize the encoding behavior of Python types that {+driver-short+} - already understands, like ``int`` and ``str``. - If you try to instantiate a type registry with one or more codecs that act - upon a built-in type, {+driver-short+} raises a ``TypeError``. This limitation also - applies to all subtypes of the standard types. - -- You can't chain type encoders. A custom type value, once - transformed by a codec's ``transform_python()`` method, *must* result in a - type that is either BSON-encodable by default, or can be - transformed by the fallback encoder into something BSON-encodable. It - *cannot* be transformed a second time by a different type codec. - -- The ``Database.command()`` method doesn't apply custom - type decoders while decoding the command response document. - -- The ``gridfs`` class doesn't apply custom type encoding or decoding to any - documents it receives or returns. - -API Documentation ------------------ +.. meta:: + :keywords: bson, uuid, date, time -For more information about encoding and decoding custom types, -see the following API documentation: +.. toctree:: + :titlesonly: + :maxdepth: 1 -- `TypeCodec <{+api-root+}bson/codec_options.html#bson.codec_options.TypeCodec>`__ -- `TypeEncoder <{+api-root+}bson/codec_options.html#bson.codec_options.TypeEncoder>`__ -- `TypeDecoder <{+api-root+}bson/codec_options.html#bson.codec_options.TypeDecoder>`__ -- `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__ -- `CodecOptions <{+api-root+}bson/codec_options.html#bson.codec_options.CodecOptions>`__ \ No newline at end of file + Serialization + Type Codecs \ No newline at end of file diff --git a/source/serialization.txt b/source/data-formats/custom-types/serialization.txt similarity index 55% rename from source/serialization.txt rename to source/data-formats/custom-types/serialization.txt index 723e7d5e..75e15766 100644 --- a/source/serialization.txt +++ b/source/data-formats/custom-types/serialization.txt @@ -20,8 +20,7 @@ Serialization Overview -------- -In this guide, you can learn how to use {+driver-short+} to perform -serialization. +In this guide, you can learn how to use {+driver-short+} to serialize your custom types. Serialization is the process of mapping a {+language+} object to a BSON document for storage in MongoDB. {+driver-short+} automatically converts basic {+language+} @@ -29,18 +28,6 @@ types into BSON when you insert a document into a collection. Similarly, when yo document from a collection, {+driver-short+} automatically converts the returned BSON back into the corresponding {+language+} types. -You can use {+driver-short+} to serialize and deserialize the following {+language+} -types: - -- ``str`` -- ``int`` -- ``float`` -- ``bool`` -- ``datetime.datetime`` -- ``list`` -- ``dict`` -- ``None`` - For a complete list of {+language+}-to-BSON mappings, see the `bson <{+api-root+}bson/index.html>`__ API documentation. @@ -95,63 +82,4 @@ it back into a ``Restaurant`` object from the preceding example: restaurant = deserialize_restaurant(restaurant_doc) To learn more about retrieving documents from a collection, see the :ref:`pymongo-retrieve` -guide. - -.. _pymongo-serialization-binary-data: - -Binary Data ------------ - -In all versions of Python, {+driver-short+} encodes instances of the -`bytes `__ class -as binary data with subtype 0, the default subtype for binary data. In Python 3, -{+driver-short+} decodes these values to instances of the ``bytes`` class. In Python 2, -the driver decodes them to instances of the -`Binary `__ -class with subtype 0. - -The following code examples show how {+driver-short+} decodes instances of the ``bytes`` -class. Select the :guilabel:`Python 2` or :guilabel:`Python 3` tab to view the corresponding -code. - -.. tabs:: - - .. tab:: Python 2 - :tabid: python2 - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - from pymongo import MongoClient - - client = MongoClient() - client.test.test.insert_one({'binary': b'this is a byte string'}) - doc = client.test.test.find_one() - print(doc) - - .. output:: - - {u'_id': ObjectId('67afb78298f604a28f0247b4'), u'binary': Binary('this is a byte string', 0)} - - .. tab:: Python 3 - :tabid: python3 - - .. io-code-block:: - :copyable: true - - .. input:: - :language: python - - from pymongo import MongoClient - - client = MongoClient() - client.test.test.insert_one({'binary': b'this is a byte string'}) - doc = client.test.test.find_one() - print(doc) - - .. output:: - - {'_id': ObjectId('67afb78298f604a28f0247b4'), 'binary': b'this is a byte string'} \ No newline at end of file +guide. \ No newline at end of file diff --git a/source/data-formats/custom-types/type-codecs.txt b/source/data-formats/custom-types/type-codecs.txt new file mode 100644 index 00000000..9144d31a --- /dev/null +++ b/source/data-formats/custom-types/type-codecs.txt @@ -0,0 +1,652 @@ +.. _pymongo-type-codecs: + +Type Codecs +=========== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: class, code examples + +Overview +-------- + +This guide explains how to use {+driver-short+} to encode and decode custom types. + +Encode a Custom Type +-------------------- + +You might need to define a custom type if you want to store a data type that +the driver doesn't understand. For example, the +BSON library's ``Decimal128`` type is distinct +from Python's built-in ``Decimal`` type. Attempting +to save an instance of ``Decimal`` with {+driver-short+} results in an +``InvalidDocument`` exception, as shown in the following code example. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + from decimal import Decimal + + num = Decimal("45.321") + db["coll"].insert_one({"num": num}) + + .. output:: + :language: shell + + Traceback (most recent call last): + ... + bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), of + type: + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + from decimal import Decimal + + num = Decimal("45.321") + await db["coll"].insert_one({"num": num}) + + .. output:: + :language: shell + + Traceback (most recent call last): + ... + bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), of + type: + +The following sections show how to define a custom type for this ``Decimal`` type. + +Define a Type Codec Class +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To encode a custom type, you must first define a **type codec.** A type codec +describes how an instance of a custom type is +converted to and from a type that the ``bson`` module can already encode. + +When you define a type codec, your class must inherit from one of the base classes in the +``codec_options`` module. The following table describes these base classes, and when +and how to implement them: + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 10 10 20 + + * - Base Class + - When to Use + - Members to Implement + + * - ``codec_options.TypeEncoder`` + - Inherit from this class to define a codec that + encodes a custom Python type to a known BSON type. + - - ``python_type`` attribute: The custom Python type that's encoded by this type codec + - ``transform_python()`` method: Function that transforms a custom type value into a type + that BSON can encode + + * - ``codec_options.TypeDecoder`` + - Inherit from this class to define a codec that + decodes a specified BSON type into a custom Python type. + - - ``bson_type`` attribute: The BSON type that's decoded by this type codec + - ``transform_bson()`` method: Function that transforms a standard BSON type value + into the custom type + + * - ``codec_options.TypeCodec`` + - Inherit from this class to define a codec that + can both encode and decode a custom type. + - - ``python_type`` attribute: The custom Python type that's encoded by this type codec + - ``bson_type`` attribute: The BSON type that's decoded by this type codec + - ``transform_bson()`` method: Function that transforms a standard BSON type value + into the custom type + - ``transform_python()`` method: Function that transforms a custom type value into a type + that BSON can encode + +Because the example ``Decimal`` custom type can be converted to and from a +``Decimal128`` instance, you must define how to encode and decode this type. +Therefore, the ``Decimal`` type codec class must inherit from +the ``TypeCodec`` base class: + +.. code-block:: python + + from bson.decimal128 import Decimal128 + from bson.codec_options import TypeCodec + + class DecimalCodec(TypeCodec): + python_type = Decimal + bson_type = Decimal128 + + def transform_python(self, value): + return Decimal128(value) + + def transform_bson(self, value): + return value.to_decimal() + +Add Codec to the Type Registry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After defining a custom type codec, you must add it to {+driver-short+}'s **type registry**, +the list of types the driver can encode and decode. +To do so, create an instance of the ``TypeRegistry`` class, passing in an instance +of your type codec class inside a list. If you create multiple custom codecs, you can +pass them all to the ``TypeRegistry`` constructor. + +The following code examples adds an instance of the ``DecimalCodec`` type codec to +the type registry: + +.. code-block:: python + + from bson.codec_options import TypeRegistry + + decimal_codec = DecimalCodec() + type_registry = TypeRegistry([decimal_codec]) + +.. note:: + + Once instantiated, registries are immutable and the only way to add codecs + to a registry is to create a new one. + +Get a Collection Reference +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Finally, define a ``codec_options.CodecOptions`` instance, passing your ``TypeRegistry`` +object as a keyword argument. Pass your ``CodecOptions`` object to the +``get_collection()`` method to obtain a collection that can use your custom type: + +.. code-block:: python + + from bson.codec_options import CodecOptions + + codec_options = CodecOptions(type_registry=type_registry) + collection = db.get_collection("test", codec_options=codec_options) + +You can then encode and decode instances of the ``Decimal`` class. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + + collection.insert_one({"num": Decimal("45.321")}) + my_doc = collection.find_one() + pprint.pprint(my_doc) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal('45.321')} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + + await collection.insert_one({"num": Decimal("45.321")}) + my_doc = await collection.find_one() + pprint.pprint(my_doc) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal('45.321')} + +To see how MongoDB stores an instance of the custom type, +create a new collection object without the customized codec options, then use it +to retrieve the document containing the custom type. The following example shows +that {+driver-short+} stores an instance of the ``Decimal`` class as a ``Decimal128`` +value. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + + new_collection = db.get_collection("test") + pprint.pprint(new_collection.find_one()) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal128('45.321')} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + + new_collection = db.get_collection("test") + pprint.pprint(await new_collection.find_one()) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal128('45.321')} + +Encode a Subtype +---------------- + +You might also need to encode one or more types that inherit from your custom type. +Consider the following subtype of the ``Decimal`` class, which contains a method to +return its value as an integer: + +.. code-block:: python + + class DecimalInt(Decimal): + def get_int(self): + return int(self) + +If you try to save an instance of the ``DecimalInt`` class without first registering a type +codec for it, {+driver-short+} raises an error. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + collection.insert_one({"num": DecimalInt("45.321")}) + + .. output:: + :language: shell + + Traceback (most recent call last): + ... + bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), + of type: + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + await collection.insert_one({"num": DecimalInt("45.321")}) + + .. output:: + :language: shell + + Traceback (most recent call last): + ... + bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), + of type: + +To encode an instance of the ``DecimalInt`` class, you must define a type codec for +the class. This type codec must inherit from the parent class's codec, ``DecimalCodec``, +as shown in the following example: + +.. code-block:: python + + class DecimalIntCodec(DecimalCodec): + @property + def python_type(self): + # The Python type encoded by this type codec + return DecimalInt + +You can then add the subclass's type codec to the type registry and encode instances +of the custom type. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + from bson.codec_options import CodecOptions + + decimal_int_codec = DecimalIntCodec() + type_registry = TypeRegistry([decimal_codec, decimal_int_codec]) + codec_options = CodecOptions(type_registry=type_registry) + + collection = db.get_collection("test", codec_options=codec_options) + collection.insert_one({"num": DecimalInt("45.321")}) + + my_doc = collection.find_one() + pprint.pprint(my_doc) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal('45.321')} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + from bson.codec_options import CodecOptions + + decimal_int_codec = DecimalIntCodec() + type_registry = TypeRegistry([decimal_codec, decimal_int_codec]) + codec_options = CodecOptions(type_registry=type_registry) + + collection = db.get_collection("test", codec_options=codec_options) + await collection.insert_one({"num": DecimalInt("45.321")}) + + my_doc = await collection.find_one() + pprint.pprint(my_doc) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal('45.321')} + +.. note:: + + The ``transform_bson()`` method of the ``DecimalCodec`` class results in + these values being decoded as ``Decimal``, not ``DecimalInt``. + +Define a Fallback Encoder +------------------------- + +You can also register a **fallback encoder**, a callable to encode types not recognized +by BSON and for which no type codec has been registered. +The fallback encoder accepts an unencodable +value as a parameter and returns a BSON-encodable value. + +The following fallback encoder encodes Python's ``Decimal`` type to a ``Decimal128``: + +.. code-block:: python + + def fallback_encoder(value): + if isinstance(value, Decimal): + return Decimal128(value) + return value + +After declaring a fallback encoder, perform the following steps: + +- Construct a new instance of the ``TypeRegistry`` class. Use the ``fallback_encoder`` + keyword argument to pass in the fallback encoder. +- Construct a new instance of the ``CodecOptions`` class. Use the ``type_registry`` + keyword argument to pass in the ``TypeRegistry`` instance. +- Call the ``get_collection()`` method. Use the ``codec_options`` keyword argument + to pass in the ``CodecOptions`` instance. + +The following code example shows this process: + +.. code-block:: python + + type_registry = TypeRegistry(fallback_encoder=fallback_encoder) + codec_options = CodecOptions(type_registry=type_registry) + collection = db.get_collection("test", codec_options=codec_options) + +You can then use this reference to a collection to store instances of the ``Decimal`` +class. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + + collection.insert_one({"num": Decimal("45.321")}) + my_doc = collection.find_one() + pprint.pprint(my_doc) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal128('45.321')} + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + import pprint + + await collection.insert_one({"num": Decimal("45.321")}) + my_doc = await collection.find_one() + pprint.pprint(my_doc) + + .. output:: + :language: shell + + {'_id': ObjectId('...'), 'num': Decimal128('45.321')} + +.. note:: + + Fallback encoders are invoked *after* attempts to encode the given value + with standard BSON encoders and any configured type encoders have failed. + Therefore, in a type registry configured with a type encoder and fallback + encoder that both target the same custom type, the behavior specified in + the type encoder takes precedence. + +Encode Unknown Types +~~~~~~~~~~~~~~~~~~~~ +.. TODO: consider new example + +Because fallback encoders don't need to declare the types that they encode +beforehand, you can use them in cases where a ``TypeEncoder`` doesn't work. +For example, you can use a fallback encoder to save arbitrary objects to MongoDB. +Consider the following arbitrary custom types: + +.. code-block:: python + + class MyStringType(object): + def __init__(self, value): + self.__value = value + + def __repr__(self): + return "MyStringType('%s')" % (self.__value,) + + + class MyNumberType(object): + def __init__(self, value): + self.__value = value + + def __repr__(self): + return "MyNumberType(%s)" % (self.__value,) + +You can define a fallback encoder that pickles the objects it receives +and returns them as ``Binary`` instances with a custom +subtype. This custom subtype allows you to define a ``TypeDecoder`` class that +identifies pickled artifacts upon retrieval and transparently decodes them +back into Python objects: + +.. code-block:: python + + import pickle + from bson.binary import Binary, USER_DEFINED_SUBTYPE + from bson.codec_options import TypeDecoder + + def fallback_pickle_encoder(value): + return Binary(pickle.dumps(value), USER_DEFINED_SUBTYPE) + + class PickledBinaryDecoder(TypeDecoder): + bson_type = Binary + + def transform_bson(self, value): + if value.subtype == USER_DEFINED_SUBTYPE: + return pickle.loads(value) + return value + +You can then add the ``PickledBinaryDecoder`` to the codec options for a collection +and use it to encode and decode your custom types. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + from bson.codec_options import CodecOptions,TypeRegistry + + codec_options = CodecOptions( + type_registry=TypeRegistry( + [PickledBinaryDecoder()], fallback_encoder=fallback_pickle_encoder + ) + ) + + collection = db.get_collection("test", codec_options=codec_options) + collection.insert_one( + {"_id": 1, "str": MyStringType("hello world"), "num": MyNumberType(2)} + ) + my_doc = collection.find_one() + + print(isinstance(my_doc["str"], MyStringType)) + print(isinstance(my_doc["num"], MyNumberType)) + + .. output:: + :language: shell + + True + True + + .. tab:: Asynchronous + :tabid: async + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + from bson.codec_options import CodecOptions,TypeRegistry + + codec_options = CodecOptions( + type_registry=TypeRegistry( + [PickledBinaryDecoder()], fallback_encoder=fallback_pickle_encoder + ) + ) + + collection = db.get_collection("test", codec_options=codec_options) + await collection.insert_one( + {"_id": 1, "str": MyStringType("hello world"), "num": MyNumberType(2)} + ) + my_doc = await collection.find_one() + + print(isinstance(my_doc["str"], MyStringType)) + print(isinstance(my_doc["num"], MyNumberType)) + + .. output:: + :language: shell + + True + True + +Limitations +----------- + +{+driver-short+} type codecs and fallback encoders have the following +limitations: + +- You can't customize the encoding behavior of Python types that {+driver-short+} + already understands, like ``int`` and ``str``. + If you try to instantiate a type registry with one or more codecs that act + upon a built-in type, {+driver-short+} raises a ``TypeError``. This limitation also + applies to all subtypes of the standard types. + +- You can't chain type encoders. A custom type value, once + transformed by a codec's ``transform_python()`` method, *must* result in a + type that is either BSON-encodable by default, or can be + transformed by the fallback encoder into something BSON-encodable. It + *cannot* be transformed a second time by a different type codec. + +- The ``Database.command()`` method doesn't apply custom + type decoders while decoding the command response document. + +- The ``gridfs`` class doesn't apply custom type encoding or decoding to any + documents it receives or returns. + +API Documentation +----------------- + +For more information about encoding and decoding custom types, +see the following API documentation: + +- `TypeCodec <{+api-root+}bson/codec_options.html#bson.codec_options.TypeCodec>`__ +- `TypeEncoder <{+api-root+}bson/codec_options.html#bson.codec_options.TypeEncoder>`__ +- `TypeDecoder <{+api-root+}bson/codec_options.html#bson.codec_options.TypeDecoder>`__ +- `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__ +- `CodecOptions <{+api-root+}bson/codec_options.html#bson.codec_options.CodecOptions>`__ \ No newline at end of file diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt index f553f829..2cf868ba 100644 --- a/source/data-formats/time-series.txt +++ b/source/data-formats/time-series.txt @@ -253,7 +253,7 @@ Query Time Series Data You can use the same syntax and conventions to query data stored in a time series collection as you use when performing read or aggregation operations on -other collections. To learn more about these operations, see :ref:`pymongo-read` +other collections. To learn more about these operations, see :ref:`pymongo-query` and :ref:`pymongo-aggregation`. .. _pymongo-time-series-addtl-info: diff --git a/source/databases-collections.txt b/source/databases-collections.txt index f50ca2cf..275c7a9a 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -113,25 +113,6 @@ document count. The following example creates a capped collection called To learn more about capped collections, see :manual:`Capped Collections ` in the {+mdb-server+} manual. -Collation -~~~~~~~~~ - -When you create a collection, you can specify a default **collation** for all operations -you perform on the collection. - -.. include:: /includes/collation-description.rst - -The following example creates the same collection as the previous example, -but with a default collation of ``fr_CA``: - -.. code-block:: python - :emphasize-lines: 4 - - from pymongo.collation import Collation - - database = client["test_database"] - database.create_collection("example_collection", collation=Collation(locale='fr_CA')) - Get a List of Collections ------------------------- @@ -181,146 +162,6 @@ The following example deletes the ``test_collection`` collection: Drop a collection only if the data in it is no longer needed. -.. _pymongo-config-read-write: - -Configure Read and Write Operations ------------------------------------ - -You can control how the driver routes read operations by setting a **read preference**. -You can also control options for how the driver waits for acknowledgment of -read and write operations on a replica set by setting a **read concern** and a -**write concern**. - -By default, databases inherit these settings from the ``MongoClient`` instance, -and collections inherit them from the database. However, you can change these -settings on your database or collection by using one of the following methods: - -- ``get_database()``: Gets the database and applies the client's read - preference, read concern, and write preference. -- ``database.with_options()``: Gets the database and applies its current read - preference, read concern, and write preference. -- ``get_collection()``: Gets the collection and applies its current read preference, read concern, and write preference. -- ``collection.with_options()``: Gets the collection and applies the database's read - preference, read concern, and write preference. - -To change read or write settings with the preceding methods, call the method and -pass in the collection or database name, and the new read preference, read -concern, or write preference. - -The following example shows how to change the read preference, read concern and -write preference of a database called ``test-database`` with the ``get_database()`` method: - -.. code-block:: python - - client.get_database("test-database", - read_preference=ReadPreference.SECONDARY, - read_concern="local", - write_concern="majority") - -The following example shows how to change read and write settings of a -collection called ``test-collection`` with the ``get_collection()`` method: - -.. code-block:: python - - database.get_collection("test-collection", - read_preference=ReadPreference.SECONDARY, - read_concern="local", - write_concern="majority") - -The following example shows how to change read and write settings of a -collection called ``test-collection`` with the ``with_options()`` method: - -.. code-block:: python - - collection.with_options(read_preference=ReadPreference.SECONDARY, - read_concern="local", - write_concern="majority") - -.. tip:: - - To see the types of read preferences available in the ``ReadPreference`` enum, see the - `API documentation <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.ReadPreference>`__. - -To learn more about the read and write settings, see the following guides in the -MongoDB Server manual: - -- :manual:`Read Preference ` -- :manual:`Read Concern ` -- :manual:`Write Concern ` - -Tag Sets -~~~~~~~~ - -In {+mdb-server+}, you can apply key-value :manual:`tags -` to replica-set -members according to any criteria you choose. You can then use -those tags to target one or more members for a read operation. - -By default, {+driver-short+} ignores tags -when choosing a member to read from. To instruct {+driver-short+} -to prefer certain tags, pass them as a parameter to your -`read preference class <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.Primary>`__ -constructor. - -In the following code example, the tag set passed to the ``read_preference`` parameter -instructs {+driver-short+} to prefer reads from the -New York data center (``'dc': 'ny'``) and to fall back to the San Francisco data -center (``'dc': 'sf'``): - -.. code-block:: python - - db = client.get_database( - 'test', read_preference=Secondary([{'dc': 'ny'}, {'dc': 'sf'}])) - -Local Threshold -~~~~~~~~~~~~~~~ - -If multiple replica-set members match the read preference and tag sets you specify, -{+driver-short+} reads from the nearest replica-set members, chosen according to -their ping time. - -By default, the driver uses only those members whose ping times are within 15 milliseconds -of the nearest member for queries. To distribute reads between members with -higher latencies, pass the ``localThresholdMS`` option to the ``MongoClient()`` constructor. - -The following example specifies a local threshold of 35 milliseconds: - -.. code-block:: python - :emphasize-lines: 3 - - client = MongoClient(replicaSet='repl0', - readPreference=ReadPreference.SECONDARY_PREFERRED, - localThresholdMS=35) - -In the preceding example, {+driver-short+} distributes reads between matching members -within 35 milliseconds of the closest member's ping time. - -.. note:: - - {+driver-short+} ignores the value of ``localThresholdMS`` when communicating with a - replica set through a ``mongos`` instance. In this case, use the - :manual:`localThreshold ` - command-line option. - -Retryable Reads and Writes -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -{+driver-short+} automatically retries certain read and write operations a single time -if they fail due to a network or server error. - -You can explicitly disable retryable reads or retryable writes by setting the ``retryReads`` or -``retryWrites`` option to ``False`` in the ``MongoClient()`` constructor. The following -example disables retryable reads and writes for a client: - -.. code-block:: python - - client = MongoClient("", - retryReads=False, retryWrites=False) - -To learn more about supported retryable read operations, see :manual:`Retryable Reads ` -in the {+mdb-server+} manual. To learn more about supported retryable write -operations, see :manual:`Retryable Writes ` in the {+mdb-server+} manual. - .. _pymongo-databases-collection-type-hints: Type Hints diff --git a/source/get-started.txt b/source/get-started.txt index b4b06ecf..57349bdb 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -18,14 +18,6 @@ Get Started with {+driver-short+} :description: Learn how to create an app to connect to MongoDB deployment by using the PyMongo driver. :keywords: quick start, tutorial, basics -.. toctree:: - - Download & Install - Create a Deployment - Create a Connection String - Run a Sample Query - Next Steps - Overview -------- @@ -43,3 +35,251 @@ MongoDB Atlas. Follow this guide to connect a sample Python application to a MongoDB Atlas deployment. If you prefer to connect to MongoDB using a different driver or programming language, see our :driver:`list of official drivers <>`. + +.. _pymongo-get-started-download-and-install: + +Download and Install +-------------------- + +.. note:: Alternative Installation Methods + + The following steps show you how to install {+driver-short+} by using + `pip `__. To install + {+driver-short+} from source, see + `Install from Source `__ + in the API documentation. + +.. procedure:: + :style: connected + + .. step:: Install dependencies + + Ensure you have the following dependencies installed + in your development environment: + + - `Python3 version 3.8 or later `__ + - `pip `__ + - `dnspython `__ + + .. step:: Create a project directory + + In your shell, run the following command to create a + directory called ``pymongo-quickstart`` for this project: + + .. code-block:: bash + + mkdir pymongo-quickstart + + Select the tab corresponding to your operating system and run the following commands + to create a ``quickstart.py`` application file in the ``pymongo-quickstart`` directory: + + .. tabs:: + + .. tab:: macOS / Linux + :tabid: create-file-mac-linux + + .. code-block:: bash + + cd pymongo-quickstart + touch quickstart.py + + .. tab:: Windows + :tabid: create-file-windows + + .. code-block:: bash + + cd pymongo-quickstart + type nul > quickstart.py + + .. step:: Install {+driver-short+} + + Select the tab corresponding to your operating system and run the following commands + to create and activate a virtual environment in which to install the driver: + + .. tabs:: + + .. tab:: macOS / Linux + :tabid: venv-mac-linux + + .. code-block:: bash + + python3 -m venv venv + source venv/bin/activate + + .. tab:: Windows + :tabid: venv-windows + + .. code-block:: bash + + python3 -m venv venv + . venv\Scripts\activate + + With the virtual environment activated, run the following command to + install the current version of {+driver-short+}: + + .. code-block:: bash + + python3 -m pip install pymongo + +After you complete these steps, you have a new project directory +and the driver dependencies installed. + +.. _pymongo-get-started-create-deployment: + +Create a MongoDB Deployment +--------------------------- + +You can create a free-tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a free MongoDB deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and load sample data into a new free + tier MongoDB deployment. + + .. step:: Save your credentials + + After you create your database user, save that user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +in your database. + +.. _pymongo-get-started-connection-string: + +Create a Connection String +-------------------------- + +You can connect to your MongoDB deployment by providing a +**connection URI**, also called a *connection string*, which +instructs the driver on how to connect to a MongoDB deployment +and how to behave while connected. + +The connection string includes the hostname or IP address and +port of your deployment, the authentication mechanism, user credentials +when applicable, and connection options. + +To connect to an instance or deployment not hosted on Atlas, see +:ref:`pymongo-connection-targets`. + +.. procedure:: + :style: connected + + .. step:: Find your MongoDB Atlas connection string + + To retrieve your connection string for the deployment that + you created in the :ref:`previous step `, + log into your Atlas account and navigate to the + :guilabel:`Database` section and click the :guilabel:`Connect` button + for your new deployment. + + .. figure:: /includes/figures/atlas_connection_select_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Proceed to the :guilabel:`Connect your application` section and select + "Python" from the :guilabel:`Driver` selection menu and the version + that best matches the version you installed from the :guilabel:`Version` + selection menu. + + Select the :guilabel:`Password (SCRAM)` authentication mechanism. + + Deselect the :guilabel:`Include full driver code example` option to view + the connection string. + + .. step:: Copy your connection string + + Click the button on the right of the connection string to copy it to + your clipboard as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_copy_string_python.png + :alt: The connection string copy button in the Atlas UI + + .. step:: Update the placeholders + + Paste this connection string into a file in your preferred text editor + and replace the ```` and ```` placeholders with + your database user's username and password. + + Save this file to a safe location for use in the next step. + +After completing these steps, you have a connection string that +contains your database username and password. + +.. _pymongo-get-started-connect-to-mongodb: + +Connect to MongoDB +------------------ + +.. procedure:: + :style: connected + + .. step:: Create your {+driver-short+} application + + Copy and paste the following code into the ``quickstart.py`` file in your application: + + .. literalinclude:: /includes/get-started/connect-and-query.py + :language: python + :copyable: + + .. step:: Assign the connection string + + Replace the ```` placeholder with the + connection string that you copied from the :ref:`pymongo-get-started-connection-string` + step of this guide. + + .. step:: Run your application + + In your shell, run the following command to start this application: + + .. code-block:: sh + + python3 quickstart.py + + The output includes details of the retrieved movie document: + + .. code-block:: none + + { + _id: ..., + plot: 'A young man is accidentally sent 30 years into the past...', + genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], + ... + title: 'Back to the Future', + ... + } + + .. tip:: + + If you encounter an error or see no output, check whether you specified the + proper connection string, and that you loaded the + sample data. + +After you complete these steps, you have a working application that +uses the driver to connect to your MongoDB deployment, runs a query on +the sample data, and prints out the result. + +.. _pymongo-get-started-next-steps: + +Next Steps +---------- + +Congratulations on completing the tutorial! + +In this tutorial, you created a Python application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +Learn more about {+driver-short+} from the following resources: + +- Learn how to insert documents in the :ref:`` section. +- Learn how to find documents in the :ref:`` section. +- Learn how to update documents in the :ref:`` section. +- Learn how to delete documents in the :ref:`` section. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt deleted file mode 100644 index c936d8a0..00000000 --- a/source/get-started/create-a-connection-string.txt +++ /dev/null @@ -1,62 +0,0 @@ -.. _pymongo-get-started-connection-string: - -========================== -Create a Connection String -========================== - -You can connect to your MongoDB deployment by providing a -**connection URI**, also called a *connection string*, which -instructs the driver on how to connect to a MongoDB deployment -and how to behave while connected. - -The connection string includes the hostname or IP address and -port of your deployment, the authentication mechanism, user credentials -when applicable, and connection options. - -To connect to an instance or deployment not hosted on Atlas, see -:ref:`pymongo-connection-targets`. - -.. procedure:: - :style: connected - - .. step:: Find your MongoDB Atlas Connection String - - To retrieve your connection string for the deployment that - you created in the :ref:`previous step `, - log into your Atlas account and navigate to the - :guilabel:`Database` section and click the :guilabel:`Connect` button - for your new deployment. - - .. figure:: /includes/figures/atlas_connection_select_cluster.png - :alt: The connect button in the clusters section of the Atlas UI - - Proceed to the :guilabel:`Connect your application` section and select - "Python" from the :guilabel:`Driver` selection menu and the version - that best matches the version you installed from the :guilabel:`Version` - selection menu. - - Select the :guilabel:`Password (SCRAM)` authentication mechanism. - - Deselect the :guilabel:`Include full driver code example` option to view - the connection string. - - .. step:: Copy your Connection String - - Click the button on the right of the connection string to copy it to - your clipboard as shown in the following screenshot: - - .. figure:: /includes/figures/atlas_connection_copy_string_python.png - :alt: The connection string copy button in the Atlas UI - - .. step:: Update the Placeholders - - Paste this connection string into a file in your preferred text editor - and replace the ```` and ```` placeholders with - your database user's username and password. - - Save this file to a safe location for use in the next step. - -After completing these steps, you have a connection string that -contains your database username and password. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt deleted file mode 100644 index 69c9eb74..00000000 --- a/source/get-started/create-a-deployment.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. _pymongo-get-started-create-deployment: - -=========================== -Create a MongoDB Deployment -=========================== - -You can create a free tier MongoDB deployment on MongoDB Atlas -to store and manage your data. MongoDB Atlas hosts and manages -your MongoDB database in the cloud. - -.. procedure:: - :style: connected - - .. step:: Create a Free MongoDB deployment on Atlas - - Complete the :atlas:`Get Started with Atlas ` - guide to set up a new Atlas account and load sample data into a new free - tier MongoDB deployment. - - .. step:: Save your Credentials - - After you create your database user, save that user's - username and password to a safe location for use in an upcoming step. - -After you complete these steps, you have a new free tier MongoDB -deployment on Atlas, database user credentials, and sample data loaded -in your database. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt deleted file mode 100644 index c1dc27e5..00000000 --- a/source/get-started/download-and-install.txt +++ /dev/null @@ -1,89 +0,0 @@ -.. _pymongo-get-started-download-and-install: - -==================== -Download and Install -==================== - -.. note:: Alternative Installation Methods - - The following guide shows you how to install {+driver-short+} by using - `pip `__. To install - {+driver-short+} from source, see `Install from Source `__ - in the API Documentation. - -.. procedure:: - :style: connected - - .. step:: Install Dependencies - - Ensure you have the following dependencies installed - in your development environment: - - - `Python3 version 3.8 or later `__ - - `pip `__ - - `dnspython `__ - - .. step:: Create a Project Directory - - In your shell, run the following command to create a - directory called ``pymongo-quickstart`` for this project: - - .. code-block:: bash - - mkdir pymongo-quickstart - - Select the tab corresponding to your operating system and run the following commands - to create a ``quickstart.py`` application file in the ``pymongo-quickstart`` directory: - - .. tabs:: - - .. tab:: macOS / Linux - :tabid: create-file-mac-linux - - .. code-block:: bash - - cd pymongo-quickstart - touch quickstart.py - - .. tab:: Windows - :tabid: create-file-windows - - .. code-block:: bash - - cd pymongo-quickstart - type nul > quickstart.py - - .. step:: Install {+driver-short+} - - Select the tab corresponding to your operating system and run the following commands - to create and activate a virtual environment in which to install the driver: - - .. tabs:: - - .. tab:: macOS / Linux - :tabid: venv-mac-linux - - .. code-block:: bash - - python3 -m venv venv - source venv/bin/activate - - .. tab:: Windows - :tabid: venv-windows - - .. code-block:: bash - - python3 -m venv venv - . venv\Scripts\activate - - With the virtual environment activated, run the following command to - install the current version of {+driver-short+}: - - .. code-block:: bash - - python3 -m pip install pymongo - -After you complete these steps, you have a new project directory -and the driver dependencies installed. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt deleted file mode 100644 index e018951b..00000000 --- a/source/get-started/next-steps.txt +++ /dev/null @@ -1,16 +0,0 @@ -.. _pymongo-get-started-next-steps: - -========== -Next Steps -========== - -Congratulations on completing the tutorial! - -In this tutorial, you created a Python application that -connects to a MongoDB deployment hosted on MongoDB Atlas -and retrieves a document that matches a query. - -Learn more about {+driver-short+} from the following resources: - -- Learn how to perform read operations in the :ref:`` section. -- Learn how to perform write operations in the :ref:`` section. diff --git a/source/get-started/run-sample-query.txt b/source/get-started/run-sample-query.txt deleted file mode 100644 index fa12ac4e..00000000 --- a/source/get-started/run-sample-query.txt +++ /dev/null @@ -1,56 +0,0 @@ -.. _pymongo-get-started-run-sample-query: -.. _pymongo-get-started-connect-to-mongodb: - -================== -Run a Sample Query -================== - -.. procedure:: - :style: connected - - .. step:: Create your {+driver-short+} Application - - Copy and paste the following code into the ``quickstart.py`` file in your application: - - .. literalinclude:: /includes/get-started/connect-and-query.py - :language: python - :copyable: - - .. step:: Assign the Connection String - - Replace the ```` placeholder with the - connection string that you copied from the :ref:`pymongo-get-started-connection-string` - step of this guide. - - .. step:: Run your Application - - In your shell, run the following command to start this application: - - .. code-block:: sh - - python3 quickstart.py - - The output includes details of the retrieved movie document: - - .. code-block:: none - - { - _id: ..., - plot: 'A young man is accidentally sent 30 years into the past...', - genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], - ... - title: 'Back to the Future', - ... - } - - .. tip:: - - If you encounter an error or see no output, check whether you specified the - proper connection string, and that you loaded the - sample data. - -After you complete these steps, you have a working application that -uses the driver to connect to your MongoDB deployment, runs a query on -the sample data, and prints out the result. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/includes/aggregation-tutorial-intro.rst b/source/includes/aggregation-tutorial-intro.rst new file mode 100644 index 00000000..43a43e3a --- /dev/null +++ b/source/includes/aggregation-tutorial-intro.rst @@ -0,0 +1,45 @@ +Before you begin following an aggregation tutorial, you must set up a +new Python app. You can use this app to connect to a MongoDB +deployment, insert sample data into MongoDB, and run the aggregation +pipeline in each tutorial. + +.. tip:: + + To learn how to install the driver and connect to MongoDB, + see :ref:`pymongo-get-started` + +Once you install the driver, create a file called +``agg_tutorial.py``. Paste the following code in this file to create an +app template for the aggregation tutorials: + +.. literalinclude:: /includes/aggregation/template-app.py + :language: python + :copyable: true + +.. important:: + + In the preceding code, read the code comments to find the sections of + the code that you must modify for the tutorial you are following. + + If you attempt to run the code without making any changes, you will + encounter a connection error. + +For every tutorial, you must replace the connection string placeholder with +your deployment's connection string. To learn how to locate your deployment's connection +string, see :ref:`pymongo-get-started-connection-string`. + +For example, if your connection string is +``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles +the following: + +.. code-block:: python + :copyable: false + + uri = "mongodb+srv://mongodb-example:27017"; + +To run the completed file after you modify the template for a +tutorial, run the following command in your shell: + +.. code-block:: bash + + python3 agg_tutorial.py \ No newline at end of file diff --git a/source/includes/language-compatibility-table-pymongo.rst b/source/includes/language-compatibility-table-pymongo.rst index 6c0cefc4..40ff5b4d 100644 --- a/source/includes/language-compatibility-table-pymongo.rst +++ b/source/includes/language-compatibility-table-pymongo.rst @@ -303,8 +303,53 @@ as binary data with subtype 0, the default subtype for binary data. In Python 3, {+driver-short+} decodes these values to instances of the ``bytes`` class. In Python 2, the driver decodes them to instances of the `Binary `__ -class with subtype 0. For code examples that show the differences, see the -:ref:`Extended JSON ` page. +class with subtype 0. + +The following code examples show how {+driver-short+} decodes instances of the ``bytes`` +class. Select the :guilabel:`Python 2` or :guilabel:`Python 3` tab to view the corresponding +code. + +.. tabs:: + + .. tab:: Python 2 + :tabid: python2 + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + from pymongo import MongoClient + + client = MongoClient() + client.test.test.insert_one({'binary': b'this is a byte string'}) + doc = client.test.test.find_one() + print(doc) + + .. output:: + + {u'_id': ObjectId('67afb78298f604a28f0247b4'), u'binary': Binary('this is a byte string', 0)} + + .. tab:: Python 3 + :tabid: python3 + + .. io-code-block:: + :copyable: true + + .. input:: + :language: python + + from pymongo import MongoClient + + client = MongoClient() + client.test.test.insert_one({'binary': b'this is a byte string'}) + doc = client.test.test.find_one() + print(doc) + + .. output:: + + {'_id': ObjectId('67afb78298f604a28f0247b4'), 'binary': b'this is a byte string'} The driver behaves the same way when decoding JSON binary values with subtype 0. In Python 3, it decodes these values to instances of the ``bytes`` class. In Python 2, diff --git a/source/includes/usage-examples/sample-app.py b/source/includes/usage-examples/crud-sample-app.py similarity index 100% rename from source/includes/usage-examples/sample-app.py rename to source/includes/usage-examples/crud-sample-app.py diff --git a/source/index.txt b/source/index.txt index 60e76d5f..2214ec32 100644 --- a/source/index.txt +++ b/source/index.txt @@ -15,25 +15,19 @@ MongoDB {+driver-short+} Documentation Get Started Connect Databases & Collections - Write Data - Read Data - Run a Database Command - Indexes + CRUD Operations Aggregation - Security Data Formats - Logging - Monitoring - Serialization - Third-Party Tools - What's New - Upgrade - Migrate from Motor - Switch to PyMongo Async - Previous Versions - Issues & Help - Compatibility + Indexes + Run a Database Command + Atlas Search + Atlas Vector Search + Monitoring and Logging + Security + Third-Party Integrations + Reference API Documentation <{+api-root+}> + Issues & Help Overview -------- @@ -60,26 +54,10 @@ Databases and Collections Learn how to use {+driver-short+} to work with MongoDB databases and collections in the :ref:`pymongo-databases-collections` section. -Write Data to MongoDB ---------------------- - -Learn how you can write data to MongoDB in the :ref:`pymongo-write` section. - -Read Data ---------- - -Learn how you can retrieve data from MongoDB in the :ref:`pymongo-read` section. - -Run a Database Command ----------------------- - -Learn how to run a database command in the :ref:`pymongo-run-command` section. - -Optimize Queries with Indexes ------------------------------ +Read and Write Data +------------------- -Learn how to work with common types of indexes in the :ref:`pymongo-indexes` -section. +Learn how to find, update, and delete data in the :ref:`pymongo-crud` section. Transform Your Data with Aggregation ------------------------------------ @@ -87,88 +65,63 @@ Transform Your Data with Aggregation Learn how to use {+driver-short+} to perform aggregation operations in the :ref:`pymongo-aggregation` section. -Secure Your Data ----------------- - -Learn about ways you can authenticate your application and encrypt your data in -the :ref:`pymongo-security` section. - -Specialized Data Formats ------------------------- +Data Formats +------------ Learn how to work with specialized data formats and custom types in the :ref:`pymongo-data-formats` section. -Logging -------- - -Learn how to configure logging in the :ref:`pymongo-logging` section. - -Monitoring ----------- +Optimize Queries with Indexes +----------------------------- -Learn how to monitor changes to your application in the :ref:`pymongo-monitoring` section. +Learn how to work with common types of indexes in the :ref:`pymongo-indexes` +section. -Serialization -------------- +Run a Database Command +---------------------- -Learn how {+driver-short+} serializes and deserializes data in the -:ref:`pymongo-serialization` section. +Learn how to run a database command in the :ref:`pymongo-run-command` section. -Third-Party Tools ------------------ +Atlas Search +------------ -For a list of popular third-party Python libraries for working with -MongoDB, see the :ref:`pymongo-tools` section. +Learn how to use Atlas Search to build full-text search capabilities in the +`Atlas Search tutorial `__. -What's New ----------- +Atlas Vector Search +------------------- -For a list of new features and changes in each version, see the :ref:`` -section. +Learn how to use Atlas Vector Search to query your Atlas data based on semantic meaning +rather than keyword matches in the +`Atlas Vector Search `__ +documentation. -Upgrade {+driver-short+} Versions ------------------------- +Monitoring and Logging +---------------------- -Learn what changes you might need to make to your application to upgrade driver versions -in the :ref:`pymongo-upgrade` section. +Learn how to monitor changes to your application and write them to logs in the +:ref:`pymongo-logging-monitoring` section. -Migrate from Motor to {+driver-async+} -------------------------------------- +Secure Your Data +---------------- -In September 2024, MongoDB released the experimental {+driver-async+} driver as a replacement -for `Motor `__, the previous asynchronous -MongoDB driver for Python. Learn how to migrate from Motor -to the {+driver-async+} driver in the :ref:`pymongo-async-motor-migration` -section. +Learn about ways you can authenticate your application and encrypt your data in +the :ref:`pymongo-security` section. -Switch from {+driver-short+} to {+driver-async+} ----------------------------------------------- +Reference +--------- -Learn what changes you need to make to switch from {+driver-short+} to -the experimental {+driver-async+} driver in the :ref:`pymongo-to-async-guide` section. +Find more information about {+driver-short+} versions, compatibility, and third-party tools +in the :ref:`pymongo-reference` section. -Previous Versions +API Documentation ----------------- -For documentation on versions of the driver v4.6.x and earlier, see the -:ref:`pymongo-previous-versions` section. +For detailed information about types and methods in {+driver-short+}, see +the `{+driver-short+} API documentation <{+api-root+}>`__. Issues & Help ------------- Learn how to report bugs, contribute to the driver, and find help in the -:ref:`` section. - -Compatibility -------------- - -For compatibility tables that show the recommended {+driver-short+} -version to use for specific Python and {+mdb-server+} versions, see the -:ref:`pymongo-compatibility` section. - -API Documentation ------------------ - -For detailed information about types and methods in {+driver-short+}, see -the `{+driver-short+} API documentation <{+api-root+}>`__. +:ref:`` section. \ No newline at end of file diff --git a/source/indexes.txt b/source/indexes.txt index 3ed60759..8e56da5c 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -1,8 +1,9 @@ +.. _pymongo-work-with-indexes: .. _pymongo-indexes: -============================= -Optimize Queries with Indexes -============================= +======= +Indexes +======= .. contents:: On this page :local: @@ -18,198 +19,531 @@ Optimize Queries with Indexes :description: Learn how to use indexes with the MongoDB {+driver-short+} driver. :keywords: query, optimization, efficiency, usage example, code example -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Work with Indexes - Overview -------- -On this page, you can see copyable code examples that show how to work with common -types of indexes that you can use with {+driver-short+}. +In this guide, you can learn how to use **indexes** with {+driver-short+}. +Indexes can improve the efficiency of queries and add additional functionality +to querying and storing documents. -.. tip:: +Without indexes, MongoDB must scan every document in a collection to find the +documents that match each query. These collection scans are +slow and can negatively affect the performance of your application. However, if an +appropriate index exists for a query, MongoDB can use the index to limit the +documents it must inspect. + +Operational Considerations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To improve query performance, build indexes on fields that appear often in +your application's queries and operations that return sorted results. Each +index that you add consumes disk space and memory when active, so we recommend +that you track index memory and disk usage for capacity planning. In addition, +when a write operation updates an indexed field, MongoDB updates the related +index. + +Because MongoDB supports dynamic schemas, applications can query against fields +whose names are not known in advance or are arbitrary. MongoDB 4.2 introduced +:manual:`wildcard indexes ` to help support these +queries. Wildcard indexes are not designed to replace workload-based index +planning. + +For more information about designing your data model and choosing indexes appropriate for your application, see the +:manual:`Data Modeling and Indexes ` guide +in the {+mdb-server+} manual. + +Sample Data +~~~~~~~~~~~ - To learn more about working with indexes, see the :ref:`pymongo-work-with-indexes` - guide. To learn more about any of the indexes shown on this page, see the link - provided in each section. +The examples in this guide use the ``sample_mflix.movies`` collection +from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:ref:``. -To use an example from this page, copy the code example into the -:ref:`sample application ` or your own application. -Be sure to replace all placeholders in the code examples, such as ````, with -the relevant values for your MongoDB deployment. +Index Types +----------- -.. _pymongo-index-sample: +.. _pymongo-single-field-index: -.. include:: /includes/usage-examples/sample-app-intro.rst +Single Field and Compound Indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. literalinclude:: /includes/usage-examples/sample-app.py +Single Field Indexes +```````````````````` + +:manual:`Single field indexes ` are indexes with a reference to a +single field within a collection's documents. They improve single field query and sort +performance, and support :manual:`TTL Indexes ` that +automatically remove documents from a collection after a certain amount of time or at a +specific clock time. + +.. note:: + + The ``_id_`` index is an example of a single field index. This index is automatically + created on the ``_id`` field when a new collection is created. + +The following example creates an index in ascending order on the ``title`` field: + +.. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-single + :end-before: end-index-single :language: python :copyable: - :linenos: - :emphasize-lines: 11-13 -Single Field Index ------------------- +The following is an example of a query that is covered by the index created in the +preceding code example: -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-single-field - :end-before: end-single-field +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-single-query + :end-before: end-index-single-query + +To learn more, see :manual:`Single Field Indexes +` in the {+mdb-server+} manual. -To learn more about single field indexes, see the -:ref:`pymongo-single-field-index` guide. +Compound Indexes +```````````````` -Compound Index --------------- +:manual:`Compound indexes ` hold references to multiple +fields within a collection's documents, improving query and sort performance. -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-compound - :end-before: end-compound +The following example creates a compound index on the ``type`` and ``genre`` fields: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-compound-index + :end-before: end-compound-index + +The following is an example of a query that uses the index created in +the preceding code example: + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-compound-query + :end-before: end-index-compound-query + +For more information, see :manual:`Compound Indexes ` in +the {+mdb-server+} manual. + +.. _pymongo-multikey-index: -To learn more about compound indexes, see the :ref:`pymongo-compound-index` -guide. +Multikey Indexes (Indexes on Array Fields) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Multikey Index --------------- +**Multikey indexes** are indexes that improve performance for queries that specify a field +with an index that contains an array value. You can define a multikey index by using the +same syntax as a single field or compound index. -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-multikey - :end-before: end-multikey +The following example creates a multikey index on the ``cast`` field: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-multikey + :end-before: end-index-multikey + +The following is an example of a query that uses the index created in the preceding code example: + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-multikey-query + :end-before: end-index-multikey-query + +Multikey indexes behave differently from other indexes in terms of query coverage, index- +bound computation, and sort behavior. To learn more about multikey indexes, including a +discussion of their behavior and limitations, see the +:manual:`Multikey Indexes ` guide in the {+mdb-server+} manual. + +.. _pymongo-atlas-search-index: -To learn more about multikey indexes, see the :ref:`pymongo-multikey-index` -guide. +Atlas Search and Vector Search Indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Atlas Search Index ------------------- +You can manage your :atlas:`Atlas Search ` and +:atlas:`Atlas Vector Search ` +indexes by using {+driver-short+}. The indexes specify the behavior of +the search and which fields to index. -To learn more about Atlas search indexes, see the :ref:`pymongo-atlas-search-index` -guide. +Atlas Search enables you to perform full-text searches on +collections hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of +the search and which fields to index. -Create Search Index -~~~~~~~~~~~~~~~~~~~ +Atlas Vector Search enables you to perform semantic searches on vector +embeddings stored in MongoDB Atlas. Vector Search indexes define the +indexes for the vector embeddings that you want to query and the boolean, +date, objectId, numeric, string, or UUID values that you want to use to +pre-filter your data. -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-search-create - :end-before: end-search-create +You can call the following methods on a collection to manage your Atlas Search +and Vector Search indexes: + +- ``create_search_index()`` +- ``create_search_indexes()`` +- ``list_search_indexes()`` +- ``update_search_index()`` +- ``drop_search_index()`` + +.. note:: + + The Atlas Search Index management methods run asynchronously. The + driver methods can return before confirming that they ran + successfully. To determine the current status of the indexes, call the + ``list_search_indexes()`` method. + +The following sections provide code examples that demonstrate how to use +each of the preceding methods. + +.. _pymongo-atlas-search-index-create: + +Create a Search Index +````````````````````` + +You can use the `create_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_index>`__ +and the +`create_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_indexes>`__ +methods to create Atlas Search indexes or Atlas Vector Search indexes. + +The following code example shows how to create a single Atlas Search index: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-create-search-index + :end-before: end-create-search-index + +The following code example shows how to create a single Atlas Vector Search index +by using the `SearchIndexModel <{+api-root+}pymongo/operations.html#pymongo.operations.SearchIndexModel>`__ +object: + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-create-vector-search-index + :end-before: end-create-vector-search-index + +You can use the `create_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_indexes>`__ +method to create multiple indexes. These indexes can be Atlas Search or +Vector Search indexes. The ``create_search_indexes()`` method takes a list of +``SearchIndexModel`` objects that correspond to each index you want to create. -To learn more about creating search indexes, see the :ref:`pymongo-atlas-search-index-create` -guide. +The following code example shows how to create an Atlas Search index and an Atlas +Vector Search index: + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-create-search-indexes + :end-before: end-create-search-indexes + +.. _pymongo-atlas-search-index-list: List Search Indexes -~~~~~~~~~~~~~~~~~~~ +``````````````````` + +You can use the +`list_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.list_search_indexes>`__ +method to get information about the Atlas Search and Vector Search indexes +of a collection. -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-search-list - :end-before: end-search-list +The following code example shows how to print a list of the search indexes of +a collection: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :dedent: + :start-after: start-list-search-indexes + :end-before: end-list-search-indexes -To learn more about listing search indexes, see the :ref:`pymongo-atlas-search-index-list` -guide. +.. _pymongo-atlas-search-index-update: -Update Search Indexes -~~~~~~~~~~~~~~~~~~~~~ +Update a Search Index +````````````````````` -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-search-update - :end-before: end-search-update +You can use the +`update_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.update_search_index>`__ +method to update an Atlas Search or Vector Search index. + +The following code example shows how to update an Atlas Search index: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :dedent: + :start-after: start-update-search-indexes + :end-before: end-update-search-indexes -To learn more about updating search indexes, see the :ref:`pymongo-atlas-search-index-update` -guide. +The following code example shows how to update an Atlas Vector Search index: -Delete Search Indexes -~~~~~~~~~~~~~~~~~~~~~ +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :dedent: + :start-after: start-update-vector-search-indexes + :end-before: end-update-vector-search-indexes + +.. _pymongo-atlas-search-index-drop: + +Delete a Search Index +````````````````````` -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-search-drop - :end-before: end-search-drop +You can use the +`drop_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_search_index>`__ +method to remove an Atlas Search or Vector Search index. + +The following code shows how to delete a search index from a collection: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :dedent: + :start-after: start-delete-search-indexes + :end-before: end-delete-search-indexes + +.. _pymongo-text-index: + +Text Indexes +~~~~~~~~~~~~ + +**Text indexes** support text search queries on string content. These indexes +can include any field whose value is a string or an array of string elements. +MongoDB supports text search for various languages. You can specify the default +language as an option when creating the index. + +.. tip:: -To learn more about deleting search indexes, see the :ref:`pymongo-atlas-search-index-drop` -guide. + MongoDB offers an improved full-text search solution, + :atlas:`Atlas Search `. To learn more about Atlas Search + indexes and how to use them, see the :ref:`pymongo-atlas-search-index` + section of this page. +Text Index on a Single Field +```````````````````````````` -Text Index ----------- +The following example creates a text index on the ``plot`` field: -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-text - :end-before: end-text +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-text-single + :end-before: end-index-text-single + +The following is an example of a query that uses the index created in the +preceding code example: + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-text-single-query + :end-before: end-index-text-single-query -To learn more about text indexes, see the :ref:`pymongo-text-index` -guide. +Text Index on Multiple Fields +````````````````````````````` -Geospatial Index ----------------- +A collection can contain only one text index. If you want to create a +text index for multiple text fields, create a compound +index. A text search runs on all the text fields within the compound +index. -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-geo - :end-before: end-geo +The following example creates a compound text index for the ``title`` and ``genre`` +fields: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-text-multi + :end-before: end-index-text-multi + +For more information, see :manual:`Compound Text Index Restrictions +` and +:manual:`Text Indexes ` in the {+mdb-server+} manual. + +.. _pymongo-geospatial-index: + +Geospatial Indexes +~~~~~~~~~~~~~~~~~~ + +MongoDB supports queries of geospatial coordinate data using **2dsphere indexes**. With +a ``2dsphere`` index, you can query the geospatial data for inclusion, intersection, +and proximity. For more information about querying geospatial data, see +:manual:`Geospatial Queries `. + +To create a ``2dsphere`` index, you must specify a field that contains only +**GeoJSON objects**. For more details on this +type, see the :manual:`GeoJSON objects ` guide in the MongoDB +Server manual. + +The ``location.geo`` field in the following sample document from the ``theaters`` +collection in the ``sample_mflix`` +database is a GeoJSON Point object that describes the coordinates of the theater: + +.. code-block:: javascript + + { + "_id" : ObjectId("59a47286cfa9a3a73e51e75c"), + "theaterId" : 104, + "location" : { + "address" : { + "street1" : "5000 W 147th St", + "city" : "Hawthorne", + "state" : "CA", + "zipcode" : "90250" + }, + "geo" : { + "type" : "Point", + "coordinates" : [ + -118.36559, + 33.897167 + ] + } + } + } + +Create a Geospatial Index +````````````````````````` + +The following example creates a ``2dsphere`` index on the ``location.geo`` field: + +.. literalinclude:: /includes/indexes/indexes.py + :language: python + :start-after: start-index-geo + :end-before: end-index-geo -To learn more about geospatial indexes, see the :ref:`pymongo-geospatial-index` -guide. +MongoDB also supports ``2d`` indexes for calculating distances on a Euclidean plane and for working with the "legacy +coordinate pairs" syntax used in MongoDB 2.2 and earlier. For more information, +see the :manual:`Geospatial Queries guide ` in the MongoDB +Server manual. -Unique Index ------------- +.. _pymongo-unique-index: -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-unique - :end-before: end-unique +Unique Indexes +~~~~~~~~~~~~~~ + +Unique indexes ensure that the indexed fields do not store duplicate values. By +default, MongoDB creates a unique index on the ``_id`` field during the creation +of a collection. To create a unique index, perform the following steps: + +- Specify the field or combination of fields that you want to prevent duplication on. +- Set the ``unique`` option to``True``. + +Create a Unique Index +````````````````````` + +The following example creates a descending unique index on the ``theaterId`` field: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-unique + :end-before: end-index-unique + +For more information, see the :manual:`Unique Indexes ` guide +in the {+mdb-server+} manual. -To learn more about unique indexes, see the :ref:`pymongo-unique-index` -guide. +.. _pymongo-wildcard-index: -Wildcard Index --------------- +Wildcard Indexes +~~~~~~~~~~~~~~~~ -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-wildcard - :end-before: end-wildcard +Wildcard indexes enable queries against unknown or arbitrary fields. +These indexes can be beneficial if you are using a dynamic schema. + +Create a Wildcard Index +``````````````````````` + +The following example creates an ascending wildcard index on all +values of the ``location`` field, including values nested in subdocuments and arrays: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-wildcard + :end-before: end-index-wildcard -To learn more about wildcard indexes, see the :ref:`pymongo-wildcard-index` -guide. +For more information, see the :manual:`Wildcard Indexes` +page in the {+mdb-server+} manual. -Clustered Index ---------------- +.. _pymongo-clustered-index: + +Clustered Indexes +~~~~~~~~~~~~~~~~~ + +**Clustered indexes** instruct a collection to store documents ordered +by a key value. To create a clustered index, perform the following steps when +you create your collection: -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-clustered - :end-before: end-clustered +- Specify the clustered index option with the ``_id`` field as the key. +- Set the unique field to ``True``. + +Create a Clustered Index +```````````````````````` + +The following example creates a clustered index on the ``_id`` field in +a new ``movie_reviews`` collection: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-index-clustered + :end-before: end-index-clustered -To learn more about wildcard indexes, see the :ref:`pymongo-clustered-index` -guide. +For more information, see the :manual:`Clustered Index +` +and :manual:`Clustered Collections ` sections in +the {+mdb-server+} manual. + +.. _pymongo-indexes-remove: Remove an Index --------------- -.. literalinclude:: /includes/usage-examples/index-code-examples.py - :start-after: start-remove - :end-before: end-remove +You can remove any unused index except the default unique index on the +``_id`` field. + +The following sections show how to remove a single index or to remove all +indexes in a collection. + +Remove a Single Index +~~~~~~~~~~~~~~~~~~~~~ + +Pass an instance of an index or the index name to the ``drop_index()`` method to +remove an index from a collection. + +The following example removes an index with the name ``"_title_"`` from the ``movies`` +collection: + +.. literalinclude:: /includes/indexes/indexes.py :language: python - :copyable: + :start-after: start-remove-index + :end-before: end-remove-index + +.. note:: + + You cannot remove a single field from a compound text index. You must + drop the entire index and create a new one to update the indexed + fields. + +Remove All Indexes +~~~~~~~~~~~~~~~~~~ + +Starting with MongoDB 4.2, you can drop all indexes by calling the +``drop_indexes()`` method on your collection: + +.. code-block:: java + + collection.drop_indexes() + +For earlier versions of MongoDB, pass ``"*"`` as a parameter to your call to +``drop_index()`` on your collection: + +.. code-block:: java + + collection.drop_index("*") + +Troubleshooting +--------------- + +.. include:: /includes/troubleshooting/unique-index.rst + +Additional Information +---------------------- + +To learn more about indexes in MongoDB, see the :manual:`Indexes ` +guide in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: -To learn more about removing indexes, see :ref:`pymongo-indexes-remove` -in the Work with Indexes guide. \ No newline at end of file +- `create_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_index>`__ +- `create_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_indexes>`__ +- `drop_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_index>`__ +- `drop_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_indexes>`__ \ No newline at end of file diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt deleted file mode 100644 index d0ad5091..00000000 --- a/source/indexes/atlas-search-index.txt +++ /dev/null @@ -1,155 +0,0 @@ -.. _pymongo-atlas-search-index: - -====================================== -Atlas Search and Vector Search Indexes -====================================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -You can manage your :atlas:`Atlas Search ` and -:atlas:`Atlas Vector Search ` -indexes by using {+driver-short+}. The indexes specify the behavior of -the search and which fields to index. - -Atlas Search enables you to perform full-text searches on -collections hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of -the search and which fields to index. - -Atlas Vector Search enables you to perform semantic searches on vector -embeddings stored in MongoDB Atlas. Vector Search indexes define the -indexes for the vector embeddings that you want to query and the boolean, -date, objectId, numeric, string, or UUID values that you want to use to -pre-filter your data. - -You can call the following methods on a collection to manage your Atlas Search -and Vector Search indexes: - -- ``create_search_index()`` -- ``create_search_indexes()`` -- ``list_search_indexes()`` -- ``update_search_index()`` -- ``drop_search_index()`` - -.. note:: - - The Atlas Search Index management methods run asynchronously. The - driver methods can return before confirming that they ran - successfully. To determine the current status of the indexes, call the - ``list_search_indexes()`` method. - -The following sections provide code examples that demonstrate how to use -each of the preceding methods. - -.. _pymongo-atlas-search-index-create: - -Create a Search Index ---------------------- - -You can use the `create_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_index>`__ -and the -`create_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_indexes>`__ -methods to create Atlas Search indexes or Atlas Vector Search indexes. - -The following code example shows how to create a single Atlas Search index: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-create-search-index - :end-before: end-create-search-index - -The following code example shows how to create a single Atlas Vector Search index -by using the `SearchIndexModel <{+api-root+}pymongo/operations.html#pymongo.operations.SearchIndexModel>`__ -object: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-create-vector-search-index - :end-before: end-create-vector-search-index - -You can use the `create_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_indexes>`__ -method to create multiple indexes. These indexes can be Atlas Search or -Vector Search indexes. The ``create_search_indexes()`` method takes a list of -``SearchIndexModel`` objects that correspond to each index you want to create. - -The following code example shows how to create an Atlas Search index and an Atlas -Vector Search index: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-create-search-indexes - :end-before: end-create-search-indexes - -.. _pymongo-atlas-search-index-list: - -List Search Indexes -------------------- - -You can use the -`list_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.list_search_indexes>`__ -method to get information about the Atlas Search and Vector Search indexes -of a collection. - -The following code example shows how to print a list of the search indexes of -a collection: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-list-search-indexes - :end-before: end-list-search-indexes - -.. _pymongo-atlas-search-index-update: - -Update a Search Index ---------------------- - -You can use the -`update_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.update_search_index>`__ -method to update an Atlas Search or Vector Search index. - -The following code example shows how to update an Atlas Search index: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-update-search-indexes - :end-before: end-update-search-indexes - -The following code example shows how to update an Atlas Vector Search index: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-update-vector-search-indexes - :end-before: end-update-vector-search-indexes - -.. _pymongo-atlas-search-index-drop: - -Delete a Search Index ---------------------- - -You can use the -`drop_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_search_index>`__ -method to remove an Atlas Search or Vector Search index. - -The following code shows how to delete a search index from a collection: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-delete-search-indexes - :end-before: end-delete-search-indexes diff --git a/source/indexes/clustered-index.txt b/source/indexes/clustered-index.txt deleted file mode 100644 index 4f953a2a..00000000 --- a/source/indexes/clustered-index.txt +++ /dev/null @@ -1,52 +0,0 @@ -.. _pymongo-clustered-index: - -================= -Clustered Indexes -================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -**Clustered indexes** instruct a collection to store documents ordered -by a key value. To create a clustered index, perform the following steps when -you create your collection: - -- Specify the clustered index option with the ``_id`` field as the key. -- Set the unique field to ``True``. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix`` database -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create a Clustered Index ------------------------- - -The following example creates a clustered index on the ``_id`` field in -a new ``movie_reviews`` collection: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-clustered - :end-before: end-index-clustered - -For more information, see the :manual:`Clustered Index -` -and :manual:`Clustered Collections ` sections in -the {+mdb-server+} manual. \ No newline at end of file diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt deleted file mode 100644 index 78f8836e..00000000 --- a/source/indexes/compound-index.txt +++ /dev/null @@ -1,63 +0,0 @@ -.. _pymongo-compound-index: - -================ -Compound Indexes -================ - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -:manual:`Compound indexes ` hold references to multiple -fields within a collection's documents, improving query and sort performance. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.movies`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create a Compound Index ------------------------ - -The following example creates a compound index on the ``type`` and ``genre`` fields: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-compound-index - :end-before: end-compound-index - -The following is an example of a query that uses the index created in -the preceding code example: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-compound-query - :end-before: end-index-compound-query - -For more information, see :manual:`Compound Indexes ` in -the {+mdb-server+} manual. - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-compound-index-collation - :end-before: end-compound-index-collation \ No newline at end of file diff --git a/source/indexes/geospatial-index.txt b/source/indexes/geospatial-index.txt deleted file mode 100644 index 66d742c0..00000000 --- a/source/indexes/geospatial-index.txt +++ /dev/null @@ -1,87 +0,0 @@ -.. _pymongo-geospatial-index: - -================== -Geospatial Indexes -================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -MongoDB supports queries of geospatial coordinate data using **2dsphere indexes**. With a ``2dsphere`` index, you can query -the geospatial data for inclusion, intersection, and proximity. For more information about querying geospatial data, see -:manual:`Geospatial Queries `. - -To create a ``2dsphere`` index, you must specify a field that contains only **GeoJSON objects**. For more details on this -type, see the :manual:`GeoJSON objects ` guide in the MongoDB -Server manual. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.theaters`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -The ``location.geo`` field in the following sample document from the ``theaters`` collection in the ``sample_mflix`` -database is a GeoJSON Point object that describes the coordinates of the theater: - -.. code-block:: javascript - - { - "_id" : ObjectId("59a47286cfa9a3a73e51e75c"), - "theaterId" : 104, - "location" : { - "address" : { - "street1" : "5000 W 147th St", - "city" : "Hawthorne", - "state" : "CA", - "zipcode" : "90250" - }, - "geo" : { - "type" : "Point", - "coordinates" : [ - -118.36559, - 33.897167 - ] - } - } - } - -Create a Geospatial Index -------------------------- - -The following example creates a ``2dsphere`` index on the ``location.geo`` field: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-geo - :end-before: end-index-geo - -MongoDB also supports ``2d`` indexes for calculating distances on a Euclidean plane and for working with the "legacy -coordinate pairs" syntax used in MongoDB 2.2 and earlier. For more information, -see the :manual:`Geospatial Queries guide ` in the MongoDB -Server manual. - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-geo-collation - :end-before: end-index-geo-collation diff --git a/source/indexes/multikey-index.txt b/source/indexes/multikey-index.txt deleted file mode 100644 index 3eac056a..00000000 --- a/source/indexes/multikey-index.txt +++ /dev/null @@ -1,63 +0,0 @@ -.. _pymongo-multikey-index: - -================ -Multikey Indexes -================ - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -**Multikey indexes** are indexes that improve performance for queries that specify a field with an index that contains -an array value. You can define a multikey index by using the same syntax as a single field or compound index. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.movies`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create a Multikey Index ------------------------ - -The following example creates a multikey index on the ``cast`` field: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-multikey - :end-before: end-index-multikey - -The following is an example of a query that uses the index created in the preceding code example: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-multikey-query - :end-before: end-index-multikey-query - -Multikey indexes behave differently from other indexes in terms of query coverage, index bound computation, and -sort behavior. To learn more about multikey indexes, including a discussion of their behavior and limitations, -see the :manual:`Multikey Indexes ` guide in the {+mdb-server+} manual. - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-multikey-collation - :end-before: end-index-multikey-collation \ No newline at end of file diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt deleted file mode 100644 index d4da7204..00000000 --- a/source/indexes/single-field-index.txt +++ /dev/null @@ -1,70 +0,0 @@ -.. _pymongo-single-field-index: - -==================== -Single Field Indexes -==================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -:manual:`Single field indexes ` are indexes with a reference to a single field within a collection's -documents. They improve single field query and sort performance, and support :manual:`TTL Indexes ` that -automatically remove documents from a collection after a certain amount of time or at a specific clock time. - -.. note:: - - The ``_id_`` index is an example of a single field index. This index is automatically created on the ``_id`` field - when a new collection is created. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.movies`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create Single Field Index -------------------------- - -The following example creates an index in ascending order on the ``title`` field: - -.. literalinclude:: /includes/indexes/indexes.py - :start-after: start-index-single - :end-before: end-index-single - :language: python - :copyable: - -The following is an example of a query that is covered by the index created in the preceding code example: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-single-query - :end-before: end-index-single-query - -To learn more, see :manual:`Single Field Indexes -` in the {+mdb-server+} manual. - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :start-after: start-index-single-collation - :end-before: end-index-single-collation - :language: python - :copyable: \ No newline at end of file diff --git a/source/indexes/text-index.txt b/source/indexes/text-index.txt deleted file mode 100644 index 1ae00306..00000000 --- a/source/indexes/text-index.txt +++ /dev/null @@ -1,89 +0,0 @@ -.. _pymongo-text-index: - -============ -Text Indexes -============ - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -**Text indexes** support text search queries on string content. These indexes -can include any field whose value is a string or an array of string elements. -MongoDB supports text search for various languages. You can specify the default -language as an option when creating the index. - -.. tip:: - - MongoDB offers an improved full-text search solution, - :atlas:`Atlas Search `. To learn more about Atlas Search - indexes and how to use them, see the :ref:`pymongo-atlas-search-index` - guide. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.movies`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Text Index on a Single Field ----------------------------- - -The following example creates a text index on the ``plot`` field: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-text-single - :end-before: end-index-text-single - -The following is an example of a query that uses the index created in the -preceding code example: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-text-single-query - :end-before: end-index-text-single-query - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-text-single-collation - :end-before: end-index-text-single-collation - -Text Index on Multiple Fields ------------------------------ - -A collection can contain only one text index. If you want to create a -text index for multiple text fields, create a compound -index. A text search runs on all the text fields within the compound -index. - -The following example creates a compound text index for the ``title`` and ``genre`` -fields: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-text-multi - :end-before: end-index-text-multi - -For more information, see :manual:`Compound Text Index Restrictions -` and -:manual:`Text Indexes ` in the {+mdb-server+} manual. \ No newline at end of file diff --git a/source/indexes/unique-index.txt b/source/indexes/unique-index.txt deleted file mode 100644 index fe54765a..00000000 --- a/source/indexes/unique-index.txt +++ /dev/null @@ -1,64 +0,0 @@ -.. _pymongo-unique-index: - -============== -Unique Indexes -============== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -Unique indexes ensure that the indexed fields do not store duplicate values. By -default, MongoDB creates a unique index on the ``_id`` field during the creation -of a collection. To create a unique index, perform the following steps: - -- Specify the field or combination of fields that you want to prevent duplication on. -- Set the ``unique`` option to``True``. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.theaters`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create a Unique Index ---------------------- - -The following example creates a descending unique index on the ``theaterId`` field: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-unique - :end-before: end-index-unique - -For more information, see the :manual:`Unique Indexes ` guide -in the {+mdb-server+} manual. - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-unique-collation - :end-before: end-index-unique-collation - -Troubleshooting ---------------- - -.. include:: /includes/troubleshooting/unique-index.rst \ No newline at end of file diff --git a/source/indexes/wildcard-index.txt b/source/indexes/wildcard-index.txt deleted file mode 100644 index a90aa467..00000000 --- a/source/indexes/wildcard-index.txt +++ /dev/null @@ -1,56 +0,0 @@ -.. _pymongo-wildcard-index: - -================ -Wildcard Indexes -================ - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: index, query, optimization, efficiency - -Overview --------- - -Wildcard indexes enable queries against unknown or arbitrary fields. -These indexes can be beneficial if you are using a dynamic schema. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.movies`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create a Wildcard Index ------------------------ - -The following example creates an ascending wildcard index on all -values of the ``location`` field, including values nested in subdocuments and arrays: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-wildcard - :end-before: end-index-wildcard - -For more information, see the :manual:`Wildcard Indexes` -page in the {+mdb-server+} manual. - -Collation -~~~~~~~~~ - -.. include:: /includes/collation-description-indexes.rst - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-wildcard-collation - :end-before: end-index-wildcard-collation \ No newline at end of file diff --git a/source/tools.txt b/source/integrations.txt similarity index 98% rename from source/tools.txt rename to source/integrations.txt index de6eaa4d..82551c12 100644 --- a/source/tools.txt +++ b/source/integrations.txt @@ -1,8 +1,9 @@ .. _pymongo-tools: +.. _pymongo-integrations: -================= -Third-Party Tools -================= +================================== +Third-Party Integrations and Tools +================================== .. contents:: On this page :local: diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt new file mode 100644 index 00000000..fb6c273b --- /dev/null +++ b/source/logging-and-monitoring.txt @@ -0,0 +1,55 @@ +.. _pymongo-logging-monitoring: + +Logging and Monitoring +====================== + +.. facet:: + :name: programming_language + :values: python + +.. meta:: + :keywords: event + +.. toctree:: + + Monitoring + Logging + Change Streams + +Overview +-------- + +On this page, you can see copyable code examples that show common +methods you can use to monitor and log events with {+driver-short+}. + +.. tip:: + + To learn more about any of the methods shown on this page, see the link + provided in each section. + +To use an example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Be sure to replace all placeholders in the code examples, such as ````, with +the relevant values for your MongoDB deployment. + +.. _pymongo-monitoring-sample: + +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/crud-sample-app.py + :language: python + :copyable: + :linenos: + :emphasize-lines: 11-13 + +Monitor Data Changes +-------------------- + +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-watch-for-changes + :end-before: end-watch-for-changes + :language: python + :copyable: + +To learn more about the ``watch()`` method, see the +:ref:`pymongo-change-streams` guide. \ No newline at end of file diff --git a/source/read/change-streams.txt b/source/logging-and-monitoring/change-streams.txt similarity index 99% rename from source/read/change-streams.txt rename to source/logging-and-monitoring/change-streams.txt index 318aae5a..4532e452 100644 --- a/source/read/change-streams.txt +++ b/source/logging-and-monitoring/change-streams.txt @@ -1,8 +1,8 @@ .. _pymongo-change-streams: -==================== -Monitor Data Changes -==================== +================================ +Monitor Data with Change Streams +================================ .. contents:: On this page :local: diff --git a/source/logging.txt b/source/logging-and-monitoring/logging.txt similarity index 97% rename from source/logging.txt rename to source/logging-and-monitoring/logging.txt index 8f7246da..c471e337 100644 --- a/source/logging.txt +++ b/source/logging-and-monitoring/logging.txt @@ -70,4 +70,4 @@ desired length, as shown in the following example: .. code-block:: python import os - os.environ["MONGODB_LOG_MAX_DOCUMENT_LENGTH"] = "2000" + os.environ["MONGODB_LOG_MAX_DOCUMENT_LENGTH"] = "2000" \ No newline at end of file diff --git a/source/monitoring.txt b/source/logging-and-monitoring/monitoring.txt similarity index 100% rename from source/monitoring.txt rename to source/logging-and-monitoring/monitoring.txt diff --git a/source/motor-async-migration.txt b/source/motor-async-migration.txt deleted file mode 100644 index ff15fe70..00000000 --- a/source/motor-async-migration.txt +++ /dev/null @@ -1,76 +0,0 @@ -.. _pymongo-async-motor-migration: - -==================================== -Migrate from Motor to {+driver-async+} -==================================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: motor, async, refactor, migration - -.. include:: /includes/pymongo-async-experimental.rst - -Overview --------- - -The {+driver-async+} driver is a unification of {+driver-short+} and the `Motor -library `__. In this guide, you can -identify the changes you must make to migrate an application from -Motor to the {+driver-async+} driver. - -Migrate From Motor ------------------- - -The {+driver-async+} driver functions similarly to the Motor library, but allows -for improved latency and throughput due to directly using Python Asyncio instead -of delegating work to a thread pool. In most cases, you can directly migrate -existing Motor applications to {+driver-async+} by using ``AsyncMongoClient`` in -place of ``MotorClient``, and changing the application's import statements to -import from ``pymongo``. - -The following example shows the difference in imports to use a client for -read and write operations in Motor compared to {+driver-async+}: - -.. code-block:: python - - # Motor client import - from motor.motor_asyncio import AsyncIOMotorClient - - # {+driver-async+} client import - from pymongo import AsyncMongoClient - -To see a list of the asynchronous methods available in the {+driver-async+} -driver, see the :ref:`pymongo-async-methods` section in the {+driver-short+} to -{+driver-async+} guide. - -The following section shows the method signature changes that you must implement -in your application when migrating from Motor to the {+driver-async+} driver. - -Method Signature Changes -~~~~~~~~~~~~~~~~~~~~~~~~ - -The following Motor method signatures behave differently in the {+driver-async+} driver: - -- ``AsyncMongoClient.__init__()`` does not accept an ``io_loop`` parameter. -- ``AsyncCursor.each()`` does not exist in the {+driver-async+} driver. -- ``MotorGridOut.stream_to_handler()`` does not exist in the {+driver-async+} driver. -- ``AsyncCursor.to_list(0)`` is not valid in the {+driver-async+} driver. Use - ``to_list(None)`` instead. -- ``MongoClient`` is thread safe and can be used by many threads, however, an - ``AsyncMongoClient`` is not thread safe and should only be used by a single - event loop. - -Additional Information ----------------------- - -To learn more about asynchronous Python, see the `Python Asyncio documentation -`__. \ No newline at end of file diff --git a/source/reference.txt b/source/reference.txt new file mode 100644 index 00000000..6529672e --- /dev/null +++ b/source/reference.txt @@ -0,0 +1,15 @@ +.. _pymongo-reference: + +========== +Reference +========== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Release Notes + Compatibility + Upgrade Guides + Migrate to PyMongo Async + Previous Versions \ No newline at end of file diff --git a/source/compatibility.txt b/source/reference/compatibility.txt similarity index 100% rename from source/compatibility.txt rename to source/reference/compatibility.txt diff --git a/source/pymongo-to-async-guide.txt b/source/reference/migration.txt similarity index 75% rename from source/pymongo-to-async-guide.txt rename to source/reference/migration.txt index 27b1dbea..febf2911 100644 --- a/source/pymongo-to-async-guide.txt +++ b/source/reference/migration.txt @@ -1,8 +1,9 @@ -.. _pymongo-to-async-guide: +.. _pymongo-async-migration: +.. _pymongo-async-motor-migration: -==================================== -Switch from {+driver-short+} to {+driver-async+} -==================================== +=========================== +Migrate to {+driver-async+} +=========================== .. contents:: On this page :local: @@ -15,7 +16,7 @@ Switch from {+driver-short+} to {+driver-async+} :values: reference .. meta:: - :keywords: asyncronous, refactor, migration + :keywords: motor, async, refactor, migration, asynchronous .. include:: /includes/pymongo-async-experimental.rst @@ -24,15 +25,59 @@ Overview The {+driver-async+} driver is a unification of {+driver-short+} and the `Motor library `__. In this guide, you can -identify the changes you must make to switch from {+driver-short+} to -{+driver-async+}. +identify the changes you must make to migrate an application from {+driver-short+} or +Motor to the {+driver-async+} driver. + +Migrate From Motor +------------------ + +The {+driver-async+} driver functions similarly to the Motor library, but allows +for improved latency and throughput due to directly using Python Asyncio instead +of delegating work to a thread pool. In most cases, you can directly migrate +existing Motor applications to {+driver-async+} by using ``AsyncMongoClient`` in +place of ``MotorClient``, and changing the application's import statements to +import from ``pymongo``. + +The following example shows the difference in imports to use a client for +read and write operations in Motor compared to {+driver-async+}: + +.. code-block:: python + + # Motor client import + from motor.motor_asyncio import AsyncIOMotorClient + + # {+driver-async+} client import + from pymongo import AsyncMongoClient + +To see a list of the asynchronous methods available in the {+driver-async+} +driver, see the :ref:`pymongo-async-methods` section in the {+driver-short+} to +{+driver-async+} guide. + +The following section shows the method signature changes that you must implement +in your application when migrating from Motor to the {+driver-async+} driver. + +Method Signature Changes +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following Motor method signatures behave differently in the {+driver-async+} driver: + +- ``AsyncMongoClient.__init__()`` does not accept an ``io_loop`` parameter. +- ``AsyncCursor.each()`` does not exist in the {+driver-async+} driver. +- ``MotorGridOut.stream_to_handler()`` does not exist in the {+driver-async+} driver. +- ``AsyncCursor.to_list(0)`` is not valid in the {+driver-async+} driver. Use + ``to_list(None)`` instead. +- ``MongoClient`` is thread safe and can be used by many threads, however, an + ``AsyncMongoClient`` is not thread safe and should only be used by a single + event loop. + +.. _pymongo-to-async-guide: -Switch From {+driver-short+} -------------------- +Migrate from {+driver-short+} +----------------------------- The {+driver-async+} driver behaves similarly to {+driver-short+}, but all methods that perform network operations are coroutines and must be awaited. -To switch from {+driver-short+} to {+driver-async+}, you must update your code +To migrate from {+driver-short+} to {+driver-async+}, you must update your code in the following ways: - Replace all uses of ``MongoClient`` with ``AsyncMongoClient``. diff --git a/source/previous-versions.txt b/source/reference/previous-versions.txt similarity index 91% rename from source/previous-versions.txt rename to source/reference/previous-versions.txt index 31050cb2..1a891831 100644 --- a/source/previous-versions.txt +++ b/source/reference/previous-versions.txt @@ -20,3 +20,4 @@ The following links direct you to documentation for previous versions of {+drive - `Version 4.2 `__ - `Version 4.1 `__ - `Version 4.0 `__ +- `Version 3.13 `__ diff --git a/source/whats-new.txt b/source/reference/release-notes.txt similarity index 99% rename from source/whats-new.txt rename to source/reference/release-notes.txt index dae80463..7756d3ff 100644 --- a/source/whats-new.txt +++ b/source/reference/release-notes.txt @@ -1,8 +1,9 @@ +.. _pymongo-release-notes: .. _pymongo-whats-new: -========== -What's New -========== +============= +Release Notes +============= .. contents:: On this page :local: diff --git a/source/upgrade.txt b/source/reference/upgrade.txt similarity index 100% rename from source/upgrade.txt rename to source/reference/upgrade.txt diff --git a/source/security.txt b/source/security.txt index cf6c447d..cd5ff3ef 100644 --- a/source/security.txt +++ b/source/security.txt @@ -24,6 +24,7 @@ Secure Your Data Authentication In-Use Encryption + TLS Overview -------- @@ -51,6 +52,81 @@ the relevant values for your MongoDB deployment. :linenos: :emphasize-lines: 4-6 +Transport Layer Security (TLS) +------------------------------ + +Enable TLS +~~~~~~~~~~ + +.. include:: /includes/connect/tls-tabs.rst + +To learn more about enabling TLS, see :ref:`pymongo-enable-tls` in +the TLS configuration guide. + +Specify a Certificate Authority (CA) File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/ca-file-tabs.rst + +To learn more about specifying a CA file, see :ref:`pymongo-specify-ca-file` in +the TLS configuration guide. + +Disable OCSP Checks +~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/ocsp-tabs.rst + +To learn more about disabling OCSP checks, see :ref:`pymongo-disable-ocsp` in +the TLS configuration guide. + +Specify a Certificate Revocation List (CRL) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/crl-tabs.rst + +To learn more about specifying a CRL, see :ref:`pymongo-crl` in +the TLS configuration guide. + +Present a Client Certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/client-cert-tabs.rst + +To learn more about specifying a client certificate, see :ref:`pymongo-client-cert` in +the TLS configuration guide. + +Provide a Certificate Key File Password +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/key-file-password.rst + +To learn more about providing a key file password, see :ref:`pymongo-key-file-password` in +the TLS configuration guide. + +Allow Insecure TLS +~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/insecure-tls-tabs.rst + +To learn more about allowing insecure TLS, see :ref:`pymongo-insecure-tls` in +the TLS configuration guide. + +Disable Certificate Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/disable-cert-validation-tabs.rst + +To learn more about disabling certificate validation, see :ref:`pymongo-insecure-tls` in +the TLS configuration guide. + +Disable Hostname Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/connect/disable-host-verification-tabs.rst + +To learn more about disabling hostname verification, see :ref:`pymongo-insecure-tls` in +the TLS configuration guide. + SCRAM-SHA-256 ------------- diff --git a/source/connect/tls.txt b/source/security/tls.txt similarity index 100% rename from source/connect/tls.txt rename to source/security/tls.txt diff --git a/source/work-with-indexes.txt b/source/work-with-indexes.txt deleted file mode 100644 index 5c8c5cf1..00000000 --- a/source/work-with-indexes.txt +++ /dev/null @@ -1,153 +0,0 @@ -.. _pymongo-work-with-indexes: - -================= -Work with Indexes -================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: query, optimization, efficiency - -.. toctree:: - - Single Field - Compound - Multikey - Atlas & Vector Search - Text - Geospatial - Unique - Wildcard - Clustered - -Overview --------- - -In this guide, you can learn how to use **indexes** with {+driver-short+}. -Indexes can improve the efficiency of queries and add additional functionality -to querying and storing documents. - -Without indexes, MongoDB must scan every document in a collection to find the -documents that match each query. These collection scans are -slow and can negatively affect the performance of your application. However, if an -appropriate index exists for a query, MongoDB can use the index to limit the -documents it must inspect. - -Operational Considerations -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To improve query performance, build indexes on fields that appear often in -your application's queries and operations that return sorted results. Each -index that you add consumes disk space and memory when active, so we recommend -that you track index memory and disk usage for capacity planning. In addition, -when a write operation updates an indexed field, MongoDB updates the related -index. - -Because MongoDB supports dynamic schemas, applications can query against fields -whose names are not known in advance or are arbitrary. MongoDB 4.2 introduced -:manual:`wildcard indexes ` to help support these -queries. Wildcard indexes are not designed to replace workload-based index -planning. - -For more information about designing your data model and choosing indexes appropriate for your application, see the -:manual:`Data Modeling and Indexes ` guide -in the {+mdb-server+} manual. - -Sample Data -~~~~~~~~~~~ - -The examples in this guide use the ``sample_mflix.movies`` collection -from the :atlas:`Atlas sample datasets `. To learn how to create a -free MongoDB Atlas cluster and load the sample datasets, see the -:ref:``. - -Create an Index ---------------- - -MongoDB supports several different index types to support querying your data. -The following pages describe the most common index types and provide sample -code for creating each index type. - -- :ref:`pymongo-single-field-index` -- :ref:`pymongo-compound-index` -- :ref:`pymongo-multikey-index` -- :ref:`pymongo-atlas-search-index` -- :ref:`pymongo-text-index` -- :ref:`pymongo-geospatial-index` -- :ref:`pymongo-unique-index` -- :ref:`pymongo-wildcard-index` -- :ref:`pymongo-clustered-index` - -.. _pymongo-indexes-remove: - -Remove an Index ---------------- - -You can remove any unused index except the default unique index on the -``_id`` field. - -The following sections show how to remove a single index or to remove all -indexes in a collection. - -Remove a Single Index -~~~~~~~~~~~~~~~~~~~~~ - -Pass an instance of an index or the index name to the ``drop_index()`` method to -remove an index from a collection. - -The following example removes an index with the name ``"_title_"`` from the ``movies`` -collection: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-remove-index - :end-before: end-remove-index - -.. note:: - - You cannot remove a single field from a compound text index. You must - drop the entire index and create a new one to update the indexed - fields. - -Remove All Indexes -~~~~~~~~~~~~~~~~~~ - -Starting with MongoDB 4.2, you can drop all indexes by calling the -``drop_indexes()`` method on your collection: - -.. code-block:: java - - collection.drop_indexes() - -For earlier versions of MongoDB, pass ``"*"`` as a parameter to your call to -``drop_index()`` on your collection: - -.. code-block:: java - - collection.drop_index("*") - -Additional Information ----------------------- - -To learn more about indexes in MongoDB, see the :manual:`Indexes ` -guide in the {+mdb-server+} manual. - -API Documentation -~~~~~~~~~~~~~~~~~ - -To learn more about any of the methods or types discussed in this -guide, see the following API documentation: - -- `create_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_index>`__ -- `create_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_indexes>`__ -- `drop_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_index>`__ -- `drop_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_indexes>`__ diff --git a/source/write-operations.txt b/source/write-operations.txt deleted file mode 100644 index ba791941..00000000 --- a/source/write-operations.txt +++ /dev/null @@ -1,153 +0,0 @@ -.. _pymongo-write: - -===================== -Write Data to MongoDB -===================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :description: Learn how to use {+driver-short+} to write data to MongoDB. - :keywords: usage examples, save, crud, create, code example - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Insert - Update - Replace - Delete - Bulk Write Operations - Store Large Files - Transactions - -Overview --------- - -On this page, you can see copyable code examples that show common -methods you can use to write data to MongoDB with {+driver-short+}. - -.. tip:: - - To learn more about any of the methods shown on this page, see the link - provided in each section. - -To use an example from this page, copy the code example into the -:ref:`sample application ` or your own application. -Be sure to replace all placeholders in the code examples, such as ````, with -the relevant values for your MongoDB deployment. - -.. _pymongo-write-sample: - -.. include:: /includes/usage-examples/sample-app-intro.rst - -.. literalinclude:: /includes/usage-examples/sample-app.py - :language: python - :copyable: - :linenos: - :emphasize-lines: 11-13 - -Insert One ----------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-insert-one - :end-before: end-insert-one - :language: python - :copyable: - -To learn more about the ``insert_one()`` method, see the :ref:`Insert Documents -` guide. - -Insert Multiple ---------------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-insert-multiple - :end-before: end-insert-multiple - :language: python - :copyable: - -To learn more about the ``insert_many()`` method, see the :ref:`Insert Documents -` guide. - -Update One ----------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-update-one - :end-before: end-update-one - :language: python - :copyable: - -To learn more about the ``update_one()`` method, see the -:ref:`Update Documents ` guide. - -Update Multiple ---------------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-update-multiple - :end-before: end-update-multiple - :language: python - :copyable: - -To learn more about the ``update_many()`` method, see the -:ref:`Update Documents ` guide. - -Replace One ------------ - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-replace-one - :end-before: end-replace-one - :language: python - :copyable: - -To learn more about the ``replace_one()`` method, see the -:ref:`Replace Documents ` guide. - -Delete One ----------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-delete-one - :end-before: end-delete-one - :language: python - :copyable: - -To learn more about the ``delete_one()`` method, see the -:ref:`Delete Documents ` guide. - -Delete Multiple ---------------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-delete-multiple - :end-before: end-delete-multiple - :language: python - :copyable: - -To learn more about the ``delete_many()`` method, see the -:ref:`Delete Documents ` guide. - -Bulk Write ----------- - -.. literalinclude:: /includes/usage-examples/write-code-examples.py - :start-after: start-bulk-write - :end-before: end-bulk-write - :language: python - :copyable: - -To learn more about the ``bulk_write()`` method, see the -:ref:`Bulk Write ` guide. \ No newline at end of file