From 145e84849d953bb208341d59f04a6a4d773c7375 Mon Sep 17 00:00:00 2001 From: Mike Woofter Date: Fri, 26 Apr 2024 11:59:34 -0500 Subject: [PATCH 01/33] autobuilder From e628eedd84c4be7c92255d187b95748cc51a1bec Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:16:48 -0600 Subject: [PATCH 02/33] wip --- source/index.txt | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/index.txt b/source/index.txt index 86faa57e..1e73b953 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,30 +12,31 @@ MongoDB {+driver-short+} Documentation .. toctree:: - Get Started + Getting Started Connect + CRUD Operations + Data Formats + Indexes + Run a Database Command + Logging Monitoring + Security + Versioning + API Documentation <{+api-root+}> + Issues & Help + Databases & Collections Write Data Read Data - Run a Database Command - Indexes Aggregation - Security - Data Formats - Logging - Monitoring Serialization Third-Party Tools - FAQ Troubleshooting What's New Upgrade Migrate from Motor Switch to PyMongo Async Previous Versions - Issues & Help Compatibility - API Documentation <{+api-root+}> Overview -------- From 5b8198ecddea6785ac128e90ae21c19edaf7232f Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 21 Feb 2025 12:27:41 -0600 Subject: [PATCH 03/33] consolidate get started --- config/redirects | 5 + source/get-started.txt | 254 +++++++++++++++++- source/get-started/connect-to-mongodb.txt | 55 ---- .../create-a-connection-string.txt | 62 ----- source/get-started/create-a-deployment.txt | 29 -- source/get-started/download-and-install.txt | 89 ------ source/get-started/next-steps.txt | 16 -- 7 files changed, 251 insertions(+), 259 deletions(-) delete mode 100644 source/get-started/connect-to-mongodb.txt delete mode 100644 source/get-started/create-a-connection-string.txt delete mode 100644 source/get-started/create-a-deployment.txt delete mode 100644 source/get-started/download-and-install.txt delete mode 100644 source/get-started/next-steps.txt diff --git a/config/redirects b/config/redirects index c504eff7..c3cfc2c6 100644 --- a/config/redirects +++ b/config/redirects @@ -14,3 +14,8 @@ 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 +[*-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/ diff --git a/source/get-started.txt b/source/get-started.txt index 7229eb3f..ba9d67d8 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 - Connect - Next Steps - Overview -------- @@ -43,3 +35,249 @@ 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 perform read operations in the :ref:`` section. +- Learn how to perform write operations in the :ref:`` section. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt deleted file mode 100644 index 47125adf..00000000 --- a/source/get-started/connect-to-mongodb.txt +++ /dev/null @@ -1,55 +0,0 @@ -.. _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. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst 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. From 0d87cfacfd2b5d130bdb08f84f3646c600dd8973 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 24 Feb 2025 13:54:53 -0600 Subject: [PATCH 04/33] wip --- source/{read => }/change-streams.txt | 0 source/connect.txt | 76 ------------------- source/crud.txt | 62 +++++++++++++++ source/{write => crud}/bulk-write.txt | 0 source/{read => crud}/count.txt | 0 source/{read => crud}/cursors.txt | 0 source/{write => crud}/delete.txt | 0 source/{read => crud}/distinct.txt | 0 source/{read/retrieve.txt => crud/find.txt} | 0 source/{write => crud}/gridfs.txt | 0 source/{write => crud}/insert.txt | 0 source/{read => crud}/project.txt | 0 .../specify-a-query.txt => crud/query.txt} | 12 +++ .../specify-documents-to-return.txt | 0 .../text-index.txt => crud/text-search.txt} | 8 +- source/{write => crud}/transactions.txt | 0 source/{write => crud}/update.txt | 6 ++ source/{write => crud/update}/replace.txt | 0 source/read.txt | 33 -------- source/security.txt | 75 ++++++++++++++++++ source/{connect => security}/tls.txt | 0 source/write-operations.txt | 32 -------- 22 files changed, 159 insertions(+), 145 deletions(-) rename source/{read => }/change-streams.txt (100%) create mode 100644 source/crud.txt rename source/{write => crud}/bulk-write.txt (100%) rename source/{read => crud}/count.txt (100%) rename source/{read => crud}/cursors.txt (100%) rename source/{write => crud}/delete.txt (100%) rename source/{read => crud}/distinct.txt (100%) rename source/{read/retrieve.txt => crud/find.txt} (100%) rename source/{write => crud}/gridfs.txt (100%) rename source/{write => crud}/insert.txt (100%) rename source/{read => crud}/project.txt (100%) rename source/{read/specify-a-query.txt => crud/query.txt} (96%) rename source/{read => crud}/specify-documents-to-return.txt (100%) rename source/{indexes/text-index.txt => crud/text-search.txt} (97%) rename source/{write => crud}/transactions.txt (100%) rename source/{write => crud}/update.txt (99%) rename source/{write => crud/update}/replace.txt (100%) rename source/{connect => security}/tls.txt (100%) diff --git a/source/read/change-streams.txt b/source/change-streams.txt similarity index 100% rename from source/read/change-streams.txt rename to source/change-streams.txt diff --git a/source/connect.txt b/source/connect.txt index 6c983b01..a75fc5a1 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,7 +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 @@ -85,81 +84,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/crud.txt b/source/crud.txt new file mode 100644 index 00000000..bb41e7c3 --- /dev/null +++ b/source/crud.txt @@ -0,0 +1,62 @@ +.. _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 + Delete Documents + Bulk Write Operations + Transactions + text search + configure + retryable reads + retryable writes + Store Large Files +geospatial + +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-connect-sample: + +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/connect-sample-app.py + :language: python + :copyable: true + :linenos: + :emphasize-lines: 4-6 \ No newline at end of file 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/read/count.txt b/source/crud/count.txt similarity index 100% rename from source/read/count.txt rename to source/crud/count.txt diff --git a/source/read/cursors.txt b/source/crud/cursors.txt similarity index 100% rename from source/read/cursors.txt rename to source/crud/cursors.txt diff --git a/source/write/delete.txt b/source/crud/delete.txt similarity index 100% rename from source/write/delete.txt rename to source/crud/delete.txt diff --git a/source/read/distinct.txt b/source/crud/distinct.txt similarity index 100% rename from source/read/distinct.txt rename to source/crud/distinct.txt diff --git a/source/read/retrieve.txt b/source/crud/find.txt similarity index 100% rename from source/read/retrieve.txt rename to source/crud/find.txt 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 100% rename from source/write/insert.txt rename to source/crud/insert.txt diff --git a/source/read/project.txt b/source/crud/project.txt similarity index 100% rename from source/read/project.txt rename to source/crud/project.txt diff --git a/source/read/specify-a-query.txt b/source/crud/query.txt similarity index 96% rename from source/read/specify-a-query.txt rename to source/crud/query.txt index 3b0a1887..2cd5b529 100644 --- a/source/read/specify-a-query.txt +++ b/source/crud/query.txt @@ -17,6 +17,18 @@ Specify a Query .. meta:: :keywords: expressions, operations, read, write, filter +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Find Documents + Specify Documents to Return + Specify Fields to Return + Count Documents + Distinct Field Values + Access Data from a Cursor + Monitor Data Changes + Overview -------- diff --git a/source/read/specify-documents-to-return.txt b/source/crud/specify-documents-to-return.txt similarity index 100% rename from source/read/specify-documents-to-return.txt rename to source/crud/specify-documents-to-return.txt diff --git a/source/indexes/text-index.txt b/source/crud/text-search.txt similarity index 97% rename from source/indexes/text-index.txt rename to source/crud/text-search.txt index 1ae00306..d33e2e02 100644 --- a/source/indexes/text-index.txt +++ b/source/crud/text-search.txt @@ -1,8 +1,8 @@ -.. _pymongo-text-index: +.. _pymongo-text-search: -============ -Text Indexes -============ +=========== +Text Search +=========== .. contents:: On this page :local: 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..4f6bbd58 100644 --- a/source/write/update.txt +++ b/source/crud/update.txt @@ -17,6 +17,12 @@ Update Documents .. meta:: :keywords: modify, change, bulk, code example +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Replace + Overview -------- diff --git a/source/write/replace.txt b/source/crud/update/replace.txt similarity index 100% rename from source/write/replace.txt rename to source/crud/update/replace.txt diff --git a/source/read.txt b/source/read.txt index ae453161..509feda0 100644 --- a/source/read.txt +++ b/source/read.txt @@ -1,36 +1,3 @@ -.. _pymongo-read: - -====================== -Read Data from 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 read data from MongoDB. - :keywords: usage examples, query, find, code example - -.. toctree:: - :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 - Overview -------- diff --git a/source/security.txt b/source/security.txt index cf6c447d..972ca5ca 100644 --- a/source/security.txt +++ b/source/security.txt @@ -51,6 +51,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/write-operations.txt b/source/write-operations.txt index ba791941..5f7a7298 100644 --- a/source/write-operations.txt +++ b/source/write-operations.txt @@ -1,35 +1,3 @@ -.. _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 -------- From 9e0d57645e61de0947578806b5c5c346363006bf Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 24 Feb 2025 16:13:33 -0600 Subject: [PATCH 05/33] wip --- source/{crud/text-search.txt => indexes/text-index.txt} | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) rename source/{crud/text-search.txt => indexes/text-index.txt} (97%) diff --git a/source/crud/text-search.txt b/source/indexes/text-index.txt similarity index 97% rename from source/crud/text-search.txt rename to source/indexes/text-index.txt index d33e2e02..1ae00306 100644 --- a/source/crud/text-search.txt +++ b/source/indexes/text-index.txt @@ -1,8 +1,8 @@ -.. _pymongo-text-search: +.. _pymongo-text-index: -=========== -Text Search -=========== +============ +Text Indexes +============ .. contents:: On this page :local: From 46de623daa58d32174bd2f23d7385da3a5d144c5 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 25 Feb 2025 10:13:24 -0600 Subject: [PATCH 06/33] wip --- source/crud.txt | 4 +- source/crud/configure.txt | 159 +++++++++++++++++++++++++++++++ source/databases-collections.txt | 140 --------------------------- 3 files changed, 161 insertions(+), 142 deletions(-) create mode 100644 source/crud/configure.txt diff --git a/source/crud.txt b/source/crud.txt index bb41e7c3..3e849e79 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -28,8 +28,8 @@ CRUD Operations Delete Documents Bulk Write Operations Transactions - text search - configure + + configure CRUD retryable reads retryable writes Store Large Files diff --git a/source/crud/configure.txt b/source/crud/configure.txt new file mode 100644 index 00000000..ebccc0f3 --- /dev/null +++ b/source/crud/configure.txt @@ -0,0 +1,159 @@ +.. _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+}. + +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. \ No newline at end of file diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 0b7ee96d..9bdd5bce 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -181,146 +181,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. - Troubleshooting --------------- From de0523819a75ad49575293c543b91a5b14ca49f3 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 25 Feb 2025 16:48:09 -0600 Subject: [PATCH 07/33] wip --- source/crud.txt | 13 +- source/crud/configure.txt | 9 +- source/index.txt | 8 +- source/logging-and-monitoring.txt | 141 ++++++++++++++++++++++ source/logging.txt | 66 ---------- source/{data-formats => }/time-series.txt | 0 6 files changed, 157 insertions(+), 80 deletions(-) create mode 100644 source/logging-and-monitoring.txt delete mode 100644 source/logging.txt rename source/{data-formats => }/time-series.txt (100%) diff --git a/source/crud.txt b/source/crud.txt index 3e849e79..2f7bf48d 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -26,14 +26,11 @@ CRUD Operations Query Documents Update Documents Delete Documents - Bulk Write Operations - Transactions - - configure CRUD - retryable reads - retryable writes - Store Large Files -geospatial + Bulk Write Operations + Transactions + Configure CRUD Operations + Store Large Files + Geospatial Queries Overview -------- diff --git a/source/crud/configure.txt b/source/crud/configure.txt index ebccc0f3..1c5c722f 100644 --- a/source/crud/configure.txt +++ b/source/crud/configure.txt @@ -23,6 +23,9 @@ 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 @@ -86,7 +89,7 @@ MongoDB Server manual: - :manual:`Write Concern ` Tag Sets -~~~~~~~~ +-------- In {+mdb-server+}, you can apply key-value :manual:`tags ` to replica-set @@ -110,7 +113,7 @@ center (``'dc': 'sf'``): '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 @@ -140,7 +143,7 @@ within 35 milliseconds of the closest member's ping time. 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. diff --git a/source/index.txt b/source/index.txt index 1e73b953..79345002 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,15 +18,17 @@ MongoDB {+driver-short+} Documentation Data Formats Indexes Run a Database Command - Logging Monitoring + Atlas Search + Atlas Vector Search + Time Series + Change Streams + Logging and Monitoring Security Versioning API Documentation <{+api-root+}> Issues & Help Databases & Collections - Write Data - Read Data Aggregation Serialization Third-Party Tools diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt new file mode 100644 index 00000000..166267b7 --- /dev/null +++ b/source/logging-and-monitoring.txt @@ -0,0 +1,141 @@ +.. _pymongo-monitoring-logging: + +====================== +Monitoring and Logging +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: debugging, printing, event, subscribe, listener + +Overview +-------- + +In this guide, you can learn how to configure **monitoring** in {+driver-short+} +by using {+driver-short+}'s callback-based interface. Monitoring is the process of +gathering information about your application's performance and resource usage as it runs. +This can help you make informed decisions when designing and debugging your application. + +This guide also covers **logging**, which lets you record information obtained during +monitoring to an external log. + +Event Types +----------- + +The driver provides information about your application by emitting events. You can +listen for driver events to monitor your application. + +The type of event that the driver emits depends on the operation being performed. +The following table describes the types of events that the driver emits: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Event Type + - Description + * - Command events + - Events related to MongoDB database commands, such as ``find``, ``insert``, + ``delete``, and ``count``. To learn how to use {+driver-short+} to run a + database command, see :ref:``. For more information about + MongoDB database commands, see :manual:`Database Commands ` + in the {+mdb-server+} manual. + + As a security measure, the driver redacts the contents of some + command events. This protects the sensitive information contained in these command + events. + + * - Server Discovery and Monitoring (SDAM) events + - Events related to changes in the state of the MongoDB deployment. + + * - Connection Pool events + - Events related to the connection pool held by the driver. + +For a complete list of events the driver emits, see the +`pymongo.monitoring <{+api-root+}pymongo/monitoring.html>`__ API documentation. + +Listening for Events +-------------------- + +To monitor an event, you must pass an event listener to your application's ``MongoClient``. +The following steps describe how to monitor your application by using an event listener: + +1. Create a class that inherits from one of the event listener base classes + provided by {+driver-short+}. The base class you choose depends on the type of event + you want to monitor. For example, to monitor command events, create a class + that inherits from ``CommandListener``. +#. Implement the methods of the base class that correpond to the events you want to monitor. +#. Pass an instance of your listener class to the ``MongoClient`` constructor. + +The following code implements a ``CommandListener`` to listen for command events, a +``ServerListener`` to listen for SDAM events, and a ``ConnectionPoolListener`` to listen for +connection pool events: + +.. literalinclude:: /includes/monitoring/monitoring.py + :language: python + :start-after: start-monitoring + :end-before: end-monitoring + :copyable: true + +Logging +------- + +{+driver-short+} supports {+language+}'s native logging library. You can configure the logging +verbosity for the following components: + +- ``pymongo.command``, which logs command operations +- ``pymongo.connection``, which logs connection management operations +- ``pymongo.serverSelection``, which logs server selection operations + +In addition to configuring these options individually, you can configure the global +logging level by setting the log level on ``pymongo``. To learn more about the native +logging library, see the `Python logging library documentation `__. + +Examples +~~~~~~~~ + +The following example sets the global logging level to ``INFO``: + +.. code-block:: python + + import logging + logging.getLogger("pymongo").setLevel(logging.INFO) + +The following example sets the log level on the ``pymongo.command`` component to +``DEBUG``: + +.. code-block:: python + + import logging + logging.getLogger("pymongo.command").setLevel(logging.DEBUG) + +Configuring Truncation +~~~~~~~~~~~~~~~~~~~~~~ + +If you enable logging for the ``pymongo.command`` component, the resulting logs will +be truncated after 1000 bytes by default. You can configure this truncation limit +by setting the ``MONGODB_LOG_MAX_DOCUMENT_LENGTH`` environment variable to your +desired length, as shown in the following example: + +.. code-block:: python + + import os + os.environ["MONGODB_LOG_MAX_DOCUMENT_LENGTH"] = "2000" + +API Documentation +----------------- + +To learn more about the methods and classes used to monitor events in the driver, see the +following API documentation: + +- `monitoring <{+api-root+}pymongo/monitoring.html>`__ +- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ \ No newline at end of file diff --git a/source/logging.txt b/source/logging.txt deleted file mode 100644 index 84ba3470..00000000 --- a/source/logging.txt +++ /dev/null @@ -1,66 +0,0 @@ -.. _pymongo-logging: - -======= -Logging -======= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: debugging, printing - -Overview --------- - -In this guide, you can learn how to configure logging options for different -{+driver-short+} components. - -{+driver-short+} supports {+language+}'s native logging library. You can configure the logging -verbosity for the following components: - -- ``pymongo.command``, which logs command operations -- ``pymongo.connection``, which logs connection management operations -- ``pymongo.serverSelection``, which logs server selection operations - -In addition to configuring these options individually, you can configure the global -logging level by setting the log level on ``pymongo``. To learn more about the native -logging library, see the `Python logging library documentation `__. - -Examples --------- - -The follwing example sets the global logging level to ``INFO``: - -.. code-block:: python - - import logging - logging.getLogger("pymongo").setLevel(logging.INFO) - -The following example sets the log level on the ``pymongo.command`` component to -``DEBUG``: - -.. code-block:: python - - import logging - logging.getLogger("pymongo.command").setLevel(logging.DEBUG) - -Configuring Truncation ----------------------- - -If you enable logging for the ``pymongo.command`` component, the resulting logs will -be truncated after 1000 bytes by default. You can configure this truncation limit -by setting the ``MONGODB_LOG_MAX_DOCUMENT_LENGTH`` environment variable to your -desired length, as shown in the following example: - -.. code-block:: python - - import os - os.environ["MONGODB_LOG_MAX_DOCUMENT_LENGTH"] = "2000" diff --git a/source/data-formats/time-series.txt b/source/time-series.txt similarity index 100% rename from source/data-formats/time-series.txt rename to source/time-series.txt From 4fb11986aff32de8c28b10db1a877d5cb9d6f200 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 26 Feb 2025 09:38:27 -0600 Subject: [PATCH 08/33] wip --- source/logging-and-monitoring.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt index 166267b7..6bf960eb 100644 --- a/source/logging-and-monitoring.txt +++ b/source/logging-and-monitoring.txt @@ -20,13 +20,12 @@ Monitoring and Logging Overview -------- -In this guide, you can learn how to configure **monitoring** in {+driver-short+} -by using {+driver-short+}'s callback-based interface. Monitoring is the process of +In this guide, you can learn how to configure **monitoring** and **logging** in {+driver-short+} +by using its callback-based interface. Monitoring is the process of gathering information about your application's performance and resource usage as it runs. -This can help you make informed decisions when designing and debugging your application. - -This guide also covers **logging**, which lets you record information obtained during -monitoring to an external log. +Logging is the process of recording this information to an external log. +These mechanisms can help you make informed decisions when designing and debugging +your application. Event Types ----------- From cafde514ce46dcf03b3b46abd4479c2a783ba8cf Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 27 Feb 2025 08:53:27 -0600 Subject: [PATCH 09/33] wip --- source/data-formats.txt | 2 +- source/data-formats/custom-types.txt | 442 +---------------- .../custom-types}/serialization.txt | 61 +-- .../data-formats/custom-types/type-codecs.txt | 451 ++++++++++++++++++ source/{ => data-formats}/time-series.txt | 0 .../language-compatibility-table-pymongo.rst | 49 +- source/index.txt | 17 +- source/logging-and-monitoring.txt | 140 ------ source/monitoring-and-logging.txt | 17 + .../change-streams.txt | 6 +- source/monitoring-and-logging/logging.txt | 66 +++ .../monitoring.txt | 0 source/security.txt | 1 + source/versioning.txt | 14 + source/{ => versioning}/compatibility.txt | 0 .../motor-async-migration.txt | 0 source/{ => versioning}/previous-versions.txt | 0 .../pymongo-to-async-guide.txt | 0 .../release-notes.txt} | 8 +- source/{ => versioning}/upgrade.txt | 0 20 files changed, 617 insertions(+), 657 deletions(-) rename source/{ => data-formats/custom-types}/serialization.txt (59%) create mode 100644 source/data-formats/custom-types/type-codecs.txt rename source/{ => data-formats}/time-series.txt (100%) delete mode 100644 source/logging-and-monitoring.txt create mode 100644 source/monitoring-and-logging.txt rename source/{ => monitoring-and-logging}/change-streams.txt (99%) create mode 100644 source/monitoring-and-logging/logging.txt rename source/{ => monitoring-and-logging}/monitoring.txt (100%) create mode 100644 source/versioning.txt rename source/{ => versioning}/compatibility.txt (100%) rename source/{ => versioning}/motor-async-migration.txt (100%) rename source/{ => versioning}/previous-versions.txt (100%) rename source/{ => versioning}/pymongo-to-async-guide.txt (100%) rename source/{whats-new.txt => versioning/release-notes.txt} (99%) rename source/{ => versioning}/upgrade.txt (100%) diff --git a/source/data-formats.txt b/source/data-formats.txt index 727d7690..14612aa2 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -26,7 +26,7 @@ Specialized Data Formats Custom Types Dates & Times UUIDs - Time Series Data + Time Series Overview -------- diff --git a/source/data-formats/custom-types.txt b/source/data-formats/custom-types.txt index 9caf3da9..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,440 +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: - -.. 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: - -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: - -.. 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')} - -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: - -.. 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')} - -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: - -.. 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: - -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: - -.. 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')} - -.. 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: - -.. 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')} - -.. 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: - -.. 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 - -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 59% rename from source/serialization.txt rename to source/data-formats/custom-types/serialization.txt index c71c0035..c4fba61b 100644 --- a/source/serialization.txt +++ b/source/data-formats/custom-types/serialization.txt @@ -89,63 +89,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..f0a89563 --- /dev/null +++ b/source/data-formats/custom-types/type-codecs.txt @@ -0,0 +1,451 @@ +.. _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: + +.. 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: + +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: + +.. 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')} + +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: + +.. 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')} + +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: + +.. 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: + +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: + +.. 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')} + +.. 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: + +.. 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')} + +.. 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: + +.. 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 + +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/time-series.txt b/source/data-formats/time-series.txt similarity index 100% rename from source/time-series.txt rename to source/data-formats/time-series.txt diff --git a/source/includes/language-compatibility-table-pymongo.rst b/source/includes/language-compatibility-table-pymongo.rst index 55347b1b..5dbdb9c2 100644 --- a/source/includes/language-compatibility-table-pymongo.rst +++ b/source/includes/language-compatibility-table-pymongo.rst @@ -215,8 +215,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/index.txt b/source/index.txt index 79345002..d6fba128 100644 --- a/source/index.txt +++ b/source/index.txt @@ -14,31 +14,22 @@ MongoDB {+driver-short+} Documentation Getting Started Connect + Databases & Collections CRUD Operations + Aggregation Data Formats Indexes Run a Database Command Atlas Search Atlas Vector Search - Time Series - Change Streams - Logging and Monitoring + Monitoring and Logging Security - Versioning + Versioning API Documentation <{+api-root+}> Issues & Help - Databases & Collections - Aggregation - Serialization Third-Party Tools Troubleshooting - What's New - Upgrade - Migrate from Motor - Switch to PyMongo Async - Previous Versions - Compatibility Overview -------- diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt deleted file mode 100644 index 6bf960eb..00000000 --- a/source/logging-and-monitoring.txt +++ /dev/null @@ -1,140 +0,0 @@ -.. _pymongo-monitoring-logging: - -====================== -Monitoring and Logging -====================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: debugging, printing, event, subscribe, listener - -Overview --------- - -In this guide, you can learn how to configure **monitoring** and **logging** in {+driver-short+} -by using its callback-based interface. Monitoring is the process of -gathering information about your application's performance and resource usage as it runs. -Logging is the process of recording this information to an external log. -These mechanisms can help you make informed decisions when designing and debugging -your application. - -Event Types ------------ - -The driver provides information about your application by emitting events. You can -listen for driver events to monitor your application. - -The type of event that the driver emits depends on the operation being performed. -The following table describes the types of events that the driver emits: - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Event Type - - Description - * - Command events - - Events related to MongoDB database commands, such as ``find``, ``insert``, - ``delete``, and ``count``. To learn how to use {+driver-short+} to run a - database command, see :ref:``. For more information about - MongoDB database commands, see :manual:`Database Commands ` - in the {+mdb-server+} manual. - - As a security measure, the driver redacts the contents of some - command events. This protects the sensitive information contained in these command - events. - - * - Server Discovery and Monitoring (SDAM) events - - Events related to changes in the state of the MongoDB deployment. - - * - Connection Pool events - - Events related to the connection pool held by the driver. - -For a complete list of events the driver emits, see the -`pymongo.monitoring <{+api-root+}pymongo/monitoring.html>`__ API documentation. - -Listening for Events --------------------- - -To monitor an event, you must pass an event listener to your application's ``MongoClient``. -The following steps describe how to monitor your application by using an event listener: - -1. Create a class that inherits from one of the event listener base classes - provided by {+driver-short+}. The base class you choose depends on the type of event - you want to monitor. For example, to monitor command events, create a class - that inherits from ``CommandListener``. -#. Implement the methods of the base class that correpond to the events you want to monitor. -#. Pass an instance of your listener class to the ``MongoClient`` constructor. - -The following code implements a ``CommandListener`` to listen for command events, a -``ServerListener`` to listen for SDAM events, and a ``ConnectionPoolListener`` to listen for -connection pool events: - -.. literalinclude:: /includes/monitoring/monitoring.py - :language: python - :start-after: start-monitoring - :end-before: end-monitoring - :copyable: true - -Logging -------- - -{+driver-short+} supports {+language+}'s native logging library. You can configure the logging -verbosity for the following components: - -- ``pymongo.command``, which logs command operations -- ``pymongo.connection``, which logs connection management operations -- ``pymongo.serverSelection``, which logs server selection operations - -In addition to configuring these options individually, you can configure the global -logging level by setting the log level on ``pymongo``. To learn more about the native -logging library, see the `Python logging library documentation `__. - -Examples -~~~~~~~~ - -The following example sets the global logging level to ``INFO``: - -.. code-block:: python - - import logging - logging.getLogger("pymongo").setLevel(logging.INFO) - -The following example sets the log level on the ``pymongo.command`` component to -``DEBUG``: - -.. code-block:: python - - import logging - logging.getLogger("pymongo.command").setLevel(logging.DEBUG) - -Configuring Truncation -~~~~~~~~~~~~~~~~~~~~~~ - -If you enable logging for the ``pymongo.command`` component, the resulting logs will -be truncated after 1000 bytes by default. You can configure this truncation limit -by setting the ``MONGODB_LOG_MAX_DOCUMENT_LENGTH`` environment variable to your -desired length, as shown in the following example: - -.. code-block:: python - - import os - os.environ["MONGODB_LOG_MAX_DOCUMENT_LENGTH"] = "2000" - -API Documentation ------------------ - -To learn more about the methods and classes used to monitor events in the driver, see the -following API documentation: - -- `monitoring <{+api-root+}pymongo/monitoring.html>`__ -- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ \ No newline at end of file diff --git a/source/monitoring-and-logging.txt b/source/monitoring-and-logging.txt new file mode 100644 index 00000000..9dda4ae0 --- /dev/null +++ b/source/monitoring-and-logging.txt @@ -0,0 +1,17 @@ +.. _pymongo-monitoring-logging: + +Monitoring and Logging +====================== + +.. facet:: + :name: programming_language + :values: python + +.. meta:: + :keywords: home + +.. toctree:: + + Monitoring + Logging + Change Streams \ No newline at end of file diff --git a/source/change-streams.txt b/source/monitoring-and-logging/change-streams.txt similarity index 99% rename from source/change-streams.txt rename to source/monitoring-and-logging/change-streams.txt index 318aae5a..4532e452 100644 --- a/source/change-streams.txt +++ b/source/monitoring-and-logging/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/monitoring-and-logging/logging.txt b/source/monitoring-and-logging/logging.txt new file mode 100644 index 00000000..7b16d09d --- /dev/null +++ b/source/monitoring-and-logging/logging.txt @@ -0,0 +1,66 @@ +.. _pymongo-logging: + +======= +Logging +======= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: debugging, printing + +Overview +-------- + +In this guide, you can learn how to configure logging options for different +{+driver-short+} components. + +{+driver-short+} supports {+language+}'s native logging library. You can configure the logging +verbosity for the following components: + +- ``pymongo.command``, which logs command operations +- ``pymongo.connection``, which logs connection management operations +- ``pymongo.serverSelection``, which logs server selection operations + +In addition to configuring these options individually, you can configure the global +logging level by setting the log level on ``pymongo``. To learn more about the native +logging library, see the `Python logging library documentation `__. + +Examples +-------- + +The follwing example sets the global logging level to ``INFO``: + +.. code-block:: python + + import logging + logging.getLogger("pymongo").setLevel(logging.INFO) + +The following example sets the log level on the ``pymongo.command`` component to +``DEBUG``: + +.. code-block:: python + + import logging + logging.getLogger("pymongo.command").setLevel(logging.DEBUG) + +Configuring Truncation +---------------------- + +If you enable logging for the ``pymongo.command`` component, the resulting logs will +be truncated after 1000 bytes by default. You can configure this truncation limit +by setting the ``MONGODB_LOG_MAX_DOCUMENT_LENGTH`` environment variable to your +desired length, as shown in the following example: + +.. code-block:: python + + import os + os.environ["MONGODB_LOG_MAX_DOCUMENT_LENGTH"] = "2000" \ No newline at end of file diff --git a/source/monitoring.txt b/source/monitoring-and-logging/monitoring.txt similarity index 100% rename from source/monitoring.txt rename to source/monitoring-and-logging/monitoring.txt diff --git a/source/security.txt b/source/security.txt index 972ca5ca..841c48f9 100644 --- a/source/security.txt +++ b/source/security.txt @@ -22,6 +22,7 @@ Secure Your Data :titlesonly: :maxdepth: 1 + TLS Authentication In-Use Encryption diff --git a/source/versioning.txt b/source/versioning.txt new file mode 100644 index 00000000..e6891501 --- /dev/null +++ b/source/versioning.txt @@ -0,0 +1,14 @@ +.. _pymongo-versioning: + +========== +Versioning +========== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Release Notes + Compatibility + Upgrade Guides + Previous Versions \ No newline at end of file diff --git a/source/compatibility.txt b/source/versioning/compatibility.txt similarity index 100% rename from source/compatibility.txt rename to source/versioning/compatibility.txt diff --git a/source/motor-async-migration.txt b/source/versioning/motor-async-migration.txt similarity index 100% rename from source/motor-async-migration.txt rename to source/versioning/motor-async-migration.txt diff --git a/source/previous-versions.txt b/source/versioning/previous-versions.txt similarity index 100% rename from source/previous-versions.txt rename to source/versioning/previous-versions.txt diff --git a/source/pymongo-to-async-guide.txt b/source/versioning/pymongo-to-async-guide.txt similarity index 100% rename from source/pymongo-to-async-guide.txt rename to source/versioning/pymongo-to-async-guide.txt diff --git a/source/whats-new.txt b/source/versioning/release-notes.txt similarity index 99% rename from source/whats-new.txt rename to source/versioning/release-notes.txt index dae80463..35a042e5 100644 --- a/source/whats-new.txt +++ b/source/versioning/release-notes.txt @@ -1,8 +1,8 @@ -.. _pymongo-whats-new: +.. _pymongo-release-notes: -========== -What's New -========== +============= +Release Notes +============= .. contents:: On this page :local: diff --git a/source/upgrade.txt b/source/versioning/upgrade.txt similarity index 100% rename from source/upgrade.txt rename to source/versioning/upgrade.txt From c36ee96a171e2873afefbebf24f91f522c4b7e32 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 28 Feb 2025 10:56:38 -0600 Subject: [PATCH 10/33] wip --- source/index.txt | 6 ++---- source/versioning.txt | 2 +- source/versioning/previous-versions.txt | 1 + 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/source/index.txt b/source/index.txt index d6fba128..5e56e132 100644 --- a/source/index.txt +++ b/source/index.txt @@ -15,7 +15,7 @@ MongoDB {+driver-short+} Documentation Getting Started Connect Databases & Collections - CRUD Operations + CRUD Operations Aggregation Data Formats Indexes @@ -24,12 +24,10 @@ MongoDB {+driver-short+} Documentation Atlas Vector Search Monitoring and Logging Security + Third-Party Tools Versioning API Documentation <{+api-root+}> Issues & Help - - Third-Party Tools - Troubleshooting Overview -------- diff --git a/source/versioning.txt b/source/versioning.txt index e6891501..194a40da 100644 --- a/source/versioning.txt +++ b/source/versioning.txt @@ -10,5 +10,5 @@ Versioning Release Notes Compatibility - Upgrade Guides + Upgrade Guides Previous Versions \ No newline at end of file diff --git a/source/versioning/previous-versions.txt b/source/versioning/previous-versions.txt index 31050cb2..1a891831 100644 --- a/source/versioning/previous-versions.txt +++ b/source/versioning/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 `__ From 1527fceba3362c3fc0a53c6170ba7becb0e01266 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 28 Feb 2025 14:44:00 -0600 Subject: [PATCH 11/33] wip --- source/crud.txt | 193 ++++++++++- source/crud/query.txt | 321 ++++-------------- source/crud/{ => query}/count.txt | 0 source/crud/{ => query}/cursors.txt | 0 source/crud/{ => query}/find.txt | 13 +- source/crud/{ => query}/project.txt | 0 .../specify-documents-to-return.txt | 0 source/crud/query/specify-query.txt | 298 ++++++++++++++++ source/data-formats/time-series.txt | 2 +- source/get-started.txt | 6 +- .../usage-examples/crud-sample-app.py | 17 + source/index.txt | 37 +- source/monitoring-and-logging.txt | 43 ++- source/read.txt | 109 ------ source/reference.txt | 16 + .../compatibility.txt | 0 .../migration.txt} | 63 +++- .../previous-versions.txt | 0 .../release-notes.txt | 1 + .../third-party-tools.txt} | 0 source/{versioning => reference}/upgrade.txt | 0 source/versioning.txt | 14 - source/versioning/motor-async-migration.txt | 76 ----- source/write-operations.txt | 121 ------- 24 files changed, 701 insertions(+), 629 deletions(-) rename source/crud/{ => query}/count.txt (100%) rename source/crud/{ => query}/cursors.txt (100%) rename source/crud/{ => query}/find.txt (98%) rename source/crud/{ => query}/project.txt (100%) rename source/crud/{ => query}/specify-documents-to-return.txt (100%) create mode 100644 source/crud/query/specify-query.txt create mode 100644 source/includes/usage-examples/crud-sample-app.py delete mode 100644 source/read.txt create mode 100644 source/reference.txt rename source/{versioning => reference}/compatibility.txt (100%) rename source/{versioning/pymongo-to-async-guide.txt => reference/migration.txt} (76%) rename source/{versioning => reference}/previous-versions.txt (100%) rename source/{versioning => reference}/release-notes.txt (99%) rename source/{tools.txt => reference/third-party-tools.txt} (100%) rename source/{versioning => reference}/upgrade.txt (100%) delete mode 100644 source/versioning.txt delete mode 100644 source/versioning/motor-async-migration.txt delete mode 100644 source/write-operations.txt diff --git a/source/crud.txt b/source/crud.txt index 2f7bf48d..2b05b525 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -22,15 +22,14 @@ CRUD Operations :titlesonly: :maxdepth: 1 - Insert Documents - Query Documents - Update Documents - Delete Documents - Bulk Write Operations - Transactions - Configure CRUD Operations - Store Large Files - Geospatial Queries + Insert Documents + Query Documents + Update Documents + Delete Documents + Bulk Write Operations + Transactions + Configure CRUD Operations + Store Large Files Overview -------- @@ -44,16 +43,184 @@ to MongoDB with various settings. 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. +: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-connect-sample: +.. _pymongo-crud-sample: .. include:: /includes/usage-examples/sample-app-intro.rst -.. literalinclude:: /includes/usage-examples/connect-sample-app.py +.. literalinclude:: /includes/usage-examples/crud-sample-app.py :language: python :copyable: true :linenos: - :emphasize-lines: 4-6 \ No newline at end of file + :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/crud/query.txt b/source/crud/query.txt index 2f26e9cf..c044b031 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -1,8 +1,8 @@ -.. _pymongo-specify-query: +.. _pymongo-query: -=============== -Specify a Query -=============== +===== +Query +===== .. contents:: On this page :local: @@ -15,7 +15,8 @@ Specify a Query :values: reference .. meta:: - :keywords: expressions, operations, read, write, filter + :description: Learn how to use {+driver-short+} to read data from MongoDB. + :keywords: usage examples, query, find, code example .. toctree:: :titlesonly: @@ -27,284 +28,102 @@ Specify a Query Count Documents Distinct Field Values Access Data from a Cursor - Monitor Data Changes Overview -------- -In this guide, you can learn how to specify a query by using {+driver-short+}. +On this page, you can see copyable code examples that show common +methods you can use to find documents with {+driver-short+}. -You can refine the set of documents that a query returns by creating a -**query filter**. A query filter is an expression that specifies the search -criteria MongoDB uses to match documents in a read or write operation. -In a query filter, you can prompt the driver to search for documents with an -exact match to your query, or you can compose query filters to express more -complex matching criteria. +.. tip:: -Sample Data -~~~~~~~~~~~ + To learn more about any of the methods shown on this page, see the link + provided in each section. -The examples in this guide run operations on a collection called -``fruits`` that contains the following documents: +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. -.. code-block:: json +.. _pymongo-query-sample: - { "_id": 1, "name": "apples", "qty": 5, "rating": 3, "color": "red", "type": ["fuji", "honeycrisp"] }, - { "_id": 2, "name": "bananas", "qty": 7, "rating": 4, "color": "yellow", "type": ["cavendish"] }, - { "_id": 3, "name": "oranges", "qty": 6, "rating": 2, "type": ["naval", "mandarin"] }, - { "_id": 4, "name": "pineapple", "qty": 3, "rating": 5, "color": "yellow" }, +.. include:: /includes/usage-examples/sample-app-intro.rst -The following code example shows how to create a database and collection, then -insert the sample documents into your collection: - -.. literalinclude:: /includes/specify-query/specify-queries.py - :start-after: start-sample-data - :end-before: end-sample-data +.. literalinclude:: /includes/usage-examples/sample-app.py :language: python :copyable: + :linenos: + :emphasize-lines: 11-13 -Exact Match ------------ - -Literal value queries return documents with an exact match to your query filter. - -The following example specifies a query filter as a parameter to the ``find()`` -method. The code returns all documents with a ``color`` field value of ``"yellow"``: - -.. io-code-block:: - :copyable: - - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-exact - :end-before: end-find-exact - :language: python - - .. output:: - - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} - -.. tip:: Find All Documents - - To find all documents in a collection, call the ``find()`` method and pass it an - empty query filter. The following example finds all documents in a - collection: - - .. literalinclude:: /includes/specify-query/specify-queries.py - :start-after: start-find-all - :end-before: end-find-all - :language: python - :copyable: - -Comparison Operators --------------------- - -Comparison operators evaluate a document field value against a specified value -in your query filter. The following is a list of common comparison operators: - -- ``$gt``: Greater than -- ``$lte``: Less than or Equal -- ``$ne``: Not equal - -To view a full list of comparison operators, see the :manual:`Comparison Query Operators -` guide in the {+mdb-server+} manual. - -The following example specifies a comparison operator in a query filter as a -parameter to the ``find()`` method. The code returns all documents with a -``rating`` field value greater than ``2``: - -.. io-code-block:: - :copyable: - - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-comparison - :end-before: end-find-comparison - :language: python - - .. output:: - - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} - -Logical Operators ------------------ - -Logical operators match documents by using logic applied to the results of two or -more sets of expressions. The following is a list of logical operators: - -- ``$and``, which returns all documents that match the conditions of *all* clauses -- ``$or``, which returns all documents that match the conditions of *one* clause -- ``$nor``, which returns all documents that *do not* match the conditions of any clause -- ``$not``, which returns all documents that *do not* match the expression - -To learn more about logical operators, see the :manual:`Logical Query Operators -` guide in the {+mdb-server+} manual. - -The following example specifies a logical operator in a query filter as a -parameter to the ``find()`` method. The code returns all documents with a -``qty`` field value greater than ``5`` **or** a ``color`` field value of -``"yellow"``: +Find One +-------- -.. io-code-block:: +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-find-one + :end-before: end-find-one + :language: python :copyable: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-logical - :end-before: end-find-logical - :language: python +To learn more about the ``find_one()`` method, see :ref:`pymongo-retrieve-find-one` in +the Retrieve Data guide. - .. output:: +Find Multiple +------------- - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} - -Array Operators ---------------- - -Array operators match documents based on the value or quantity of elements in an -array field. The following is a list of available array operators: - -- ``$all``, which returns documents with arrays that contain all elements in the query -- ``$elemMatch``, which returns documents if an element in their array field matches all conditions in the query -- ``$size``, which returns all documents with arrays of a specified size - -To learn more about array operators, see the :manual:`Array Query Operators -` guide in the {+mdb-server+} manual. - -The following example specifies an array operator in a query filter as a -parameter to the ``find()`` method. The code returns all documents with a -``type`` array field containing ``2`` elements: - -.. io-code-block:: +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-find + :end-before: end-find + :language: python :copyable: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-array - :end-before: end-find-array - :language: python - - .. output:: +To learn more about the ``find()`` method, see :ref:`pymongo-retrieve-find-multiple` in +the Retrieve Data guide. - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} +Count Documents in a Collection +------------------------------- -Element Operators ------------------ - -Element operators query data based on the presence or type of a field. - -To learn more about element operators, see the :manual:`Element Query Operators -` guide in the {+mdb-server+} manual. - -The following example specifies an element operator in a query filter as a -parameter to the ``find()`` method. The code returns all documents that have a -``color`` field: - -.. io-code-block:: +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-count-all + :end-before: end-count-all + :language: python :copyable: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-element - :end-before: end-find-element - :language: python - - .. output:: - - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} - -Evaluation Operators --------------------- +To learn more about the ``count_documents()`` method, see the +:ref:`pymongo-accurate-count` guide. -Evaluation operators return data based on evaluations of either individual -fields or the entire collection's documents. +Count Documents Returned from a Query +------------------------------------- -The following is a list of common evaluation operators: - -- ``$text``, which performs a text search on the documents -- ``$regex``, which returns documents that match a specified regular expression -- ``$mod``, which performs a modulo operation on the value of a field and - returns documents where the remainder is a specified value - -To view a full list of evaluation operators, see the :manual:`Evaluation Query Operators -` guide in the {+mdb-server+} manual. - -The following example specifies an evaluation operator in a query filter as a -parameter to the ``find()`` method. The code uses a regular expression to return -all documents with a ``name`` field value that has at least two consecutive -``"p"`` characters: - -.. io-code-block:: +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-count-query + :end-before: end-count-query + :language: python :copyable: - .. input:: /includes/specify-query/specify-queries.py - :start-after: start-find-evaluation - :end-before: end-find-evaluation - :language: python - - .. output:: - - {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} - {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} - -Troubleshooting ---------------- +To learn more about the ``count_documents()`` method, see the +:ref:`pymongo-accurate-count` guide. -.. _web-application-querying-by-objectid: +Estimated Document Count +------------------------ -No Results When Querying for a Document by ObjectId in Web Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It's common in web applications to encode documents' ObjectIds in URLs, as shown -in the following code example: - -.. code-block:: python - - "/posts/50b3bda58a02fb9a84d8991e" - -Your web framework passes the ObjectId part of the URL to your request -handler as a string. You must convert the string to an ``ObjectId`` instance -before passing it to the ``find_one()`` method. - -The following code example shows how to perform this conversion in a -`Flask `__ application. The process is similar for other web -frameworks. - -.. code-block:: python - - from pymongo import MongoClient - from bson.objectid import ObjectId - - from flask import Flask, render_template - - client = MongoClient() - app = Flask(__name__) - - @app.route("/posts/<_id>") - def show_post(_id): - # NOTE!: converting _id from string to ObjectId before passing to find_one - post = client.db.posts.find_one({'_id': ObjectId(_id)}) - return render_template('post.html', post=post) - - if __name__ == "__main__": - app.run() - -Additional Information ----------------------- +.. 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 querying documents, see the :manual:`Query Documents -` guide in the {+mdb-server+} manual. +To learn more about the ``estimated_document_count()`` method, see the +:ref:`pymongo-estimated-count` guide. -To learn more about retrieving documents with PyMongo, see -:ref:`pymongo-retrieve`. +Retrieve Distinct Values +------------------------ -API Documentation -~~~~~~~~~~~~~~~~~ +.. literalinclude:: /includes/usage-examples/retrieve-code-examples.py + :start-after: start-distinct + :end-before: end-distinct + :language: python + :copyable: -To learn more about any of the methods or types discussed in this -guide, see the following API documentation: +To learn more about the ``distinct()`` method, see the +:ref:`pymongo-distinct` guide. -- `find() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__ \ No newline at end of file diff --git a/source/crud/count.txt b/source/crud/query/count.txt similarity index 100% rename from source/crud/count.txt rename to source/crud/query/count.txt diff --git a/source/crud/cursors.txt b/source/crud/query/cursors.txt similarity index 100% rename from source/crud/cursors.txt rename to source/crud/query/cursors.txt diff --git a/source/crud/find.txt b/source/crud/query/find.txt similarity index 98% rename from source/crud/find.txt rename to source/crud/query/find.txt index 9aa955a1..cdf001b7 100644 --- a/source/crud/find.txt +++ b/source/crud/query/find.txt @@ -1,8 +1,9 @@ .. _pymongo-retrieve: +.. _pymongo-find: -============= -Retrieve Data -============= +============== +Find Documents +============== .. contents:: On this page :local: @@ -39,8 +40,8 @@ free MongoDB Atlas cluster and load the sample datasets, see the :ref:`` guide in the {+mdb-server+} manual. + +The following example specifies a comparison operator in a query filter as a +parameter to the ``find()`` method. The code returns all documents with a +``rating`` field value greater than ``2``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-comparison + :end-before: end-find-comparison + :language: python + + .. output:: + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + +Logical Operators +----------------- + +Logical operators match documents by using logic applied to the results of two or +more sets of expressions. The following is a list of logical operators: + +- ``$and``, which returns all documents that match the conditions of *all* clauses +- ``$or``, which returns all documents that match the conditions of *one* clause +- ``$nor``, which returns all documents that *do not* match the conditions of any clause +- ``$not``, which returns all documents that *do not* match the expression + +To learn more about logical operators, see the :manual:`Logical Query Operators +` guide in the {+mdb-server+} manual. + +The following example specifies a logical operator in a query filter as a +parameter to the ``find()`` method. The code returns all documents with a +``qty`` field value greater than ``5`` **or** a ``color`` field value of +``"yellow"``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-logical + :end-before: end-find-logical + :language: python + + .. output:: + + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + +Array Operators +--------------- + +Array operators match documents based on the value or quantity of elements in an +array field. The following is a list of available array operators: + +- ``$all``, which returns documents with arrays that contain all elements in the query +- ``$elemMatch``, which returns documents if an element in their array field matches all conditions in the query +- ``$size``, which returns all documents with arrays of a specified size + +To learn more about array operators, see the :manual:`Array Query Operators +` guide in the {+mdb-server+} manual. + +The following example specifies an array operator in a query filter as a +parameter to the ``find()`` method. The code returns all documents with a +``type`` array field containing ``2`` elements: + +.. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-array + :end-before: end-find-array + :language: python + + .. output:: + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 3, 'name': 'oranges', 'qty': 6, 'rating': 2, 'type': ['naval', 'mandarin']} + +Element Operators +----------------- + +Element operators query data based on the presence or type of a field. + +To learn more about element operators, see the :manual:`Element Query Operators +` guide in the {+mdb-server+} manual. + +The following example specifies an element operator in a query filter as a +parameter to the ``find()`` method. The code returns all documents that have a +``color`` field: + +.. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-element + :end-before: end-find-element + :language: python + + .. output:: + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 2, 'name': 'bananas', 'qty': 7, 'rating': 4, 'color': 'yellow', 'type': ['cavendish']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + +Evaluation Operators +-------------------- + +Evaluation operators return data based on evaluations of either individual +fields or the entire collection's documents. + +The following is a list of common evaluation operators: + +- ``$text``, which performs a text search on the documents +- ``$regex``, which returns documents that match a specified regular expression +- ``$mod``, which performs a modulo operation on the value of a field and + returns documents where the remainder is a specified value + +To view a full list of evaluation operators, see the :manual:`Evaluation Query Operators +` guide in the {+mdb-server+} manual. + +The following example specifies an evaluation operator in a query filter as a +parameter to the ``find()`` method. The code uses a regular expression to return +all documents with a ``name`` field value that has at least two consecutive +``"p"`` characters: + +.. io-code-block:: + :copyable: + + .. input:: /includes/specify-query/specify-queries.py + :start-after: start-find-evaluation + :end-before: end-find-evaluation + :language: python + + .. output:: + + {'_id': 1, 'name': 'apples', 'qty': 5, 'rating': 3, 'color': 'red', 'type': ['fuji', 'honeycrisp']} + {'_id': 4, 'name': 'pineapple', 'qty': 3, 'rating': 5, 'color': 'yellow'} + +Troubleshooting +--------------- + +.. _web-application-querying-by-objectid: + +No Results When Querying for a Document by ObjectId in Web Applications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's common in web applications to encode documents' ObjectIds in URLs, as shown +in the following code example: + +.. code-block:: python + + "/posts/50b3bda58a02fb9a84d8991e" + +Your web framework passes the ObjectId part of the URL to your request +handler as a string. You must convert the string to an ``ObjectId`` instance +before passing it to the ``find_one()`` method. + +The following code example shows how to perform this conversion in a +`Flask `__ application. The process is similar for other web +frameworks. + +.. code-block:: python + + from pymongo import MongoClient + from bson.objectid import ObjectId + + from flask import Flask, render_template + + client = MongoClient() + app = Flask(__name__) + + @app.route("/posts/<_id>") + def show_post(_id): + # NOTE!: converting _id from string to ObjectId before passing to find_one + post = client.db.posts.find_one({'_id': ObjectId(_id)}) + return render_template('post.html', post=post) + + if __name__ == "__main__": + app.run() + +Additional Information +---------------------- + +To learn more about querying documents, see the :manual:`Query Documents +` guide in the {+mdb-server+} manual. + +To learn more about retrieving documents with PyMongo, see +:ref:`pymongo-retrieve`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `find() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__ \ No newline at end of file diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt index 7e7e7b6d..0211630b 100644 --- a/source/data-formats/time-series.txt +++ b/source/data-formats/time-series.txt @@ -172,7 +172,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/get-started.txt b/source/get-started.txt index ba9d67d8..57349bdb 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -277,7 +277,9 @@ 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. +- 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/includes/usage-examples/crud-sample-app.py b/source/includes/usage-examples/crud-sample-app.py new file mode 100644 index 00000000..304fbba4 --- /dev/null +++ b/source/includes/usage-examples/crud-sample-app.py @@ -0,0 +1,17 @@ +from pymongo import MongoClient + +try: + # start example code here + + # end example code here + + client.admin.command("ping") + print("Connected successfully") + + # other application code + + client.close() + +except Exception as e: + raise Exception( + "The following error occurred: ", e) diff --git a/source/index.txt b/source/index.txt index 5e56e132..4172f1c9 100644 --- a/source/index.txt +++ b/source/index.txt @@ -25,7 +25,7 @@ MongoDB {+driver-short+} Documentation Monitoring and Logging Security Third-Party Tools - Versioning + Reference API Documentation <{+api-root+}> Issues & Help @@ -54,15 +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 ---------------------- +Read and Write Data +------------------- -Learn how you can write data to MongoDB in the :ref:`pymongo-write` section. - -Read Data from MongoDB ----------------------- - -Learn how you can retrieve data from MongoDB in the :ref:`pymongo-read` section. +Learn how to find, update, and delete data in the :ref:`pymongo-crud` section. Run a Database Command ---------------------- @@ -87,21 +82,17 @@ 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 ----------- +Monitoring and Logging +---------------------- -Learn how to monitor changes to your application in the :ref:`pymongo-monitoring` section. +Learn how to monitor changes to your application and write them to logs in the +:ref:`pymongo-monitoring-logging` section. Serialization ------------- @@ -115,16 +106,10 @@ Third-Party Tools For a list of popular third-party Python libraries for working with MongoDB, see the :ref:`pymongo-tools` section. -Troubleshooting ---------------- - -For solutions to issues you might encounter when using the driver, see the -:ref:`pymongo-troubleshooting` section. - What's New ---------- -For a list of new features and changes in each version, see the :ref:`` +For a list of new features and changes in each version, see the :ref:`` section. Upgrade {+driver-short+} Versions diff --git a/source/monitoring-and-logging.txt b/source/monitoring-and-logging.txt index 9dda4ae0..2ab53e96 100644 --- a/source/monitoring-and-logging.txt +++ b/source/monitoring-and-logging.txt @@ -14,4 +14,45 @@ Monitoring and Logging Monitoring Logging - Change Streams \ No newline at end of file + 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. + +.. start here + + +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/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.txt b/source/read.txt deleted file mode 100644 index 509feda0..00000000 --- a/source/read.txt +++ /dev/null @@ -1,109 +0,0 @@ -Overview --------- - -On this page, you can see copyable code examples that show common -methods you can use to retrieve documents 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-read-sample: - -.. include:: /includes/usage-examples/sample-app-intro.rst - -.. literalinclude:: /includes/usage-examples/sample-app.py - :language: python - :copyable: - :linenos: - :emphasize-lines: 11-13 - -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. - -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/reference.txt b/source/reference.txt new file mode 100644 index 00000000..81b2232f --- /dev/null +++ b/source/reference.txt @@ -0,0 +1,16 @@ +.. _pymongo-reference: + +========== +Reference +========== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Release Notes + Compatibility + Third-Party Tools + Upgrade Guides + Migration Guides + Previous Versions \ No newline at end of file diff --git a/source/versioning/compatibility.txt b/source/reference/compatibility.txt similarity index 100% rename from source/versioning/compatibility.txt rename to source/reference/compatibility.txt diff --git a/source/versioning/pymongo-to-async-guide.txt b/source/reference/migration.txt similarity index 76% rename from source/versioning/pymongo-to-async-guide.txt rename to source/reference/migration.txt index 27b1dbea..2c680956 100644 --- a/source/versioning/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,11 +25,55 @@ 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+} -------------------- +Switch 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. diff --git a/source/versioning/previous-versions.txt b/source/reference/previous-versions.txt similarity index 100% rename from source/versioning/previous-versions.txt rename to source/reference/previous-versions.txt diff --git a/source/versioning/release-notes.txt b/source/reference/release-notes.txt similarity index 99% rename from source/versioning/release-notes.txt rename to source/reference/release-notes.txt index 35a042e5..7756d3ff 100644 --- a/source/versioning/release-notes.txt +++ b/source/reference/release-notes.txt @@ -1,4 +1,5 @@ .. _pymongo-release-notes: +.. _pymongo-whats-new: ============= Release Notes diff --git a/source/tools.txt b/source/reference/third-party-tools.txt similarity index 100% rename from source/tools.txt rename to source/reference/third-party-tools.txt diff --git a/source/versioning/upgrade.txt b/source/reference/upgrade.txt similarity index 100% rename from source/versioning/upgrade.txt rename to source/reference/upgrade.txt diff --git a/source/versioning.txt b/source/versioning.txt deleted file mode 100644 index 194a40da..00000000 --- a/source/versioning.txt +++ /dev/null @@ -1,14 +0,0 @@ -.. _pymongo-versioning: - -========== -Versioning -========== - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Release Notes - Compatibility - Upgrade Guides - Previous Versions \ No newline at end of file diff --git a/source/versioning/motor-async-migration.txt b/source/versioning/motor-async-migration.txt deleted file mode 100644 index ff15fe70..00000000 --- a/source/versioning/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/write-operations.txt b/source/write-operations.txt deleted file mode 100644 index 5f7a7298..00000000 --- a/source/write-operations.txt +++ /dev/null @@ -1,121 +0,0 @@ -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 From 5d819459ae0231deacb6dc3cfbbe4f927a43b837 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 28 Feb 2025 15:12:43 -0600 Subject: [PATCH 12/33] build fixes --- source/connect/connection-options.txt | 9 +++++++++ source/crud/delete.txt | 1 + source/crud/insert.txt | 3 ++- source/crud/query.txt | 12 ++++++------ source/crud/{ => query}/distinct.txt | 0 source/crud/update.txt | 3 ++- source/index.txt | 1 - 7 files changed, 20 insertions(+), 9 deletions(-) rename source/crud/{ => query}/distinct.txt (100%) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 7d9fe378..85a4d106 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -17,6 +17,15 @@ 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 + Overview -------- diff --git a/source/crud/delete.txt b/source/crud/delete.txt index b265809b..d94d0000 100644 --- a/source/crud/delete.txt +++ b/source/crud/delete.txt @@ -1,4 +1,5 @@ .. _pymongo-write-delete: +.. _pymongo-delete: ================ Delete Documents diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 19ed2b42..f91d20d4 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -1,4 +1,5 @@ .. _pymongo-write-insert: +.. _pymongo-insert: ================ Insert Documents @@ -144,7 +145,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/crud/query.txt b/source/crud/query.txt index c044b031..4b100ff7 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -22,12 +22,12 @@ Query :titlesonly: :maxdepth: 1 - Find Documents - Specify Documents to Return - Specify Fields to Return - Count Documents - Distinct Field Values - Access Data from a Cursor + Find Documents + Specify Documents to Return + Specify Fields to Return + Count Documents + Distinct Field Values + Access Data from a Cursor Overview -------- diff --git a/source/crud/distinct.txt b/source/crud/query/distinct.txt similarity index 100% rename from source/crud/distinct.txt rename to source/crud/query/distinct.txt diff --git a/source/crud/update.txt b/source/crud/update.txt index 4f6bbd58..4f1a5809 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -1,4 +1,5 @@ .. _pymongo-write-update: +.. _pymongo-update: ================ Update Documents @@ -21,7 +22,7 @@ Update Documents :titlesonly: :maxdepth: 1 - Replace + Replace Overview -------- diff --git a/source/index.txt b/source/index.txt index 4172f1c9..47d683ec 100644 --- a/source/index.txt +++ b/source/index.txt @@ -24,7 +24,6 @@ MongoDB {+driver-short+} Documentation Atlas Vector Search Monitoring and Logging Security - Third-Party Tools Reference API Documentation <{+api-root+}> Issues & Help From 3dcc58c7b948c042ddc28c0ced1475cae25246a4 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 28 Feb 2025 15:14:04 -0600 Subject: [PATCH 13/33] wip --- snooty.toml | 3 +-- source/connect/{ => connection-options}/csot.txt | 0 .../connect/{ => connection-options}/network-compression.txt | 0 source/connect/{ => connection-options}/server-selection.txt | 0 source/connect/{ => connection-options}/stable-api.txt | 0 5 files changed, 1 insertion(+), 2 deletions(-) rename source/connect/{ => connection-options}/csot.txt (100%) rename source/connect/{ => connection-options}/network-compression.txt (100%) rename source/connect/{ => connection-options}/server-selection.txt (100%) rename source/connect/{ => connection-options}/stable-api.txt (100%) diff --git a/snooty.toml b/snooty.toml index 69c559c1..da1c6f3c 100644 --- a/snooty.toml +++ b/snooty.toml @@ -2,8 +2,6 @@ name = "pymongo" title = "PyMongo" toc_landing_pages = [ "/get-started", - "/write-operations", - "/read", "/connect", "/indexes", "work-with-indexes", @@ -13,6 +11,7 @@ toc_landing_pages = [ "/security/authentication", "/aggregation-tutorials", "/data-formats", + "/connect/connection-options" ] intersphinx = [ 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 100% rename from source/connect/network-compression.txt rename to source/connect/connection-options/network-compression.txt 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 From 531e2b1713e14bb2c5a0e022342bd7241e897901 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 28 Feb 2025 15:55:36 -0600 Subject: [PATCH 14/33] fixes --- source/connect.txt | 3 --- source/crud/query.txt | 1 + .../usage-examples/crud-sample-app.py | 12 +++++++----- source/includes/usage-examples/sample-app.py | 19 ------------------- source/reference.txt | 2 +- 5 files changed, 9 insertions(+), 28 deletions(-) delete mode 100644 source/includes/usage-examples/sample-app.py diff --git a/source/connect.txt b/source/connect.txt index a75fc5a1..1bb4b54f 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,9 +25,6 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options - Compress Network Traffic - Customize Server Selection - Stable API Limit Server Execution Time Overview diff --git a/source/crud/query.txt b/source/crud/query.txt index 4b100ff7..37f2b60a 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -22,6 +22,7 @@ Query :titlesonly: :maxdepth: 1 + Specify a Query Find Documents Specify Documents to Return Specify Fields to Return diff --git a/source/includes/usage-examples/crud-sample-app.py b/source/includes/usage-examples/crud-sample-app.py index 304fbba4..98d245c7 100644 --- a/source/includes/usage-examples/crud-sample-app.py +++ b/source/includes/usage-examples/crud-sample-app.py @@ -1,14 +1,16 @@ +import pymongo from pymongo import MongoClient try: - # start example code here + uri = "" + client = MongoClient(uri) - # end example code here + database = client[""] + collection = database[""] - client.admin.command("ping") - print("Connected successfully") + # start example code here - # other application code + # end example code here client.close() diff --git a/source/includes/usage-examples/sample-app.py b/source/includes/usage-examples/sample-app.py deleted file mode 100644 index 98d245c7..00000000 --- a/source/includes/usage-examples/sample-app.py +++ /dev/null @@ -1,19 +0,0 @@ -import pymongo -from pymongo import MongoClient - -try: - uri = "" - client = MongoClient(uri) - - database = client[""] - collection = database[""] - - # start example code here - - # end example code here - - client.close() - -except Exception as e: - raise Exception( - "The following error occurred: ", e) diff --git a/source/reference.txt b/source/reference.txt index 81b2232f..371ea522 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -12,5 +12,5 @@ Reference Compatibility Third-Party Tools Upgrade Guides - Migration Guides + Migration Guides Previous Versions \ No newline at end of file From 2a6a2ce5fa8456bb85a767cc798001c5de1e636a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 3 Mar 2025 15:39:14 -0600 Subject: [PATCH 15/33] wip --- source/index.txt | 90 +++++++++++++----------------------------------- 1 file changed, 23 insertions(+), 67 deletions(-) diff --git a/source/index.txt b/source/index.txt index 47d683ec..0e1e5b86 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,7 +12,7 @@ MongoDB {+driver-short+} Documentation .. toctree:: - Getting Started + Get Started Connect Databases & Collections CRUD Operations @@ -58,85 +58,52 @@ Read and Write Data Learn how to find, update, and delete data in the :ref:`pymongo-crud` section. -Run a Database Command ----------------------- - -Learn how to run a database command in the :ref:`pymongo-run-command` section. - -Optimize Queries with Indexes ------------------------------ - -Learn how to work with common types of indexes in the :ref:`pymongo-indexes` -section. - 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. - Data Formats ------------ Learn how to work with specialized data formats and custom types in the :ref:`pymongo-data-formats` section. -Monitoring and Logging ----------------------- - -Learn how to monitor changes to your application and write them to logs in the -:ref:`pymongo-monitoring-logging` section. - -Serialization -------------- - -Learn how {+driver-short+} serializes and deserializes data in the -:ref:`pymongo-serialization` section. - -Third-Party Tools ------------------ +Optimize Queries with Indexes +----------------------------- -For a list of popular third-party Python libraries for working with -MongoDB, see the :ref:`pymongo-tools` section. +Learn how to work with common types of indexes in the :ref:`pymongo-indexes` +section. -What's New ----------- +Run a Database Command +---------------------- -For a list of new features and changes in each version, see the :ref:`` -section. +Learn how to run a database command in the :ref:`pymongo-run-command` section. -Upgrade {+driver-short+} Versions ------------------------- +Atlas Search +------------ -Learn what changes you might need to make to your application to upgrade driver versions -in the :ref:`pymongo-upgrade` section. +Learn how to use Atlas Search to build full-text search capabilities in the +:ref:`pymongo-atlas-search` 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+} ----------------------------------------------- +Monitoring and Logging +---------------------- -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. +Learn how to monitor changes to your application and write them to logs in the +:ref:`pymongo-monitoring-logging` 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 ------------- @@ -144,15 +111,4 @@ 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+}>`__. From e2842c1cc571b0c1280824f1713e09a7008e6db3 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 4 Mar 2025 10:06:28 -0600 Subject: [PATCH 16/33] wip --- source/index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index.txt b/source/index.txt index 0e1e5b86..a11b2466 100644 --- a/source/index.txt +++ b/source/index.txt @@ -20,7 +20,7 @@ MongoDB {+driver-short+} Documentation Data Formats Indexes Run a Database Command - Atlas Search + Atlas Search Atlas Vector Search Monitoring and Logging Security From 93e377db526166ecad79d702d9273e63df292553 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 4 Mar 2025 10:18:09 -0600 Subject: [PATCH 17/33] fix build errors --- source/connect.txt | 1 - source/crud/query.txt | 2 +- source/index.txt | 2 +- source/indexes.txt | 2 +- source/monitoring-and-logging.txt | 2 +- 5 files changed, 4 insertions(+), 5 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 1bb4b54f..ef2c17b4 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,7 +25,6 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options - Limit Server Execution Time Overview -------- diff --git a/source/crud/query.txt b/source/crud/query.txt index 37f2b60a..c1dfff27 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -50,7 +50,7 @@ the relevant values for your MongoDB deployment. .. 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: diff --git a/source/index.txt b/source/index.txt index a11b2466..5c5e65b8 100644 --- a/source/index.txt +++ b/source/index.txt @@ -85,7 +85,7 @@ Atlas Search ------------ Learn how to use Atlas Search to build full-text search capabilities in the -:ref:`pymongo-atlas-search` section. +`Atlas Search tutorial `__. Secure Your Data ---------------- diff --git a/source/indexes.txt b/source/indexes.txt index 3ed60759..0e00d9d3 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -45,7 +45,7 @@ the relevant values for your MongoDB deployment. .. 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: diff --git a/source/monitoring-and-logging.txt b/source/monitoring-and-logging.txt index 2ab53e96..1601d95c 100644 --- a/source/monitoring-and-logging.txt +++ b/source/monitoring-and-logging.txt @@ -39,7 +39,7 @@ the relevant values for your MongoDB deployment. .. 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: From 809ba45f19371265fc10e799e00eea1ead01662e Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 4 Mar 2025 11:45:27 -0600 Subject: [PATCH 18/33] fixes --- snooty.toml | 5 +- source/connect/connection-options.txt | 70 +++++++++++++------ source/crud/query/cursors.txt | 3 +- source/crud/query/find.txt | 3 +- .../query/specify-documents-to-return.txt | 3 +- source/data-formats.txt | 2 +- .../custom-types/serialization.txt | 15 +--- source/index.txt | 26 +++++-- source/reference.txt | 2 +- source/reference/migration.txt | 6 +- 10 files changed, 84 insertions(+), 51 deletions(-) diff --git a/snooty.toml b/snooty.toml index da1c6f3c..0f76b028 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,7 +11,10 @@ toc_landing_pages = [ "/security/authentication", "/aggregation-tutorials", "/data-formats", - "/connect/connection-options" + "/connect/connection-options", + "crud", + "/crud/query", + "/crud/update" ] intersphinx = [ diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 85a4d106..91f988e6 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -113,26 +113,9 @@ Network Compression | **MongoClient Example**: ``zlibCompressionLevel = 3`` | **Connection URI Example**: ``zlibCompressionLevel=3`` -Timeouts -~~~~~~~~ +For more information about network compression in {+driver-short+}, see +:ref:``. -.. 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 ~~~~~~~~~~~~~~~~ @@ -153,6 +136,50 @@ Server Selection | **MongoClient Example**: ``server_selector = your_function`` | **Connection URI Example**: N/A +Stable API +~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Connection Option + - Description + + * - ``server_api`` + - | A ``ServerApi`` object that specifies the Stable API version and other Stable API + | options. + | + | **Data Type**: ``ServerApi`` + | **Default**: ``None`` + | **MongoClient Example**: ``server_api = ServerApi("1")`` + | **Connection URI Example**: N/A + +For more information about the Stable API, see :ref:``. + +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`` + +For more information about using timeouts to limit server execution time, see +:ref:``. + Connection Pools ~~~~~~~~~~~~~~~~ @@ -293,7 +320,7 @@ Authentication | **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`. +For more information about the connection options in this section, see :ref:`pymongo-auth`. Read and Write Operations ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -376,4 +403,5 @@ Read and Write Operations | **MongoClient Example**: ``retryWrites=False`` | **Connection URI Example**: ``retryWrites=false`` -For more information about the connection options in this section, see :ref:`pymongo-databases-collections`. +For more information about the connection options in this section, see +:ref:`pymongo-configure-crud`. diff --git a/source/crud/query/cursors.txt b/source/crud/query/cursors.txt index c818b1ae..c788f7bd 100644 --- a/source/crud/query/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/crud/query/find.txt b/source/crud/query/find.txt index cdf001b7..a77e754d 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -36,7 +36,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-retrieve-find: diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index e9d0b5ab..d2eed17f 100644 --- a/source/crud/query/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/data-formats.txt b/source/data-formats.txt index 14612aa2..727d7690 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -26,7 +26,7 @@ Specialized Data Formats Custom Types Dates & Times UUIDs - Time Series + Time Series Data Overview -------- diff --git a/source/data-formats/custom-types/serialization.txt b/source/data-formats/custom-types/serialization.txt index c4fba61b..8079a095 100644 --- a/source/data-formats/custom-types/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. diff --git a/source/index.txt b/source/index.txt index 5c5e65b8..673fda6c 100644 --- a/source/index.txt +++ b/source/index.txt @@ -87,11 +87,13 @@ Atlas Search Learn how to use Atlas Search to build full-text search capabilities in the `Atlas Search tutorial `__. -Secure Your Data ----------------- +Atlas Vector Search +------------------- -Learn about ways you can authenticate your application and encrypt your data in -the :ref:`pymongo-security` 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. Monitoring and Logging ---------------------- @@ -99,6 +101,18 @@ Monitoring and Logging Learn how to monitor changes to your application and write them to logs in the :ref:`pymongo-monitoring-logging` section. +Secure Your Data +---------------- + +Learn about ways you can authenticate your application and encrypt your data in +the :ref:`pymongo-security` section. + +Reference +--------- + +Find more information about {+driver-short+} versions, compatibility, and third-party tools +in the the :ref:`pymongo-reference` section. + API Documentation ----------------- @@ -109,6 +123,4 @@ Issues & Help ------------- Learn how to report bugs, contribute to the driver, and find help in the -:ref:`` section. - - +:ref:`` section. \ No newline at end of file diff --git a/source/reference.txt b/source/reference.txt index 371ea522..979b8264 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -12,5 +12,5 @@ Reference Compatibility Third-Party Tools Upgrade Guides - Migration Guides + Migrate to PyMongo Async Previous Versions \ No newline at end of file diff --git a/source/reference/migration.txt b/source/reference/migration.txt index 2c680956..febf2911 100644 --- a/source/reference/migration.txt +++ b/source/reference/migration.txt @@ -72,12 +72,12 @@ The following Motor method signatures behave differently in the {+driver-async+} .. _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``. From f334ed6a3195b06322d152a580a74617aa18dd76 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 4 Mar 2025 11:53:34 -0600 Subject: [PATCH 19/33] fixes --- snooty.toml | 3 ++- source/index.txt | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/snooty.toml b/snooty.toml index 0f76b028..cbe62272 100644 --- a/snooty.toml +++ b/snooty.toml @@ -14,7 +14,8 @@ toc_landing_pages = [ "/connect/connection-options", "crud", "/crud/query", - "/crud/update" + "/crud/update", + "monitoring-and-logging" ] intersphinx = [ diff --git a/source/index.txt b/source/index.txt index 673fda6c..fafd1266 100644 --- a/source/index.txt +++ b/source/index.txt @@ -111,7 +111,7 @@ Reference --------- Find more information about {+driver-short+} versions, compatibility, and third-party tools -in the the :ref:`pymongo-reference` section. +in the :ref:`pymongo-reference` section. API Documentation ----------------- From d56fcc82aeec43ec6eb35eac6eedee40775fcd5e Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 5 Mar 2025 16:19:54 -0600 Subject: [PATCH 20/33] add redirects --- config/redirects | 39 +++++++++++++++++++++++++++++++ source/monitoring-and-logging.txt | 5 +--- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/config/redirects b/config/redirects index c3cfc2c6..d40ae582 100644 --- a/config/redirects +++ b/config/redirects @@ -19,3 +19,42 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/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}/reference/third-party-tools/ +[*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/reference/upgrade/ +[*-master]: ${prefix}/${version}/write-operations/ -> ${base}/${version}/crud/ \ No newline at end of file diff --git a/source/monitoring-and-logging.txt b/source/monitoring-and-logging.txt index 1601d95c..e1f3874e 100644 --- a/source/monitoring-and-logging.txt +++ b/source/monitoring-and-logging.txt @@ -8,7 +8,7 @@ Monitoring and Logging :values: python .. meta:: - :keywords: home + :keywords: event .. toctree:: @@ -27,9 +27,6 @@ methods you can use to monitor and log events with {+driver-short+}. To learn more about any of the methods shown on this page, see the link provided in each section. -.. start here - - 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 From e5fb7354f744cd1467a505f7c220ab790a6a2b50 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 11 Mar 2025 17:38:24 -0500 Subject: [PATCH 21/33] rm feedback --- source/connect/connection-options.txt | 352 +---------- .../connection-options/connection-pools.txt | 136 ++++ .../network-compression.txt | 29 +- source/crud/configure.txt | 21 +- source/databases-collections.txt | 19 - source/index.txt | 2 +- source/indexes.txt | 592 ++++++++++++++---- source/indexes/atlas-search-index.txt | 155 ----- source/indexes/clustered-index.txt | 52 -- source/indexes/compound-index.txt | 63 -- source/indexes/geospatial-index.txt | 87 --- source/indexes/multikey-index.txt | 63 -- source/indexes/single-field-index.txt | 70 --- source/indexes/text-index.txt | 89 --- source/indexes/unique-index.txt | 64 -- source/indexes/wildcard-index.txt | 56 -- source/work-with-indexes.txt | 153 ----- 17 files changed, 653 insertions(+), 1350 deletions(-) create mode 100644 source/connect/connection-options/connection-pools.txt delete mode 100644 source/indexes/atlas-search-index.txt delete mode 100644 source/indexes/clustered-index.txt delete mode 100644 source/indexes/compound-index.txt delete mode 100644 source/indexes/geospatial-index.txt delete mode 100644 source/indexes/multikey-index.txt delete mode 100644 source/indexes/single-field-index.txt delete mode 100644 source/indexes/text-index.txt delete mode 100644 source/indexes/unique-index.txt delete mode 100644 source/indexes/wildcard-index.txt delete mode 100644 source/work-with-indexes.txt diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 91f988e6..bf7e8e1d 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -21,16 +21,19 @@ Specify Connection Options :titlesonly: :maxdepth: 1 + Enable Authentication Compress Network Traffic Customize Server Selection Stable API Limit Server Execution Time + Connection Pools + Configure CRUD Operations 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: @@ -68,340 +71,21 @@ 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. +To learn about the connection options available in {+driver-short+}, see the following +sections: -.. 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. +- :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 ` -Network Compression -~~~~~~~~~~~~~~~~~~~ +API Documentation +----------------- -.. list-table:: - :header-rows: 1 - :widths: 30 70 +To learn more about creating a ``MongoClient`` object in {+driver-short+}, +see the following API documentation: - * - 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`` - -For more information about network compression in {+driver-short+}, see -:ref:``. - -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 - -Stable API -~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Connection Option - - Description - - * - ``server_api`` - - | A ``ServerApi`` object that specifies the Stable API version and other Stable API - | options. - | - | **Data Type**: ``ServerApi`` - | **Default**: ``None`` - | **MongoClient Example**: ``server_api = ServerApi("1")`` - | **Connection URI Example**: N/A - -For more information about the Stable API, see :ref:``. - -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`` - -For more information about using timeouts to limit server execution time, see -:ref:``. - -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 connecting a new - socket 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. - | - | **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 options 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`` - - * - ``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`` - - * - ``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`` - - * - ``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`` - - * - ``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`` - - * - ``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`` - -For more information about the connection options in this section, see -:ref:`pymongo-configure-crud`. +- `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..8be70288 --- /dev/null +++ b/source/connect/connection-options/connection-pools.txt @@ -0,0 +1,136 @@ +.. _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 connecting a new + socket 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. + | + | **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/connection-options/network-compression.txt b/source/connect/connection-options/network-compression.txt index 8348fdfe..6171ba79 100644 --- a/source/connect/connection-options/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/crud/configure.txt b/source/crud/configure.txt index 1c5c722f..7af6a9c7 100644 --- a/source/crud/configure.txt +++ b/source/crud/configure.txt @@ -159,4 +159,23 @@ example disables retryable reads and writes for a client: 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. \ No newline at end of file +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/databases-collections.txt b/source/databases-collections.txt index e3f99bed..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 ------------------------- diff --git a/source/index.txt b/source/index.txt index fafd1266..2c83cd39 100644 --- a/source/index.txt +++ b/source/index.txt @@ -20,7 +20,7 @@ MongoDB {+driver-short+} Documentation Data Formats Indexes Run a Database Command - Atlas Search + Atlas Search Atlas Vector Search Monitoring and Logging Security diff --git a/source/indexes.txt b/source/indexes.txt index 0e00d9d3..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/crud-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/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>`__ From e717fe5db937f8654a32b9ec1a63e46b4101db06 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 11 Mar 2025 17:43:11 -0500 Subject: [PATCH 22/33] drawer fix --- snooty.toml | 2 -- 1 file changed, 2 deletions(-) diff --git a/snooty.toml b/snooty.toml index cbe62272..f904854c 100644 --- a/snooty.toml +++ b/snooty.toml @@ -3,8 +3,6 @@ title = "PyMongo" toc_landing_pages = [ "/get-started", "/connect", - "/indexes", - "work-with-indexes", "/aggregation", "/aggregation/aggregation-tutorials", "/security", From 3ff14c252ff9968d26bad25db40a57a8b52b481e Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 11:26:23 -0500 Subject: [PATCH 23/33] autobuilder From b773372f1cf5151fd3fdcdf2d7d173a0a792834a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 13:25:39 -0500 Subject: [PATCH 24/33] add redirects --- config/redirects | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/config/redirects b/config/redirects index 37e1d679..5850964c 100644 --- a/config/redirects +++ b/config/redirects @@ -58,6 +58,17 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/ [*-master]: ${prefix}/${version}/tools/ -> ${base}/${version}/reference/third-party-tools/ [*-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/ # temp redirect until DOP deletes unversioned URLs [master]: ${prefix}/compatibility/ -> ${base}/current/compatibility/ From ba92628ade279224089b6ff3ed1c3492b48161cb Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 14 Mar 2025 14:58:45 -0500 Subject: [PATCH 25/33] move agg tutorials --- config/redirects | 7 ++ source/aggregation.txt | 39 +++++- source/aggregation/aggregation-tutorials.txt | 112 ------------------ .../filtered-subset.txt | 4 +- .../group-total.txt | 4 +- .../multi-field-join.txt | 4 +- .../one-to-one-join.txt | 4 +- .../unpack-arrays.txt | 4 +- .../includes/aggregation-tutorial-intro.rst | 45 +++++++ 9 files changed, 93 insertions(+), 130 deletions(-) delete mode 100644 source/aggregation/aggregation-tutorials.txt rename source/aggregation/{aggregation-tutorials => }/filtered-subset.txt (97%) rename source/aggregation/{aggregation-tutorials => }/group-total.txt (98%) rename source/aggregation/{aggregation-tutorials => }/multi-field-join.txt (98%) rename source/aggregation/{aggregation-tutorials => }/one-to-one-join.txt (98%) rename source/aggregation/{aggregation-tutorials => }/unpack-arrays.txt (97%) create mode 100644 source/includes/aggregation-tutorial-intro.rst diff --git a/config/redirects b/config/redirects index 5850964c..7afbd16e 100644 --- a/config/redirects +++ b/config/redirects @@ -70,5 +70,12 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/ [*-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/source/aggregation.txt b/source/aggregation.txt index 82d4160f..e0bbecf3 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/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 From 003210e93ab45b22c64478d62f4f762539c614ac Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 14 Mar 2025 15:04:57 -0500 Subject: [PATCH 26/33] fixes --- snooty.toml | 2 -- source/aggregation.txt | 10 +++++----- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/snooty.toml b/snooty.toml index f904854c..b03ea04d 100644 --- a/snooty.toml +++ b/snooty.toml @@ -4,10 +4,8 @@ toc_landing_pages = [ "/get-started", "/connect", "/aggregation", - "/aggregation/aggregation-tutorials", "/security", "/security/authentication", - "/aggregation-tutorials", "/data-formats", "/connect/connection-options", "crud", diff --git a/source/aggregation.txt b/source/aggregation.txt index e0bbecf3..184acdd7 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -22,11 +22,11 @@ Transform Your Data with Aggregation :titlesonly: :maxdepth: 1 - Filtered Subset - Group & Total - Unpack Arrays & Group - One-to-One Join - Multi-Field Join + Filtered Subset + Group & Total + Unpack Arrays & Group + One-to-One Join + Multi-Field Join Overview -------- From 35ca66cd7705ff179018e1cee4207523020b7255 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 17 Mar 2025 08:51:46 -0500 Subject: [PATCH 27/33] add tls --- source/connect/connection-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index bf7e8e1d..bc0f3881 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -21,7 +21,7 @@ Specify Connection Options :titlesonly: :maxdepth: 1 - Enable Authentication + Enable TLS Compress Network Traffic Customize Server Selection Stable API From 5c0a4d3a2e9cb4319b4d12bafec433b24e40a027 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 17 Mar 2025 10:14:22 -0500 Subject: [PATCH 28/33] move auth --- source/connect/connection-options.txt | 2 +- .../authentication-encryption.txt | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 source/connect/connection-options/authentication-encryption.txt diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index bc0f3881..285fd3fc 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -21,7 +21,7 @@ Specify Connection Options :titlesonly: :maxdepth: 1 - Enable TLS + Authentication and Encryption Compress Network Traffic Customize Server Selection Stable API diff --git a/source/connect/connection-options/authentication-encryption.txt b/source/connect/connection-options/authentication-encryption.txt new file mode 100644 index 00000000..bb484280 --- /dev/null +++ b/source/connect/connection-options/authentication-encryption.txt @@ -0,0 +1,18 @@ +.. _pymongo-connection-auth-encryption: + +============================= +Authentication and Encryption +============================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: authentication, qe, csfle, tls, encryption + +To learn about the authentication and encryption options available in {+driver-short+}, +see the following Security pages: + +- :ref:`Authentication ` +- :ref:`TLS ` \ No newline at end of file From cfc6d97b95c23666a4e4af6fa545dd129b5465ad Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 17 Mar 2025 15:14:45 -0500 Subject: [PATCH 29/33] small changes --- config/redirects | 2 +- source/connect/connection-options.txt | 5 +++++ source/index.txt | 1 + .../{reference/third-party-tools.txt => integrations.txt} | 7 ++++--- 4 files changed, 11 insertions(+), 4 deletions(-) rename source/{reference/third-party-tools.txt => integrations.txt} (98%) diff --git a/config/redirects b/config/redirects index 7afbd16e..1ae71b70 100644 --- a/config/redirects +++ b/config/redirects @@ -55,7 +55,7 @@ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/ [*-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}/reference/third-party-tools/ +[*-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/ diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 285fd3fc..eda25394 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -82,6 +82,11 @@ sections: - :ref:`Connection Pools ` - :ref:`Configure CRUD Operations ` +.. tip:: Authentication and Encryption + + To learn how to enable TLS encryption and authentication in {+driver-short+}, + see :ref:`pymongo-tls` and :ref:`pymongo-auth` in the Security section. + API Documentation ----------------- diff --git a/source/index.txt b/source/index.txt index 2c83cd39..b60934f7 100644 --- a/source/index.txt +++ b/source/index.txt @@ -24,6 +24,7 @@ MongoDB {+driver-short+} Documentation Atlas Vector Search Monitoring and Logging Security + Third-Party Integrations Reference API Documentation <{+api-root+}> Issues & Help diff --git a/source/reference/third-party-tools.txt b/source/integrations.txt similarity index 98% rename from source/reference/third-party-tools.txt rename to source/integrations.txt index de6eaa4d..82551c12 100644 --- a/source/reference/third-party-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: From 99fc6f7132759f7c5509de56d0af2c584667eef0 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 17 Mar 2025 16:19:42 -0500 Subject: [PATCH 30/33] incorporate mm changes --- .../connection-options/connection-pools.txt | 8 +- .../data-formats/custom-types/type-codecs.txt | 409 +++++++++++++----- 2 files changed, 310 insertions(+), 107 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 8be70288..2dfde47f 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -43,8 +43,8 @@ your connection URI: - Description * - ``connectTimeoutMS`` - - | The time that {+driver-short+} waits when connecting a new - socket before timing out. + - | The time that {+driver-short+} waits when establishing a new + connection before timing out. | | **Data Type**: ``int`` | **Default**: ``20000`` @@ -62,7 +62,9 @@ your connection URI: | **Connection URI Example**: ``maxConnecting=3`` * - ``maxIdleTimeMS`` - - | The maximum time that a connection can remain idle in the pool. + - | 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) diff --git a/source/data-formats/custom-types/type-codecs.txt b/source/data-formats/custom-types/type-codecs.txt index f0a89563..9144d31a 100644 --- a/source/data-formats/custom-types/type-codecs.txt +++ b/source/data-formats/custom-types/type-codecs.txt @@ -29,26 +29,54 @@ 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: +``InvalidDocument`` exception, as shown in the following code example. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: - :copyable: true +.. tabs:: - .. input:: - :language: python + .. tab:: Synchronous + :tabid: sync - from decimal import Decimal + .. io-code-block:: + :copyable: true - num = Decimal("45.321") - db["coll"].insert_one({"num": num}) + .. input:: + :language: python - .. output:: - :language: shell + from decimal import Decimal - Traceback (most recent call last): - ... - bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), of - type: + 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. @@ -154,46 +182,97 @@ object as a keyword argument. Pass your ``CodecOptions`` object to the 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: +You can then encode and decode instances of the ``Decimal`` class. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. io-code-block:: - :copyable: true +.. tabs:: + + .. tab:: Synchronous + :tabid: sync - .. input:: - :language: python + .. io-code-block:: + :copyable: true - import pprint - - collection.insert_one({"num": Decimal("45.321")}) - my_doc = collection.find_one() - pprint.pprint(my_doc) + .. input:: + :language: python - .. output:: - :language: shell - - {'_id': ObjectId('...'), 'num': Decimal('45.321')} + 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: +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()) -.. io-code-block:: - :copyable: true + .. output:: + :language: shell - .. input:: - :language: python + {'_id': ObjectId('...'), 'num': Decimal128('45.321')} - import pprint + .. tab:: Asynchronous + :tabid: async - new_collection = db.get_collection("test") - pprint.pprint(new_collection.find_one()) + .. io-code-block:: + :copyable: true - .. output:: - :language: shell + .. input:: + :language: python - {'_id': ObjectId('...'), 'num': Decimal128('45.321')} + 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 ---------------- @@ -209,23 +288,48 @@ return its value as an integer: 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: +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")}) -.. io-code-block:: - :copyable: true + .. output:: + :language: shell - .. input:: - :language: python + Traceback (most recent call last): + ... + bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), + of type: - collection.insert_one({"num": DecimalInt("45.321")}) + .. tab:: Asynchronous + :tabid: async - .. output:: - :language: shell + .. io-code-block:: + :copyable: true - Traceback (most recent call last): - ... - bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), - of type: + .. 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``, @@ -239,32 +343,65 @@ as shown in the following example: # 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: +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: -.. io-code-block:: - :copyable: true +.. tabs:: - .. input:: - :language: python + .. tab:: Synchronous + :tabid: sync - import pprint - from bson.codec_options import CodecOptions + .. io-code-block:: + :copyable: true - decimal_int_codec = DecimalIntCodec() - type_registry = TypeRegistry([decimal_codec, decimal_int_codec]) - codec_options = CodecOptions(type_registry=type_registry) + .. input:: + :language: python - 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) + 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')} - .. output:: - :language: shell + .. tab:: Asynchronous + :tabid: async - {'_id': ObjectId('...'), 'num': Decimal('45.321')} + .. 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:: @@ -306,24 +443,50 @@ The following code example shows this process: 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: +class. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync -.. io-code-block:: - :copyable: true + .. io-code-block:: + :copyable: true - .. input:: - :language: python + .. input:: + :language: python - import pprint + import pprint - collection.insert_one({"num": Decimal("45.321")}) - my_doc = collection.find_one() - pprint.pprint(my_doc) + collection.insert_one({"num": Decimal("45.321")}) + my_doc = collection.find_one() + pprint.pprint(my_doc) - .. output:: - :language: shell + .. output:: + :language: shell - {'_id': ObjectId('...'), 'num': Decimal128('45.321')} + {'_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:: @@ -383,36 +546,74 @@ back into Python objects: 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: +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 + .. io-code-block:: + :copyable: true - .. input:: - :language: python + .. input:: + :language: python - from bson.codec_options import CodecOptions,TypeRegistry + from bson.codec_options import CodecOptions,TypeRegistry - codec_options = CodecOptions( - type_registry=TypeRegistry( - [PickledBinaryDecoder()], fallback_encoder=fallback_pickle_encoder - ) - ) + 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() + 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)) + print(isinstance(my_doc["str"], MyStringType)) + print(isinstance(my_doc["num"], MyNumberType)) - .. output:: - :language: shell + .. output:: + :language: shell - True - True + True + True Limitations ----------- From 786045926735440d56b524ee40739ada7f534678 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Mar 2025 10:55:03 -0500 Subject: [PATCH 31/33] sync with java --- source/connect/connection-options.txt | 1 - .../authentication-encryption.txt | 18 ------------------ source/crud.txt | 3 ++- source/index.txt | 2 +- ...-logging.txt => logging-and-monitoring.txt} | 4 ++-- source/reference.txt | 1 - source/security.txt | 2 +- 7 files changed, 6 insertions(+), 25 deletions(-) delete mode 100644 source/connect/connection-options/authentication-encryption.txt rename source/{monitoring-and-logging.txt => logging-and-monitoring.txt} (96%) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index eda25394..7513aae6 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -21,7 +21,6 @@ Specify Connection Options :titlesonly: :maxdepth: 1 - Authentication and Encryption Compress Network Traffic Customize Server Selection Stable API diff --git a/source/connect/connection-options/authentication-encryption.txt b/source/connect/connection-options/authentication-encryption.txt deleted file mode 100644 index bb484280..00000000 --- a/source/connect/connection-options/authentication-encryption.txt +++ /dev/null @@ -1,18 +0,0 @@ -.. _pymongo-connection-auth-encryption: - -============================= -Authentication and Encryption -============================= - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: authentication, qe, csfle, tls, encryption - -To learn about the authentication and encryption options available in {+driver-short+}, -see the following Security pages: - -- :ref:`Authentication ` -- :ref:`TLS ` \ No newline at end of file diff --git a/source/crud.txt b/source/crud.txt index 2b05b525..fff036c2 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -25,11 +25,12 @@ CRUD Operations Insert Documents Query Documents Update Documents + Replace Documents Delete Documents Bulk Write Operations Transactions - Configure CRUD Operations Store Large Files + Configure CRUD Operations Overview -------- diff --git a/source/index.txt b/source/index.txt index b60934f7..2214ec32 100644 --- a/source/index.txt +++ b/source/index.txt @@ -100,7 +100,7 @@ Monitoring and Logging ---------------------- Learn how to monitor changes to your application and write them to logs in the -:ref:`pymongo-monitoring-logging` section. +:ref:`pymongo-logging-monitoring` section. Secure Your Data ---------------- diff --git a/source/monitoring-and-logging.txt b/source/logging-and-monitoring.txt similarity index 96% rename from source/monitoring-and-logging.txt rename to source/logging-and-monitoring.txt index e1f3874e..fb6c273b 100644 --- a/source/monitoring-and-logging.txt +++ b/source/logging-and-monitoring.txt @@ -1,6 +1,6 @@ -.. _pymongo-monitoring-logging: +.. _pymongo-logging-monitoring: -Monitoring and Logging +Logging and Monitoring ====================== .. facet:: diff --git a/source/reference.txt b/source/reference.txt index 979b8264..6529672e 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -10,7 +10,6 @@ Reference Release Notes Compatibility - Third-Party Tools Upgrade Guides Migrate to PyMongo Async Previous Versions \ No newline at end of file diff --git a/source/security.txt b/source/security.txt index 841c48f9..cd5ff3ef 100644 --- a/source/security.txt +++ b/source/security.txt @@ -22,9 +22,9 @@ Secure Your Data :titlesonly: :maxdepth: 1 - TLS Authentication In-Use Encryption + TLS Overview -------- From f55e725c9d710b6254a88c3fa22cee54541021c3 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Mar 2025 11:07:12 -0500 Subject: [PATCH 32/33] remove crud options --- source/connect/connection-options.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 7513aae6..4aed4b87 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -26,7 +26,6 @@ Specify Connection Options Stable API Limit Server Execution Time Connection Pools - Configure CRUD Operations Overview -------- From 13ccbf6a1d84f2dd8a2b289dd334f911171774bc Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Mar 2025 13:36:34 -0500 Subject: [PATCH 33/33] fixes --- source/crud/{update => }/replace.txt | 0 source/crud/update.txt | 6 ------ .../change-streams.txt | 0 .../logging.txt | 0 .../monitoring.txt | 0 5 files changed, 6 deletions(-) rename source/crud/{update => }/replace.txt (100%) rename source/{monitoring-and-logging => logging-and-monitoring}/change-streams.txt (100%) rename source/{monitoring-and-logging => logging-and-monitoring}/logging.txt (100%) rename source/{monitoring-and-logging => logging-and-monitoring}/monitoring.txt (100%) diff --git a/source/crud/update/replace.txt b/source/crud/replace.txt similarity index 100% rename from source/crud/update/replace.txt rename to source/crud/replace.txt diff --git a/source/crud/update.txt b/source/crud/update.txt index 4f1a5809..a1968a2d 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -18,12 +18,6 @@ Update Documents .. meta:: :keywords: modify, change, bulk, code example -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Replace - Overview -------- diff --git a/source/monitoring-and-logging/change-streams.txt b/source/logging-and-monitoring/change-streams.txt similarity index 100% rename from source/monitoring-and-logging/change-streams.txt rename to source/logging-and-monitoring/change-streams.txt diff --git a/source/monitoring-and-logging/logging.txt b/source/logging-and-monitoring/logging.txt similarity index 100% rename from source/monitoring-and-logging/logging.txt rename to source/logging-and-monitoring/logging.txt diff --git a/source/monitoring-and-logging/monitoring.txt b/source/logging-and-monitoring/monitoring.txt similarity index 100% rename from source/monitoring-and-logging/monitoring.txt rename to source/logging-and-monitoring/monitoring.txt