From 7cba80d01ec1e26a78e0b04783e06e3931c91383 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 12 Mar 2025 14:38:29 -0400 Subject: [PATCH 01/31] toc tweaks --- snooty.toml | 1 + .../databases-collections.txt | 0 source/get-started.txt | 212 +++++++++++++++++- source/get-started/connect-to-mongodb.txt | 50 ----- source/get-started/connection-string.txt | 53 ----- source/get-started/create-deployment.txt | 29 --- source/get-started/download-and-install.txt | 61 ----- source/get-started/next-steps.txt | 19 -- .../get-started/quickstart-troubleshoot.rst | 2 +- source/index.txt | 3 +- source/references.txt | 16 ++ .../compatibility.txt | 0 .../integrations.txt | 6 +- source/{versioning => references}/legacy.txt | 0 source/{versioning => references}/upgrade.txt | 0 .../{versioning => references}/whats-new.txt | 0 source/versioning.txt | 15 -- 17 files changed, 232 insertions(+), 235 deletions(-) rename source/{get-started => }/databases-collections.txt (100%) delete mode 100644 source/get-started/connect-to-mongodb.txt delete mode 100644 source/get-started/connection-string.txt delete mode 100644 source/get-started/create-deployment.txt delete mode 100644 source/get-started/download-and-install.txt delete mode 100644 source/get-started/next-steps.txt create mode 100644 source/references.txt rename source/{versioning => references}/compatibility.txt (100%) rename source/{get-started => references}/integrations.txt (98%) rename source/{versioning => references}/legacy.txt (100%) rename source/{versioning => references}/upgrade.txt (100%) rename source/{versioning => references}/whats-new.txt (100%) delete mode 100644 source/versioning.txt diff --git a/snooty.toml b/snooty.toml index e550a15d9..84cb3ae7e 100644 --- a/snooty.toml +++ b/snooty.toml @@ -13,6 +13,7 @@ toc_landing_pages = [ "/crud", "/crud/builders", "/data-formats", + "/references", "/api-documentation", "/security", "/security/auth" diff --git a/source/get-started/databases-collections.txt b/source/databases-collections.txt similarity index 100% rename from source/get-started/databases-collections.txt rename to source/databases-collections.txt diff --git a/source/get-started.txt b/source/get-started.txt index 4dec6ef26..49621c323 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -19,8 +19,6 @@ Get Started with the Java Driver Create a Connection String Connect to MongoDB Next Steps - Databases & Collections - Integrations Overview -------- @@ -49,4 +47,212 @@ deployment. The tutorial includes the following sections: that connects to MongoDB and queries data stored in your deployment. If you prefer to connect to MongoDB using a different driver or -programming language, see our :driver:`list of official drivers <>`. \ No newline at end of file +programming language, see our :driver:`list of official drivers <>`. + +.. _java-get-started-download-and-install: + +Download and Install +-------------------- + +Complete the following steps to install the {+driver-short+} and +its dependencies in your development environment. + +.. procedure:: + :style: connected + + .. step:: Install the driver dependencies + + Before you begin this tutorial, ensure that you install + the following dependencies: + + - `JDK `__ + version 8 or later + - Integrated development environment (IDE), such as `IntelliJ IDEA `__ + or `Eclipse `__ + + .. note:: + + This tutorial shows how to install the {+driver-short+} by using + Maven or Gradle in an IDE. If you do not use an IDE, visit `Building Maven + `__ + or `Creating New Gradle Builds `__ + to learn how to set up your project. + + .. step:: Install the {+driver-short+} + + In your IDE, create a new `Maven `__ or `Gradle `__ + project. If you use Maven, add the following code to your ``pom.xml`` dependencies list: + + .. code-block:: xml + + + + org.mongodb + mongodb-driver-sync + {+full-version+} + + + + If you use Gradle, add the following code to your ``build.gradle`` dependencies list: + + .. code-block:: groovy + + dependencies { + implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}' + } + + After you configure your dependencies, ensure they are available to your + project by running your dependency manager and refreshing + the project in your IDE. + +After you complete these steps, you have a new project +and the driver dependencies installed. + +.. _java-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 a free tier MongoDB deployment. + Ensure that you :atlas:`load sample data ` and + :atlas:`add your IP address ` to the IP access + list. + + .. 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. + +.. _java-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. + +.. 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:`Clusters` section. Click the :guilabel:`Connect` button + for your new deployment, as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_connect_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Then, proceed to the :guilabel:`Connect your application` section. Select + "Java" from the :guilabel:`Driver` selection menu and the version + that best matches the version you installed from the :guilabel:`Version` + selection menu. + + .. 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_uri_java.png + :alt: The connection string copy button in the Atlas UI + + .. step:: Edit your connection string placeholders + + Paste your connection string into a file in your preferred text editor + and save this file to a safe location for later use. In your connection + string, replace the ```` and ```` placeholders with + your database user's username and password. + +After completing these steps, you have a connection string that +contains your database username and password. + +Run a Sample Query +------------------ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +After retrieving the connection string for your MongoDB Atlas deployment, +you can connect to the deployment from your Java application and query +the Atlas sample datasets. + +.. procedure:: + :style: connected + + .. step:: Create your Java application file + + In your project's base package directory, create a file called + ``QuickStart.java``. Copy and paste the following code into this file, + which queries the ``movies`` collection in the ``sample_mflix`` database: + + .. literalinclude:: /includes/get-started/code-snippets/QuickStart.java + :start-after: begin QuickStart + :end-before: end QuickStart + :language: java + :dedent: + + .. step:: Assign the connection string + + Replace the ```` placeholder with the connection string + that you copied from the :ref:`java-get-started-connection-string` step of this + guide. + + .. step:: Run your Java application + + Run your application in your IDE or your shell. Your output + contains details about the retrieved movie document: + + .. include:: /includes/get-started/query-output.rst + + .. include:: /includes/get-started/jdk-tls-issue.rst + +After you complete these steps, you have a Java application that +connects to your MongoDB deployment, runs a query on the sample +data, and returns a matching document. + +.. _java-get-started-next-steps: + +Next Steps +---------- + +Congratulations on completing the tutorial! + +.. include:: /includes/get-started/quickstart-troubleshoot.rst + +In this tutorial, you created a {+driver-short+} application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +You can continue to develop your sample application by +visiting the following guides: + +- :ref:`java-db-coll`: Learn more about interacting with + MongoDB databases and collections. +- :ref:`java-integrations`: Learn about the third-party + integrations that you can use with the {+driver-short+}. \ 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 287892833..000000000 --- a/source/get-started/connect-to-mongodb.txt +++ /dev/null @@ -1,50 +0,0 @@ -================== -Connect to MongoDB -================== - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: test connection, runnable, code example - -After retrieving the connection string for your MongoDB Atlas deployment, -you can connect to the deployment from your Java application and query -the Atlas sample datasets. - -.. procedure:: - :style: connected - - .. step:: Create your Java application file - - In your project's base package directory, create a file called - ``QuickStart.java``. Copy and paste the following code into this file, - which queries the ``movies`` collection in the ``sample_mflix`` database: - - .. literalinclude:: /includes/get-started/code-snippets/QuickStart.java - :start-after: begin QuickStart - :end-before: end QuickStart - :language: java - :dedent: - - .. step:: Assign the connection string - - Replace the ```` placeholder with the connection string - that you copied from the :ref:`java-get-started-connection-string` step of this - guide. - - .. step:: Run your Java application - - Run your application in your IDE or your shell. Your output - contains details about the retrieved movie document: - - .. include:: /includes/get-started/query-output.rst - - .. include:: /includes/get-started/jdk-tls-issue.rst - -After you complete these steps, you have a Java application that -connects to your MongoDB deployment, runs a query on the sample -data, and returns a matching document. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/get-started/connection-string.txt b/source/get-started/connection-string.txt deleted file mode 100644 index d5e1dc250..000000000 --- a/source/get-started/connection-string.txt +++ /dev/null @@ -1,53 +0,0 @@ -.. _java-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. - -.. 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:`Clusters` section. Click the :guilabel:`Connect` button - for your new deployment, as shown in the following screenshot: - - .. figure:: /includes/figures/atlas_connection_connect_cluster.png - :alt: The connect button in the clusters section of the Atlas UI - - Then, proceed to the :guilabel:`Connect your application` section. Select - "Java" from the :guilabel:`Driver` selection menu and the version - that best matches the version you installed from the :guilabel:`Version` - selection menu. - - .. 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_uri_java.png - :alt: The connection string copy button in the Atlas UI - - .. step:: Edit your connection string placeholders - - Paste your connection string into a file in your preferred text editor - and save this file to a safe location for later use. In your connection - string, replace the ```` and ```` placeholders with - your database user's username and password. - -After completing these steps, you have a connection string that -contains your database username and password. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-deployment.txt b/source/get-started/create-deployment.txt deleted file mode 100644 index adf078dbe..000000000 --- a/source/get-started/create-deployment.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. _java-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 a free tier MongoDB deployment. - Ensure that you :atlas:`load sample data ` and - :atlas:`add your IP address ` to the IP access - list. - - .. 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. \ No newline at end of file diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt deleted file mode 100644 index 25809997f..000000000 --- a/source/get-started/download-and-install.txt +++ /dev/null @@ -1,61 +0,0 @@ -.. _java-get-started-download-and-install: - -==================== -Download and Install -==================== - -Complete the following steps to install the {+driver-short+} and -its dependencies in your development environment. - -.. procedure:: - :style: connected - - .. step:: Install the driver dependencies - - Before you begin this tutorial, ensure that you install - the following dependencies: - - - `JDK `__ - version 8 or later - - Integrated development environment (IDE), such as `IntelliJ IDEA `__ - or `Eclipse `__ - - .. note:: - - This tutorial shows how to install the {+driver-short+} by using - Maven or Gradle in an IDE. If you do not use an IDE, visit `Building Maven - `__ - or `Creating New Gradle Builds `__ - to learn how to set up your project. - - .. step:: Install the {+driver-short+} - - In your IDE, create a new `Maven `__ or `Gradle `__ - project. If you use Maven, add the following code to your ``pom.xml`` dependencies list: - - .. code-block:: xml - - - - org.mongodb - mongodb-driver-sync - {+full-version+} - - - - If you use Gradle, add the following code to your ``build.gradle`` dependencies list: - - .. code-block:: groovy - - dependencies { - implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}' - } - - After you configure your dependencies, ensure they are available to your - project by running your dependency manager and refreshing - the project in your IDE. - -After you complete these steps, you have a new project -and the driver dependencies installed. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt deleted file mode 100644 index 8be4e1fb3..000000000 --- a/source/get-started/next-steps.txt +++ /dev/null @@ -1,19 +0,0 @@ -.. _java-get-started-next-steps: - -========== -Next Steps -========== - -Congratulations on completing the tutorial! - -In this tutorial, you created a {+driver-short+} application that -connects to a MongoDB deployment hosted on MongoDB Atlas -and retrieves a document that matches a query. - -You can continue to develop your sample application by -visiting the following guides: - -- :ref:`java-db-coll`: Learn more about interacting with - MongoDB databases and collections. -- :ref:`java-integrations`: Learn about the third-party - integrations that you can use with the {+driver-short+}. \ No newline at end of file diff --git a/source/includes/get-started/quickstart-troubleshoot.rst b/source/includes/get-started/quickstart-troubleshoot.rst index 390289f41..803f050a2 100644 --- a/source/includes/get-started/quickstart-troubleshoot.rst +++ b/source/includes/get-started/quickstart-troubleshoot.rst @@ -1,6 +1,6 @@ .. note:: - If you run into issues on this step, ask for help in the + If you run into issues in this tutorial, ask for help in the :community-forum:`MongoDB Community Forums ` or submit feedback by using the :guilabel:`Rate this page` tab on the right or bottom right side of this page. \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 06b623cd3..fe263dbdc 100644 --- a/source/index.txt +++ b/source/index.txt @@ -20,6 +20,7 @@ MongoDB Java Driver Get Started Connect + Databases & Collections CRUD Operations Data Formats Indexes @@ -28,7 +29,7 @@ MongoDB Java Driver Atlas Vector Search Logging and Monitoring Security - Versioning + References API Documentation Issues & Help diff --git a/source/references.txt b/source/references.txt new file mode 100644 index 000000000..c6eda2b81 --- /dev/null +++ b/source/references.txt @@ -0,0 +1,16 @@ +========== +References +========== + +.. meta:: + :description: Find references material for the {+driver-long+}. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Release Notes + Compatibility + Third-Party Integrations + Upgrade + Migrate from the Legacy API \ No newline at end of file diff --git a/source/versioning/compatibility.txt b/source/references/compatibility.txt similarity index 100% rename from source/versioning/compatibility.txt rename to source/references/compatibility.txt diff --git a/source/get-started/integrations.txt b/source/references/integrations.txt similarity index 98% rename from source/get-started/integrations.txt rename to source/references/integrations.txt index d8929a1ca..fa329cc8a 100644 --- a/source/get-started/integrations.txt +++ b/source/references/integrations.txt @@ -1,8 +1,8 @@ .. _java-integrations: -=================== -Driver Integrations -=================== +======================== +Third-Party Integrations +======================== .. facet:: :name: genre diff --git a/source/versioning/legacy.txt b/source/references/legacy.txt similarity index 100% rename from source/versioning/legacy.txt rename to source/references/legacy.txt diff --git a/source/versioning/upgrade.txt b/source/references/upgrade.txt similarity index 100% rename from source/versioning/upgrade.txt rename to source/references/upgrade.txt diff --git a/source/versioning/whats-new.txt b/source/references/whats-new.txt similarity index 100% rename from source/versioning/whats-new.txt rename to source/references/whats-new.txt diff --git a/source/versioning.txt b/source/versioning.txt deleted file mode 100644 index 90c9e35b6..000000000 --- a/source/versioning.txt +++ /dev/null @@ -1,15 +0,0 @@ -========== -Versioning -========== - -.. meta:: - :description: Learn about versioning in the {+driver-long+}. - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Release Notes - Compatibility - Upgrade - Migrate from the Legacy API \ No newline at end of file From 23928aa7621be7dce3d9dd6c807ad09a4d1097e4 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Thu, 13 Mar 2025 15:14:07 -0400 Subject: [PATCH 02/31] crud --- config/redirects | 116 +++++++++--------- snooty.toml | 3 +- source/{crud => }/aggregation.txt | 5 + .../aggregation-expression-operations.txt | 0 source/{crud => }/builders.txt | 12 +- source/{crud => }/builders/aggregates.txt | 0 source/{crud => }/builders/filters.txt | 0 source/{crud => }/builders/indexes.txt | 0 source/{crud => }/builders/projections.txt | 0 source/{crud => }/builders/sort.txt | 0 source/{crud => }/builders/updates.txt | 0 .../connection/specify-connection-options.txt | 19 +-- source/crud.txt | 13 +- source/crud/{write-operations => }/bulk.txt | 4 +- source/crud/{write-operations => }/delete.txt | 0 source/crud/{write-operations => }/insert.txt | 0 source/crud/query-documents.txt | 29 +++++ .../count.txt | 0 .../cursor.txt | 0 .../distinct.txt | 0 .../retrieve.txt => query-documents/find.txt} | 10 +- .../geo.txt | 0 .../limit.txt | 0 .../project.txt | 0 .../skip.txt | 0 .../sort.txt | 0 .../specify-query.txt} | 0 .../text.txt | 0 source/crud/update-documents.txt | 19 +++ .../embedded-arrays.txt | 0 .../modify.txt | 0 .../upsert.txt | 0 source/crud/write-operations.txt | 25 ---- source/index.txt | 4 +- source/usage-examples/find.txt | 6 +- source/usage-examples/findOne.txt | 6 +- 36 files changed, 149 insertions(+), 122 deletions(-) rename source/{crud => }/aggregation.txt (98%) rename source/{crud => aggregation}/aggregation-expression-operations.txt (100%) rename source/{crud => }/builders.txt (92%) rename source/{crud => }/builders/aggregates.txt (100%) rename source/{crud => }/builders/filters.txt (100%) rename source/{crud => }/builders/indexes.txt (100%) rename source/{crud => }/builders/projections.txt (100%) rename source/{crud => }/builders/sort.txt (100%) rename source/{crud => }/builders/updates.txt (100%) rename source/crud/{write-operations => }/bulk.txt (99%) rename source/crud/{write-operations => }/delete.txt (100%) rename source/crud/{write-operations => }/insert.txt (100%) create mode 100644 source/crud/query-documents.txt rename source/crud/{read-operations => query-documents}/count.txt (100%) rename source/crud/{read-operations => query-documents}/cursor.txt (100%) rename source/crud/{read-operations => query-documents}/distinct.txt (100%) rename source/crud/{read-operations/retrieve.txt => query-documents/find.txt} (96%) rename source/crud/{read-operations => query-documents}/geo.txt (100%) rename source/crud/{read-operations => query-documents}/limit.txt (100%) rename source/crud/{read-operations => query-documents}/project.txt (100%) rename source/crud/{read-operations => query-documents}/skip.txt (100%) rename source/crud/{read-operations => query-documents}/sort.txt (100%) rename source/crud/{query-document.txt => query-documents/specify-query.txt} (100%) rename source/crud/{read-operations => query-documents}/text.txt (100%) create mode 100644 source/crud/update-documents.txt rename source/crud/{write-operations => update-documents}/embedded-arrays.txt (100%) rename source/crud/{write-operations => update-documents}/modify.txt (100%) rename source/crud/{write-operations => update-documents}/upsert.txt (100%) delete mode 100644 source/crud/write-operations.txt diff --git a/config/redirects b/config/redirects index bfe5774c4..f7c6750f9 100644 --- a/config/redirects +++ b/config/redirects @@ -14,61 +14,61 @@ raw: ${prefix}/master -> ${base}/upcoming/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/ [*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ [*-v4.8]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/ -[master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/read-operations/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/read-operations/retrieve/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/read-operations/cursor/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/read-operations/sort/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/read-operations/skip/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/read-operations/limit/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/read-operations/project/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/read-operations/geo/ -[master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/read-operations/text/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/write-operations/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/write-operations/insert/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/write-operations/delete/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/write-operations/modify/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/write-operations/embedded-arrays/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/write-operations/upsert/ -[master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/write-operations/bulk/ -[master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-document/ -[master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ -[master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/ -[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/ -[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/ -[master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/ -[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/ -[master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/ -[master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/ -[master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/ -[master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/ -[master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/mongoclient -[master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/ -[master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/ -[master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/ -[master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/ -[master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/ -[master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/ -[master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/crud/builders/ -[master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/crud/builders/aggregates/ -[master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/crud/builders/filters/ -[master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/crud/builders/indexes/ -[master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/crud/builders/projections/ -[master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/crud/builders/sort/ -[master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/crud/builders/updates/ -[master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/ -[master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/crud/aggregation/ -[master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/crud/aggregation-expression-operations/ -[master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/ -[master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/ -[master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/ -[master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ -[master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ -[master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/ -[master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/ -[master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/ -[master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/ -[master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/ -[master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/ -[master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/query-documents/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query-documents/find/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/query-documents/cursor/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/query-documents/sort/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/query-documents/skip/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/query-documents/limit/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query-documents/project/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query-documents/geo/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/query-documents/text/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/update-documents/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/update-documents/insert/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/update-documents/delete/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/update-documents/modify/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/update-documents/embedded-arrays/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/update-documents/upsert/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/bulk/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-documents/specify-query/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/ +[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/mongoclient +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/ +[v5.3-master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/builders/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/builders/aggregates/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/builders/filters/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/builders/indexes/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/builders/projections/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/builders/sort/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/builders/updates/ +[v5.3-master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/ +[v5.3-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/aggregation/ +[v5.3-master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/aggregation/aggregation-expression-operations/ +[v5.3-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/ +[v5.3-master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/ +[v5.3-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/ +[v5.3-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ +[v5.3-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ +[v5.3-master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/ +[v5.3-master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/ +[v5.3-master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/ +[v5.3-master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/ +[v5.3-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/ +[v5.3-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/ +[v5.3-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/ diff --git a/snooty.toml b/snooty.toml index 84cb3ae7e..ed695a8f3 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,7 +11,8 @@ toc_landing_pages = [ "/connection", "/connection/specify-connection-options", "/crud", - "/crud/builders", + "/aggregation", + "/builders", "/data-formats", "/references", "/api-documentation", diff --git a/source/crud/aggregation.txt b/source/aggregation.txt similarity index 98% rename from source/crud/aggregation.txt rename to source/aggregation.txt index defdb8d4e..22bf262cb 100644 --- a/source/crud/aggregation.txt +++ b/source/aggregation.txt @@ -17,6 +17,11 @@ Aggregation :depth: 2 :class: singlecol +.. toctree:: + :caption: Aggregation + + Aggregation Expressions + Overview -------- diff --git a/source/crud/aggregation-expression-operations.txt b/source/aggregation/aggregation-expression-operations.txt similarity index 100% rename from source/crud/aggregation-expression-operations.txt rename to source/aggregation/aggregation-expression-operations.txt diff --git a/source/crud/builders.txt b/source/builders.txt similarity index 92% rename from source/crud/builders.txt rename to source/builders.txt index eb906a6b4..77153a825 100644 --- a/source/crud/builders.txt +++ b/source/builders.txt @@ -6,12 +6,12 @@ Builders .. toctree:: - Aggregation - Filters - Indexes - Projection - Sort - Update + Aggregation + Filters + Indexes + Projection + Sort + Update .. contents:: On this page :local: diff --git a/source/crud/builders/aggregates.txt b/source/builders/aggregates.txt similarity index 100% rename from source/crud/builders/aggregates.txt rename to source/builders/aggregates.txt diff --git a/source/crud/builders/filters.txt b/source/builders/filters.txt similarity index 100% rename from source/crud/builders/filters.txt rename to source/builders/filters.txt diff --git a/source/crud/builders/indexes.txt b/source/builders/indexes.txt similarity index 100% rename from source/crud/builders/indexes.txt rename to source/builders/indexes.txt diff --git a/source/crud/builders/projections.txt b/source/builders/projections.txt similarity index 100% rename from source/crud/builders/projections.txt rename to source/builders/projections.txt diff --git a/source/crud/builders/sort.txt b/source/builders/sort.txt similarity index 100% rename from source/crud/builders/sort.txt rename to source/builders/sort.txt diff --git a/source/crud/builders/updates.txt b/source/builders/updates.txt similarity index 100% rename from source/crud/builders/updates.txt rename to source/builders/updates.txt diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index c9b63fdbc..e2ce531b9 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -6,8 +6,8 @@ Specify Connection Options .. toctree:: - MongoClient Settings - Connection URI Options + + Connection URI Options MongoClient Settings Stable API Network Compression JNDI Datasource @@ -21,11 +21,12 @@ Specify Connection Options .. meta:: :keywords: connection string, URI, Atlas, code example +Overview +-------- -- :ref:`MongoClient Settings ` -- :ref:`Connection URI Options ` -- :ref:`Stable API ` -- :ref:`Network Compression ` -- :ref:`JNDI Datasource ` -- `AWS Lambda `__ -- :ref:`Connection Security Options ` \ No newline at end of file +This section describes the MongoDB connection and authentication options +available in the {+driver-short+}. You can specify connection options in the +following ways: + +- :ref:`Specifying query parameters in the connection URI` you pass to the ``MongoClient`` constructor +- :ref:`Defining a MongoClientSettings object ` and passing it to the ``MongoClient`` constructor \ No newline at end of file diff --git a/source/crud.txt b/source/crud.txt index 3fc0b0fde..e11c55c8b 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -7,21 +7,20 @@ CRUD Operations .. toctree:: :caption: CRUD Operations - Read - Write - Query + Insert Documents + Query Documents + Update Documents + Delete Documents + Bulk Operations Compound Operations Transactions - Builders - Aggregation - Aggregation Expressions Collations Large File Storage with GridFS CRUD (Create, Read, Update, Delete) operations enable you to work with data stored in MongoDB. -- :ref:`Read Operations ` find and return +- :ref:`Query Documents ` find and return documents stored in your database. - :ref:`Write Operations ` insert, modify, or delete documents in your database. diff --git a/source/crud/write-operations/bulk.txt b/source/crud/bulk.txt similarity index 99% rename from source/crud/write-operations/bulk.txt rename to source/crud/bulk.txt index 8d0ee7e59..f675fe504 100644 --- a/source/crud/write-operations/bulk.txt +++ b/source/crud/bulk.txt @@ -1,8 +1,8 @@ .. _java-fundamentals-bulkwrite: -=============== +===================== Bulk Operations -=============== +===================== .. contents:: On this page :local: diff --git a/source/crud/write-operations/delete.txt b/source/crud/delete.txt similarity index 100% rename from source/crud/write-operations/delete.txt rename to source/crud/delete.txt diff --git a/source/crud/write-operations/insert.txt b/source/crud/insert.txt similarity index 100% rename from source/crud/write-operations/insert.txt rename to source/crud/insert.txt diff --git a/source/crud/query-documents.txt b/source/crud/query-documents.txt new file mode 100644 index 000000000..47a9f87b5 --- /dev/null +++ b/source/crud/query-documents.txt @@ -0,0 +1,29 @@ +.. _java-read-operations: + +=============== +Query Documents +=============== + +.. meta:: + :description: Learn about the commands for running read operations on MongoDB by using the {+driver-long+}. + +.. toctree:: + :caption: Query Documents + + Specify a Query + Find Documents + Limit Returned Results + Sort Results + Skip Returned Results + Search Geospatially + Search Text + Access Data from a Cursor + +- :doc:`/crud/query-documents/find` +- :doc:`/crud/query-documents/cursor` +- :doc:`/crud/query-documents/sort` +- :doc:`/crud/query-documents/skip` +- :doc:`/crud/query-documents/limit` +- :doc:`/crud/query-documents/project` +- :doc:`/crud/query-documents/geo` +- :doc:`/crud/query-documents/text` diff --git a/source/crud/read-operations/count.txt b/source/crud/query-documents/count.txt similarity index 100% rename from source/crud/read-operations/count.txt rename to source/crud/query-documents/count.txt diff --git a/source/crud/read-operations/cursor.txt b/source/crud/query-documents/cursor.txt similarity index 100% rename from source/crud/read-operations/cursor.txt rename to source/crud/query-documents/cursor.txt diff --git a/source/crud/read-operations/distinct.txt b/source/crud/query-documents/distinct.txt similarity index 100% rename from source/crud/read-operations/distinct.txt rename to source/crud/query-documents/distinct.txt diff --git a/source/crud/read-operations/retrieve.txt b/source/crud/query-documents/find.txt similarity index 96% rename from source/crud/read-operations/retrieve.txt rename to source/crud/query-documents/find.txt index c2de1b09d..a738def52 100644 --- a/source/crud/read-operations/retrieve.txt +++ b/source/crud/query-documents/find.txt @@ -1,11 +1,9 @@ .. _java-fundamentals-retrieve-data: ============== -Retrieve Data +Find Documents ============== - - .. contents:: On this page :local: :backlinks: none @@ -15,10 +13,8 @@ Retrieve Data Overview -------- -In this guide, you can learn how to retrieve data from your MongoDB -database. To retrieve data, use read operations. - -Read operations allow you to do the following: +In this guide, you can learn how to retrieve documents from your MongoDB +database. You can find your documents by using the following: - Retrieve a subset of documents from your collection using a :ref:`find operation ` - Perform transformations on retrieved documents from your collection using an :ref:`aggregate operation ` diff --git a/source/crud/read-operations/geo.txt b/source/crud/query-documents/geo.txt similarity index 100% rename from source/crud/read-operations/geo.txt rename to source/crud/query-documents/geo.txt diff --git a/source/crud/read-operations/limit.txt b/source/crud/query-documents/limit.txt similarity index 100% rename from source/crud/read-operations/limit.txt rename to source/crud/query-documents/limit.txt diff --git a/source/crud/read-operations/project.txt b/source/crud/query-documents/project.txt similarity index 100% rename from source/crud/read-operations/project.txt rename to source/crud/query-documents/project.txt diff --git a/source/crud/read-operations/skip.txt b/source/crud/query-documents/skip.txt similarity index 100% rename from source/crud/read-operations/skip.txt rename to source/crud/query-documents/skip.txt diff --git a/source/crud/read-operations/sort.txt b/source/crud/query-documents/sort.txt similarity index 100% rename from source/crud/read-operations/sort.txt rename to source/crud/query-documents/sort.txt diff --git a/source/crud/query-document.txt b/source/crud/query-documents/specify-query.txt similarity index 100% rename from source/crud/query-document.txt rename to source/crud/query-documents/specify-query.txt diff --git a/source/crud/read-operations/text.txt b/source/crud/query-documents/text.txt similarity index 100% rename from source/crud/read-operations/text.txt rename to source/crud/query-documents/text.txt diff --git a/source/crud/update-documents.txt b/source/crud/update-documents.txt new file mode 100644 index 000000000..cb55d9a4f --- /dev/null +++ b/source/crud/update-documents.txt @@ -0,0 +1,19 @@ +.. _java-write-operations: + +================ +Update Documents +================ + +.. meta:: + :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. + +.. toctree:: + :caption: Update Documents + + Modify + Update Array Elements + Upsert + +- :doc:`/crud/update-documents/modify` +- :doc:`/crud/update-documents/embedded-arrays` +- :doc:`/crud/update-documents/upsert` diff --git a/source/crud/write-operations/embedded-arrays.txt b/source/crud/update-documents/embedded-arrays.txt similarity index 100% rename from source/crud/write-operations/embedded-arrays.txt rename to source/crud/update-documents/embedded-arrays.txt diff --git a/source/crud/write-operations/modify.txt b/source/crud/update-documents/modify.txt similarity index 100% rename from source/crud/write-operations/modify.txt rename to source/crud/update-documents/modify.txt diff --git a/source/crud/write-operations/upsert.txt b/source/crud/update-documents/upsert.txt similarity index 100% rename from source/crud/write-operations/upsert.txt rename to source/crud/update-documents/upsert.txt diff --git a/source/crud/write-operations.txt b/source/crud/write-operations.txt deleted file mode 100644 index aa0b2d86a..000000000 --- a/source/crud/write-operations.txt +++ /dev/null @@ -1,25 +0,0 @@ -.. _java-write-operations: - -================ -Write Operations -================ - -.. meta:: - :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. - -.. toctree:: - :caption: Write Operations - - Insert - Delete - Modify - Update Array Elements - Upsert - Bulk Operations - -- :doc:`/crud/write-operations/insert` -- :doc:`/crud/write-operations/delete` -- :doc:`/crud/write-operations/modify` -- :doc:`/crud/write-operations/embedded-arrays` -- :doc:`/crud/write-operations/upsert` -- :doc:`/crud/write-operations/bulk` diff --git a/source/index.txt b/source/index.txt index fe263dbdc..0df091b51 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,10 +22,12 @@ MongoDB Java Driver Connect Databases & Collections CRUD Operations + Aggregation + Builders Data Formats Indexes Run a Command - Atlas Search + Atlas Search Atlas Vector Search Logging and Monitoring Security diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt index d619e149b..d5ee25489 100644 --- a/source/usage-examples/find.txt +++ b/source/usage-examples/find.txt @@ -13,7 +13,7 @@ the collection. If you do not include a filter, MongoDB returns all the documents in the collection. For more information about querying MongoDB with the Java driver, see our -:doc:`guide on Querying Documents `. +:doc:`guide on Querying Documents `. You can also chain methods to the ``find()`` method such as ``sort()`` which organizes the matched documents in a specified order and @@ -21,9 +21,9 @@ organizes the matched documents in a specified order and returned documents. For more information about the ``sort()`` method, see our -:doc:`guide on Sorting `. +:doc:`guide on Sorting `. For more information about the ``projection()`` method, see our -:doc:`guide on Projections ` +:doc:`guide on Projections ` The ``find()`` method returns an instance of ``FindIterable``, a class that offers several methods to access, organize, and traverse the results. diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index ba7aac213..f6bfd7366 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -14,16 +14,16 @@ include a filter, MongoDB returns all the documents in the collection. The ``first()`` method returns the first matching document. For more information about querying MongoDB with the Java driver, see our -:doc:`guide on Querying Documents `. +:doc:`guide on Querying Documents `. You can also chain other methods to the ``find()`` method such as ``sort()`` which organizes the matched documents in a specified order, and ``projection()`` which configures the fields included in the returned documents. For more information about the ``sort()`` method, see our -:doc:`guide on Sorting `. +:doc:`guide on Sorting `. For more information about the ``projection()`` method, see our -:doc:`guide on Projections ` +:doc:`guide on Projections ` The ``find()`` method returns an instance of ``FindIterable``, a class that offers several methods to access, organize, and traverse the results. From 14f3c062cf59d4d0a144fb3185914849e2d9cb81 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 14 Mar 2025 10:37:46 -0400 Subject: [PATCH 03/31] connection pool --- source/builders.txt | 12 ++++++------ source/index.txt | 2 +- source/{references.txt => reference.txt} | 6 +++--- 3 files changed, 10 insertions(+), 10 deletions(-) rename source/{references.txt => reference.txt} (91%) diff --git a/source/builders.txt b/source/builders.txt index 77153a825..1311f8f74 100644 --- a/source/builders.txt +++ b/source/builders.txt @@ -6,12 +6,12 @@ Builders .. toctree:: - Aggregation - Filters - Indexes - Projection - Sort - Update + Aggregation + Filters + Indexes + Projection + Sort + Update .. contents:: On this page :local: diff --git a/source/index.txt b/source/index.txt index 0df091b51..b78ebf057 100644 --- a/source/index.txt +++ b/source/index.txt @@ -31,7 +31,7 @@ MongoDB Java Driver Atlas Vector Search Logging and Monitoring Security - References + Reference API Documentation Issues & Help diff --git a/source/references.txt b/source/reference.txt similarity index 91% rename from source/references.txt rename to source/reference.txt index c6eda2b81..303f41879 100644 --- a/source/references.txt +++ b/source/reference.txt @@ -1,6 +1,6 @@ -========== -References -========== +========= +Reference +========= .. meta:: :description: Find references material for the {+driver-long+}. From 992ffc48e849be5c2c796bf01075787f5fb90fbd Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 14 Mar 2025 11:05:29 -0400 Subject: [PATCH 04/31] connection pool --- source/connection/specify-connection-options.txt | 5 +++-- .../{ => specify-connection-options}/connection-pools.txt | 0 source/logging-monitoring/monitoring.txt | 5 +---- 3 files changed, 4 insertions(+), 6 deletions(-) rename source/connection/{ => specify-connection-options}/connection-pools.txt (100%) diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index e2ce531b9..61f0be989 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -6,9 +6,10 @@ Specify Connection Options .. toctree:: - - Connection URI Options MongoClient Settings + Connection URI Options + MongoClient Settings Stable API + Connection Pools Network Compression JNDI Datasource AWS Lambda diff --git a/source/connection/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt similarity index 100% rename from source/connection/connection-pools.txt rename to source/connection/specify-connection-options/connection-pools.txt diff --git a/source/logging-monitoring/monitoring.txt b/source/logging-monitoring/monitoring.txt index bd4137f88..be1d6116a 100644 --- a/source/logging-monitoring/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -230,10 +230,7 @@ A connection pool event is an event related to a **connection pool** held by the A connection pool is a set of open TCP connections your driver maintains with a MongoDB instance. Connection pools help reduce the number of network handshakes your application needs to perform with a MongoDB instance and can help your -application run faster. - -.. Add when page is ready: To learn more about connection pools, see the {+driver-short+}'s -.. :ref:`Connection Pools ` guide. +application run faster. To learn more about connection pools, see the {+driver-short+}'s :ref:`Connection Pools ` guide. To monitor connection pool events, write a class that implements the ``ConnectionPoolListener`` interface and register an instance of that class with your From 4430051cf3f60959f35696e7bc5ed7a232719dd1 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 14 Mar 2025 11:22:06 -0400 Subject: [PATCH 05/31] connection pool --- .../connection-options.txt | 54 +++++------ .../connection-pools.txt | 79 ++++++++++++--- .../mongoclientsettings.txt | 96 +++++++++---------- 3 files changed, 141 insertions(+), 88 deletions(-) diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index 2c2d0e862..bc815fa43 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -17,26 +17,26 @@ parameters of the connection URI to specify the behavior of the client. - Type - Description - * - **minPoolSize** - - integer - - Specifies the minimum number of connections that must exist at - any moment in a single connection pool. + .. * - **minPoolSize** + .. - integer + .. - Specifies the minimum number of connections that must exist at + .. any moment in a single connection pool. - | **Default**: ``0`` + .. | **Default**: ``0`` - * - **maxPoolSize** - - integer - - Specifies the maximum number of connections that a connection - pool can have at a given time. + .. * - **maxPoolSize** + .. - integer + .. - Specifies the maximum number of connections that a connection + .. pool can have at a given time. - | **Default**: ``100`` + .. | **Default**: ``100`` - * - **waitQueueTimeoutMS** - - integer - - Specifies the maximum amount of time, in milliseconds that a - thread can wait for a connection to become available. + .. * - **waitQueueTimeoutMS** + .. - integer + .. - Specifies the maximum amount of time, in milliseconds that a + .. thread can wait for a connection to become available. - | **Default**: ``120000`` (120 seconds) + .. | **Default**: ``120000`` (120 seconds) * - **serverSelectionTimeoutMS** - integer @@ -121,14 +121,14 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``0`` - * - **maxIdleTimeMS** - - integer - - Specifies the maximum amount of time, in milliseconds, that the driver - allows a pooled connection to idle before closing the - connection. A value of ``0`` indicates that there is no upper bound - on how long the driver allows a pooled connection to be idle. + .. * - **maxIdleTimeMS** + .. - integer + .. - Specifies the maximum amount of time, in milliseconds, that the driver + .. allows a pooled connection to idle before closing the + .. connection. A value of ``0`` indicates that there is no upper bound + .. on how long the driver allows a pooled connection to be idle. - | **Default**: ``0`` + .. | **Default**: ``0`` * - **maxLifeTimeMS** - integer @@ -285,12 +285,12 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``false`` - * - **maxConnecting** - - integer - - Specifies the maximum number of connections a pool can establish - concurrently. + .. * - **maxConnecting** + .. - integer + .. - Specifies the maximum number of connections a pool can establish + .. concurrently. - | **Default**: ``2`` + .. | **Default**: ``2`` * - **srvServiceName** - string diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index 26e18b75c..743c1c812 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -114,22 +114,75 @@ see the corresponding syntax: *Default*: ``120000`` (120 seconds) - To learn more about connection string options, see the - :ref:`Connection Options ` - guide. - .. tab:: MongoClientSettings - :tabid: MongoClient + :tabid: MongoClient + + Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ method to modify the way the driver manages its connection pool. + + The following table describes the methods you can chain to your settings to modify the driver's behavior: + + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``addConnectionPoolListener()`` + - Adds a listener for connection pool-related events. + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the connection pool settings specified in a + ``ConnectionPoolSettings`` object. + + * - ``maintenanceFrequency()`` + - Sets the frequency for running a maintenance job. + + * - ``maintenanceInitialDelay()`` + - Sets the time to wait before running the first maintenance job. + + * - ``maxConnectionIdleTime()`` + - Sets the maximum time a connection can be idle before it's closed. + + * - ``maxConnectionLifeTime()`` + - Sets the maximum time a pooled connection can be alive before it's + closed. + + * - ``maxSize()`` + - | Sets the maximum number of connections associated with a connection + pool. + | + | **Default**: ``100`` + + * - ``maxWaitTime()`` + - | Sets the maximum time to wait for an available connection. + | + | **Default**: ``2 minutes`` + + * - ``minSize()`` + - | Sets the minimum number of connections associated with a connection + pool. + | + | **Default**: ``0`` + + .. note:: + + This ``maxSize`` and ``minSize`` settings apply to each server in the cluster you connect the driver to. + + For example, assume you connect the driver to a cluster with three``mongos`` servers. This means that there can be at most ``maxSize`` connections and at least ``minSize`` connections to each ``mongos`` server. - .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java - :start-after: begin MongoSettings - :end-before: end MongoSettings - :language: java - :dedent: + .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java + :start-after: begin MongoSettings + :end-before: end MongoSettings + :language: java + :dedent: - For more information on configuring you connection pool by using a - ``MongoClientSettings`` object see the Connection Pool Settings section - of the :ref:`` guide. + For more information on configuring you connection pool by using a + ``MongoClientSettings`` object see the Connection Pool Settings section + of the :ref:`` guide. Additional Information ---------------------- diff --git a/source/connection/specify-connection-options/mongoclientsettings.txt b/source/connection/specify-connection-options/mongoclientsettings.txt index f6be3284c..137187ff2 100644 --- a/source/connection/specify-connection-options/mongoclientsettings.txt +++ b/source/connection/specify-connection-options/mongoclientsettings.txt @@ -73,9 +73,9 @@ connection behavior: - Applies the ``ClusterSettings.Builder`` block and then sets the :ref:`cluster settings `. - * - ``applyToConnectionPoolSettings()`` - - Applies the ``ConnectionPoolSettings.Builder`` block and then sets the - :ref:`connection pool settings `. + .. * - ``applyToConnectionPoolSettings()`` + .. - Applies the ``ConnectionPoolSettings.Builder`` block and then sets the + .. :ref:`connection pool settings `. * - ``applyToLoggerSettings()`` - Applies the ``LoggerSettings.Builder`` block and then sets the @@ -308,68 +308,68 @@ regardless of the type of MongoDB cluster it's a part of: Connection Pool Settings ------------------------ -Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ -method to modify the way the driver manages its connection pool. +.. Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ +.. method to modify the way the driver manages its connection pool. -The following table describes the methods you can chain to your -settings to modify the driver's behavior: +.. The following table describes the methods you can chain to your +.. settings to modify the driver's behavior: -.. list-table:: - :widths: 40 60 - :header-rows: 1 +.. .. list-table:: +.. :widths: 40 60 +.. :header-rows: 1 - * - Method - - Description +.. * - Method +.. - Description - * - ``addConnectionPoolListener()`` - - Adds a listener for connection pool-related events. +.. * - ``addConnectionPoolListener()`` +.. - Adds a listener for connection pool-related events. - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. +.. * - ``applyConnectionString()`` +.. - Uses the settings from a ``ConnectionString`` object. - * - ``applySettings()`` - - Uses the connection pool settings specified in a - ``ConnectionPoolSettings`` object. +.. * - ``applySettings()`` +.. - Uses the connection pool settings specified in a +.. ``ConnectionPoolSettings`` object. - * - ``maintenanceFrequency()`` - - Sets the frequency for running a maintenance job. +.. * - ``maintenanceFrequency()`` +.. - Sets the frequency for running a maintenance job. - * - ``maintenanceInitialDelay()`` - - Sets the time to wait before running the first maintenance job. +.. * - ``maintenanceInitialDelay()`` +.. - Sets the time to wait before running the first maintenance job. - * - ``maxConnectionIdleTime()`` - - Sets the maximum time a connection can be idle before it's closed. +.. * - ``maxConnectionIdleTime()`` +.. - Sets the maximum time a connection can be idle before it's closed. - * - ``maxConnectionLifeTime()`` - - Sets the maximum time a pooled connection can be alive before it's - closed. +.. * - ``maxConnectionLifeTime()`` +.. - Sets the maximum time a pooled connection can be alive before it's +.. closed. - * - ``maxSize()`` - - | Sets the maximum number of connections associated with a connection - pool. - | - | **Default**: ``100`` +.. * - ``maxSize()`` +.. - | Sets the maximum number of connections associated with a connection +.. pool. +.. | +.. | **Default**: ``100`` - * - ``maxWaitTime()`` - - | Sets the maximum time to wait for an available connection. - | - | **Default**: ``2 minutes`` +.. * - ``maxWaitTime()`` +.. - | Sets the maximum time to wait for an available connection. +.. | +.. | **Default**: ``2 minutes`` - * - ``minSize()`` - - | Sets the minimum number of connections associated with a connection - pool. - | - | **Default**: ``0`` +.. * - ``minSize()`` +.. - | Sets the minimum number of connections associated with a connection +.. pool. +.. | +.. | **Default**: ``0`` -.. note:: +.. .. note:: - This ``maxSize`` and ``minSize`` settings apply to each server - in the cluster you connect the driver to. +.. This ``maxSize`` and ``minSize`` settings apply to each server +.. in the cluster you connect the driver to. - For example, assume you connect the driver to a cluster with three - ``mongos`` servers. This means that there can be at most ``maxSize`` - connections and at least ``minSize`` connections to each ``mongos`` server. +.. For example, assume you connect the driver to a cluster with three +.. ``mongos`` servers. This means that there can be at most ``maxSize`` +.. connections and at least ``minSize`` connections to each ``mongos`` server. Example ~~~~~~~ From 64bf34afc4ba7c05e0d404d55f1887e5a3cf8fd5 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 01:25:57 -0400 Subject: [PATCH 06/31] tabs --- .../connection/specify-connection-options.txt | 6 +- .../cluster-settings.txt | 179 +++++++++ .../connection-pools.txt | 21 +- .../mongoclientsettings.txt | 371 +----------------- .../server-settings.txt | 76 ++++ .../socket-settings.txt | 87 ++++ .../code-snippets/MCSettings.java | 3 +- source/security/tls.txt | 83 +++- 8 files changed, 437 insertions(+), 389 deletions(-) create mode 100644 source/connection/specify-connection-options/cluster-settings.txt create mode 100644 source/connection/specify-connection-options/server-settings.txt create mode 100644 source/connection/specify-connection-options/socket-settings.txt diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 61f0be989..daaefeaf0 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -10,6 +10,7 @@ Specify Connection Options MongoClient Settings Stable API Connection Pools + Cluster Settings Network Compression JNDI Datasource AWS Lambda @@ -27,7 +28,4 @@ Overview This section describes the MongoDB connection and authentication options available in the {+driver-short+}. You can specify connection options in the -following ways: - -- :ref:`Specifying query parameters in the connection URI` you pass to the ``MongoClient`` constructor -- :ref:`Defining a MongoClientSettings object ` and passing it to the ``MongoClient`` constructor \ No newline at end of file +following ways: \ No newline at end of file diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt new file mode 100644 index 000000000..315ea6b51 --- /dev/null +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -0,0 +1,179 @@ +.. _mcs-cluster-settings: + +================ +Cluster Settings +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: timeout, replica set + +Overview +-------- + +In this guide, you can learn about how the {+driver-short+} manages clusters. + +You can specify settings for your clusters using either a :ref:`connection +string ` or by passing a ``MongoClientSettings`` object to the +:ref:`MongoClients ` contructor. Select the :guilabel:`Connection +String` or :guilabel:`MongoClientSettings` tab to see the options available: + + +.. tabs:: + + .. tab:: Connection String + :tabid: uri + + .. list-table:: + :header-rows: 1 + :widths: 20 10 20 + + * - Option Name + - Type + - Description + + * - **serverSelectionTimeoutMS** + - integer + - Specifies the maximum amount of time, in milliseconds, the driver + will wait for server selection to succeed before throwing an + exception. + + | **Default**: ``30000`` (30 seconds) + + * - **localThresholdMS** + - integer + - When communicating with multiple instances of MongoDB in a replica + set, the driver will only send requests to a server whose + response time is less than or equal to the server with the fastest + response time plus the local threshold, in milliseconds. + + | **Default**: ``15`` + + * - **heartbeatFrequencyMS** + - integer + - Specifies the frequency, in milliseconds that the driver will + wait between attempts to determine the current state of each + server in the cluster. + + | **Default**: ``10000`` (10 seconds) + + * - **replicaSet** + - string + - Specifies that the :ref:`connection string ` + provided includes multiple hosts. When specified, the driver + attempts to find all members of that set. + + | **Default**: ``null`` + + * - **directConnection** + - boolean + - Specifies that the driver must connect to the host directly. This + maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your ``MongoClientSettings``. + + | **Default**: ``false`` + + * - **srvServiceName** + - string + - Specifies the service name of the `SRV resource records `__ the driver retrieves to construct your :manual:`seed list `. You must use the :manual:`DNS Seed List Connection Format ` in your :ref:`connection URI ` to use this option. + + | **Default**: ``mongodb`` + + .. tab:: MongoClientSettings + :tabid: MongoClient + + Chain the `applyToClusterSettings() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToClusterSettings(com.mongodb.Block)>`__ + method to modify the driver's behavior when interacting with your MongoDB + cluster. + + The following table describes the methods you can chain to your + settings to modify the driver's behavior: + + .. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 40 60 + + * - Method + - Description + + * - ``addClusterListener()`` + - Adds a listener for cluster-related events. + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the cluster settings specified in a ``ClusterSettings`` object. + + * - ``hosts()`` + - Sets all the specified locations of a Mongo deployment. + + * - ``localThreshold()`` + - | Sets the amount of time that a server’s round trip can take and still be eligible for server selection. + | + | **Default**: ``15 milliseconds`` + + * - ``mode()`` + - Sets how to connect to a MongoDB deployment. + + * - ``requiredClusterType()`` + - Sets the type of cluster required for the cluster. + + * - ``requiredReplicaSetName()`` + - Sets the replica set name required for the cluster. + + * - ``serverSelectionTimeout()`` + - | Sets the maximum time to select a primary node before throwing a timeout exception. + | + | **Default**: ``30 seconds`` + + * - ``serverSelector()`` + - Adds a server selector to apply before server selection. + + * - ``srvHost()`` + - | Sets the host name to use to look up an SRV DNS record to find the MongoDB hosts. + | + | If you want to enable the processing of TXT records associated with the host, specify the SRV host in the connection string using the ``applyConnectionString()`` method. + | + | For example: + + .. code-block:: java + :emphasize-lines: 3 + + MongoClient mongoClient = + MongoClients.create(MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) + + * - ``srvMaxHosts()`` + - | Sets the maximum number of hosts the driver can connect to when using the DNS seedlist (SRV) connection protocol, identified by the ``mongodb+srv`` connection string prefix. + | + | Throws an exception if you are not using the SRV connection protocol. + + Example + ~~~~~~~ + + This example specifies for the driver to connect directly to a server, + regardless of the type of MongoDB cluster it's a part of: + + .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin ClusterSettings + :end-before: end ClusterSettings + :language: java + :emphasize-lines: 3-4 + :dedent: + + .. tip:: + + This is analogous to the ``directConnection`` parameter you can specify + in your connection URI. See :ref:`` for more + information. diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index 743c1c812..a74d0e8e9 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -1,4 +1,5 @@ .. _java-connection-pools: +.. _mcs-connectionpool-settings: ================ Connection Pools @@ -117,7 +118,13 @@ see the corresponding syntax: .. tab:: MongoClientSettings :tabid: MongoClient - Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ method to modify the way the driver manages its connection pool. + Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ method to modify the way the driver manages its connection pool. The following example chains the ``applyToConnectionPoolSettings()`` method to set the thread to wait at most ``10 SECONDS`` for an available connection, and the ``maxSize`` of the connection pool to 200: + + .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java + :start-after: begin MongoSettings + :end-before: end MongoSettings + :language: java + :dedent: The following table describes the methods you can chain to your settings to modify the driver's behavior: @@ -172,17 +179,7 @@ see the corresponding syntax: This ``maxSize`` and ``minSize`` settings apply to each server in the cluster you connect the driver to. - For example, assume you connect the driver to a cluster with three``mongos`` servers. This means that there can be at most ``maxSize`` connections and at least ``minSize`` connections to each ``mongos`` server. - - .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java - :start-after: begin MongoSettings - :end-before: end MongoSettings - :language: java - :dedent: - - For more information on configuring you connection pool by using a - ``MongoClientSettings`` object see the Connection Pool Settings section - of the :ref:`` guide. + For example, assume you connect the driver to a cluster with three ``mongos`` servers. This means that there can be at most ``maxSize`` connections and at least ``minSize`` connections to each ``mongos`` server. Additional Information ---------------------- diff --git a/source/connection/specify-connection-options/mongoclientsettings.txt b/source/connection/specify-connection-options/mongoclientsettings.txt index 137187ff2..273923edb 100644 --- a/source/connection/specify-connection-options/mongoclientsettings.txt +++ b/source/connection/specify-connection-options/mongoclientsettings.txt @@ -27,11 +27,7 @@ the behavior of your ``MongoClient``. The following sections describe commonly used settings: - :ref:`MongoClient Settings ` -- :ref:`Cluster Settings ` -- :ref:`Socket Settings ` -- :ref:`Connection Pool Settings ` - :ref:`Server Settings ` -- :ref:`TLS/SSL Settings ` .. _mcs-settings: @@ -85,13 +81,13 @@ connection behavior: - Applies the ``ServerSettings.Builder`` block and then sets the :ref:`server settings `. - * - ``applyToSocketSettings()`` - - Applies the ``SocketSettings.Builder`` block and then sets the - :ref:`socket settings `. + .. * - ``applyToSocketSettings()`` + .. - Applies the ``SocketSettings.Builder`` block and then sets the + .. :ref:`socket settings `. - * - ``applyToSslSettings()`` - - Applies the ``SslSettings.Builder`` block and then sets the - :ref:`TLS/SSL settings `. + .. * - ``applyToSslSettings()`` + .. - Applies the ``SslSettings.Builder`` block and then sets the + .. :ref:`TLS/SSL settings `. * - ``autoEncryptionSettings()`` - | Sets the :ref:`auto-encryption settings `. @@ -205,187 +201,6 @@ This example demonstrates specifying a ``ConnectionString``: To learn more about logging with the {+driver-long+}, see the :ref:`java-fundamentals-logging` guide. -.. _mcs-cluster-settings: - -Cluster Settings ----------------- - -Chain the `applyToClusterSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToClusterSettings(com.mongodb.Block)>`__ -method to modify the driver's behavior when interacting with your -MongoDB cluster. - -The following table describes the methods you can chain to your -settings to modify the driver's behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``addClusterListener()`` - - Adds a listener for cluster-related events. - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the cluster settings specified in a ``ClusterSettings`` object. - - * - ``hosts()`` - - Sets all the specified locations of a Mongo deployment. - - * - ``localThreshold()`` - - | Sets the amount of time that a server’s round trip can take and still - be eligible for server selection. - | - | **Default**: ``15 milliseconds`` - - * - ``mode()`` - - Sets how to connect to a MongoDB deployment. - - * - ``requiredClusterType()`` - - Sets the type of cluster required for the cluster. - - * - ``requiredReplicaSetName()`` - - Sets the replica set name required for the cluster. - - * - ``serverSelectionTimeout()`` - - | Sets the maximum time to select a primary node before throwing a - timeout exception. - | - | **Default**: ``30 seconds`` - - * - ``serverSelector()`` - - Adds a server selector to apply before server selection. - - * - ``srvHost()`` - - | Sets the host name to use to look up an SRV DNS record to find the - MongoDB hosts. - | - | If you want to enable the processing of TXT records associated with the host, - specify the SRV host in the connection string - using the ``applyConnectionString()`` method. - | - | For example: - - .. code-block:: java - :emphasize-lines: 3 - - MongoClient mongoClient = - MongoClients.create(MongoClientSettings.builder() - .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) - - * - ``srvMaxHosts()`` - - | Sets the maximum number of hosts the driver can connect to when using - the DNS seedlist (SRV) connection protocol, identified by the - ``mongodb+srv`` connection string prefix. - | - | Throws an exception if you are not using the SRV connection protocol. - -Example -~~~~~~~ - -This example specifies for the driver to connect directly to a server, -regardless of the type of MongoDB cluster it's a part of: - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin ClusterSettings - :end-before: end ClusterSettings - :language: java - :emphasize-lines: 3-4 - :dedent: - -.. tip:: - - This is analogous to the ``directConnection`` parameter you can specify - in your connection URI. See :ref:`` for more - information. - -.. _mcs-connectionpool-settings: - -Connection Pool Settings ------------------------- - -.. Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ -.. method to modify the way the driver manages its connection pool. - -.. The following table describes the methods you can chain to your -.. settings to modify the driver's behavior: - -.. .. list-table:: -.. :widths: 40 60 -.. :header-rows: 1 - -.. * - Method -.. - Description - -.. * - ``addConnectionPoolListener()`` -.. - Adds a listener for connection pool-related events. - -.. * - ``applyConnectionString()`` -.. - Uses the settings from a ``ConnectionString`` object. - -.. * - ``applySettings()`` -.. - Uses the connection pool settings specified in a -.. ``ConnectionPoolSettings`` object. - -.. * - ``maintenanceFrequency()`` -.. - Sets the frequency for running a maintenance job. - -.. * - ``maintenanceInitialDelay()`` -.. - Sets the time to wait before running the first maintenance job. - -.. * - ``maxConnectionIdleTime()`` -.. - Sets the maximum time a connection can be idle before it's closed. - -.. * - ``maxConnectionLifeTime()`` -.. - Sets the maximum time a pooled connection can be alive before it's -.. closed. - -.. * - ``maxSize()`` -.. - | Sets the maximum number of connections associated with a connection -.. pool. -.. | -.. | **Default**: ``100`` - -.. * - ``maxWaitTime()`` -.. - | Sets the maximum time to wait for an available connection. -.. | -.. | **Default**: ``2 minutes`` - -.. * - ``minSize()`` -.. - | Sets the minimum number of connections associated with a connection -.. pool. -.. | -.. | **Default**: ``0`` - - -.. .. note:: - -.. This ``maxSize`` and ``minSize`` settings apply to each server -.. in the cluster you connect the driver to. - -.. For example, assume you connect the driver to a cluster with three -.. ``mongos`` servers. This means that there can be at most ``maxSize`` -.. connections and at least ``minSize`` connections to each ``mongos`` server. - -Example -~~~~~~~ - -This example specifies the following driver behavior in a pool of -``Connection`` types: - -- The thread to wait at most ``10 SECONDS`` for an available connection -- To have at most ``200`` connections associated with the pool - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin ConnectionPoolSettings - :end-before: end ConnectionPoolSettings - :language: java - :emphasize-lines: 3-5 - :dedent: .. _mcs-logger-settings: @@ -424,178 +239,4 @@ message is set to ``5000`` characters. :emphasize-lines: 3-4 :dedent: -.. _mcs-server-settings: - -Server Settings ---------------- - -Chain the `applyToServerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToServerSettings(com.mongodb.Block)>`__ -method to modify the driver's behavior when monitoring each MongoDB -deployment. - -The following table describes the methods you can chain to your -settings to modify the driver's behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``addServerListener()`` - - Adds a listener for server-related events. - * - ``addServerMonitorListener()`` - - Adds a listener for server monitor-related events. - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the server settings specified in a ``ServerSettings`` object. - - * - ``heartbeatFrequency()`` - - | Sets the interval for a cluster monitor to attempt reaching a server. - | - | **Default**: ``10 seconds`` - - * - ``minHeartbeatFrequency()`` - - | Sets the minimum interval for server monitoring checks. - | - | **Default**: ``500 milliseconds`` - -Example -~~~~~~~ - -This example specifies the following driver behavior in a MongoDB deployment: - -- The minimum interval for server monitoring checks to be at least - ``700 MILLISECONDS`` -- The cluster monitor to attempt reaching a server every ``15 SECONDS`` - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin ServerSettings - :end-before: end ServerSettings - :language: java - :emphasize-lines: 3-5 - :dedent: - -.. _mcs-socket-settings: - -Socket Settings ---------------- - -Chain the `applyToSocketSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSocketSettings(com.mongodb.Block)>`__ -method to modify the driver's behavior when connecting and communicating -with your MongoDB deployment. - -The following table describes the methods you can chain to your settings -to modify the driver's behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the socket settings specified in a ``SocketSettings`` object. - - * - ``connectTimeout()`` - - | Sets the maximum time to connect to an available socket before throwing - a timeout exception. - | - | **Default**: ``10 seconds`` - - * - ``readTimeout()`` - - | Sets the maximum time to read from an available socket before throwing a - timeout exception. - | - | **Default**: ``0``, which indicates no timeout - - * - ``receiveBufferSize()`` - - | Sets the socket's buffer size when receiving. - | - | **Default**: The operating system default - - * - ``sendBufferSize()`` - - | Sets the socket's buffer size when sending. - | - | **Default**: The operating system default - -.. note:: Connect to MongoDB by using a SOCKS5 Proxy - - You can chain the ``applyToProxySettings()`` method to your socket settings to - connect to MongoDB by using a SOCKS5 proxy. To learn how to use a SOCKS5 proxy - and set proxy settings, see the :ref:`Connect to MongoDB by Using a SOCKS5 Proxy - ` guide. - -.. _java-socketsettings-example: - -Example -~~~~~~~ - -This example specifies the following driver behavior in a MongoDB socket: - -- To connect to an available socket within ``10 SECONDS`` -- To read from an available socket within ``15 SECONDS`` - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin SocketSettings - :end-before: end SocketSettings - :language: java - :emphasize-lines: 3-5 - :dedent: - -.. _mcs-ssl-settings: - -TLS/SSL Settings ----------------- - -Chain the `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ -method to modify the driver's behavior when using TLS/SSL to secure a -connection between your application and MongoDB. - -The following table describes the methods you can chain to your -settings to modify the driver's behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the TLS/SSL settings specified in a ``SslSettings`` object. - - * - ``context()`` - - Sets the ``SSLContext`` for use when you enable TLS/SSL. - - * - ``enabled()`` - - Whether to enable TLS/SSL. (You must enable this for Atlas clusters.) - - * - ``invalidHostNameAllowed()`` - - Whether to allow a mismatch between the server’s hostname and the - hostname specified by the TLS certificate. - -Example -~~~~~~~ - -This example specifies for the driver to enable TLS/SSL when connecting -to MongoDB: - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin SslSettings - :end-before: end SslSettings - :language: java - :emphasize-lines: 3-4 - :dedent: \ No newline at end of file diff --git a/source/connection/specify-connection-options/server-settings.txt b/source/connection/specify-connection-options/server-settings.txt new file mode 100644 index 000000000..d2ac7b02e --- /dev/null +++ b/source/connection/specify-connection-options/server-settings.txt @@ -0,0 +1,76 @@ +.. _mcs-server-settings: + +=============== +Server Settings +=============== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +Overview +-------- + +In this guide, you can learn about how the {+driver-short+} manages server +settings. + +Configuring Server Settings +--------------------------- + +Chain the `applyToServerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToServerSettings(com.mongodb.Block)>`__ +method to modify the driver's behavior when monitoring each MongoDB +deployment. + +The following table describes the methods you can chain to your +settings to modify the driver's behavior: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``addServerListener()`` + - Adds a listener for server-related events. + + * - ``addServerMonitorListener()`` + - Adds a listener for server monitor-related events. + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the server settings specified in a ``ServerSettings`` object. + + * - ``heartbeatFrequency()`` + - | Sets the interval for a cluster monitor to attempt reaching a server. + | + | **Default**: ``10 seconds`` + + * - ``minHeartbeatFrequency()`` + - | Sets the minimum interval for server monitoring checks. + | + | **Default**: ``500 milliseconds`` + +Example +~~~~~~~ + +This example specifies the following driver behavior in a MongoDB deployment: + +- The minimum interval for server monitoring checks to be at least + ``700 MILLISECONDS`` +- The cluster monitor to attempt reaching a server every ``15 SECONDS`` + +.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin ServerSettings + :end-before: end ServerSettings + :language: java + :emphasize-lines: 3-5 + :dedent: diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt new file mode 100644 index 000000000..a19fd2c43 --- /dev/null +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -0,0 +1,87 @@ +.. _mcs-socket-settings: + +================ +Socket Settings +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +Overview +-------- + +In this guide, you can learn about how the {+driver-short+} manages socket +settings. + +Chain the `applyToSocketSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSocketSettings(com.mongodb.Block)>`__ +method to modify the driver's behavior when connecting and communicating +with your MongoDB deployment. + +The following table describes the methods you can chain to your settings +to modify the driver's behavior: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the socket settings specified in a ``SocketSettings`` object. + + * - ``connectTimeout()`` + - | Sets the maximum time to connect to an available socket before throwing + a timeout exception. + | + | **Default**: ``10 seconds`` + + * - ``readTimeout()`` + - | Sets the maximum time to read from an available socket before throwing a + timeout exception. + | + | **Default**: ``0``, which indicates no timeout + + * - ``receiveBufferSize()`` + - | Sets the socket's buffer size when receiving. + | + | **Default**: The operating system default + + * - ``sendBufferSize()`` + - | Sets the socket's buffer size when sending. + | + | **Default**: The operating system default + +.. note:: Connect to MongoDB by using a SOCKS5 Proxy + + You can chain the ``applyToProxySettings()`` method to your socket settings to + connect to MongoDB by using a SOCKS5 proxy. To learn how to use a SOCKS5 proxy + and set proxy settings, see the :ref:`Connect to MongoDB by Using a SOCKS5 Proxy + ` guide. + +.. _java-socketsettings-example: + +Example +------- + +This example specifies the following driver behavior in a MongoDB socket: + +- To connect to an available socket within ``10 SECONDS`` +- To read from an available socket within ``15 SECONDS`` + +.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin SocketSettings + :end-before: end SocketSettings + :language: java + :emphasize-lines: 3-5 + :dedent: diff --git a/source/includes/fundamentals/code-snippets/MCSettings.java b/source/includes/fundamentals/code-snippets/MCSettings.java index c38717be8..ba06e969c 100644 --- a/source/includes/fundamentals/code-snippets/MCSettings.java +++ b/source/includes/fundamentals/code-snippets/MCSettings.java @@ -89,7 +89,8 @@ private static void createSocketSettings() { try { //begin SocketSettings MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder().applyConnectionString(new ConnectionString("")) + MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) .applyToSocketSettings(builder -> builder.connectTimeout(10, SECONDS) .readTimeout(15, SECONDS)) diff --git a/source/security/tls.txt b/source/security/tls.txt index a84d4ddec..992e5c0fc 100644 --- a/source/security/tls.txt +++ b/source/security/tls.txt @@ -36,6 +36,7 @@ or `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCl for more information. .. _tls-enable: +.. _mcs-ssl-settings: Enable TLS/SSL -------------- @@ -68,23 +69,91 @@ using a method in the ``MongoClientSettings.Builder`` class. .. code-block:: java MongoClient mongoClient = MongoClients.create("mongodb+srv://:@?tls=true"); + + The following table describes the parameter you can include in your + connection string to modify the driver's TSL behavior: + + .. list-table:: + :header-rows: 1 + :widths: 20 10 20 + + * - Option Name + - Type + - Description + + * - **ssl** + - boolean + - Specifies that all communication with MongoDB instances must + use TLS/SSL. Superseded by the **tls** option. + + | **Default**: ``false`` + + * - **tls** + - boolean + - Specifies that all communication with MongoDB instances must + use TLS. Supersedes the **ssl** option. + + | **Default**: ``false`` + + * - **tlsInsecure** + - boolean + - Specifies that the driver must allow invalid hostnames for TLS + connections. Has the same effect as setting + **tlsAllowInvalidHostnames** to ``true``. To configure TLS security + constraints in other ways, use a + :ref:`custom SSLContext `. + + | **Default**: ``false`` + + * - **tlsAllowInvalidHostnames** + - boolean + - Specifies that the driver must allow invalid hostnames in the + certificate for TLS connections. Supersedes + **sslInvalidHostNameAllowed**. + + | **Default**: ``false`` .. tab:: MongoClientSettings :tabid: mongoclientsettings To configure your ``MongoClient``'s TLS/SSL connection options using the - ``MongoClientSettings.Builder`` class, call the + ``MongoClientSettings.Builder`` class, chain the `applyToSslSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`__ method. Set the ``enabled`` property to ``true`` in the ``SslSettings.Builder`` block to enable TLS/SSL: - .. code-block:: java + .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin SslSettings + :end-before: end SslSettings + :language: java + :emphasize-lines: 3-4 + :dedent: + + The following table describes the methods you can chain to your + settings to modify the driver's TSL behavior: + + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the TLS/SSL settings specified in a ``SslSettings`` object. + + * - ``context()`` + - Sets the ``SSLContext`` for use when you enable TLS/SSL. + + * - ``enabled()`` + - Whether to enable TLS/SSL. (You must enable this for Atlas clusters.) - MongoClientSettings settings = MongoClientSettings.builder() - .applyToSslSettings(builder -> - builder.enabled(true)) - .build(); - MongoClient client = MongoClients.create(settings); + * - ``invalidHostNameAllowed()`` + - Whether to allow a mismatch between the server’s hostname and the + hostname specified by the TLS certificate. .. _tls_configure-certificates: From a8a39a5e7f79345be3b9d2069e869474a6537c87 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 01:26:39 -0400 Subject: [PATCH 07/31] socket settings --- .../socket-settings.txt | 34 +++++++++++++++---- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index a19fd2c43..47128729a 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -20,12 +20,34 @@ Overview In this guide, you can learn about how the {+driver-short+} manages socket settings. -Chain the `applyToSocketSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSocketSettings(com.mongodb.Block)>`__ -method to modify the driver's behavior when connecting and communicating -with your MongoDB deployment. - -The following table describes the methods you can chain to your settings -to modify the driver's behavior: +You can specify settings for your sockets using either a :ref:`connection +string ` or by passing a ``MongoClientSettings`` object to the +:ref:`MongoClients ` contructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: + +.. tabs:: + + .. tab:: Connection String + :tabid: uri + + .. list-table:: + :header-rows: 1 + :widths: 20 10 20 + + * - Option Name + - Type + - Description + + * - + + .. tab:: Connection String + :tabid: uri + + Chain the `applyToSocketSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSocketSettings(com.mongodb.Block)>`__ + method to modify the driver's behavior when connecting and communicating + with your MongoDB deployment. + + The following table describes the methods you can chain to your settings + to modify the driver's behavior: .. list-table:: :widths: 40 60 From 562da0d8bb2b9e125c47feea1760e9da116e1783 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 01:34:50 -0400 Subject: [PATCH 08/31] options --- snooty.toml | 1 - source/connection/mongoclient.txt | 4 +- .../connection-options.txt | 132 ------------------ .../connection-pools.txt | 1 + .../socket-settings.txt | 6 +- source/get-started.txt | 8 -- 6 files changed, 8 insertions(+), 144 deletions(-) diff --git a/snooty.toml b/snooty.toml index ed695a8f3..f4ed42363 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,7 +7,6 @@ intersphinx = [ ] toc_landing_pages = [ - "/get-started", "/connection", "/connection/specify-connection-options", "/crud", diff --git a/source/connection/mongoclient.txt b/source/connection/mongoclient.txt index e280a1f9f..c31023eac 100644 --- a/source/connection/mongoclient.txt +++ b/source/connection/mongoclient.txt @@ -45,8 +45,8 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``. ``MongoClient`` instances. To learn about the different settings you can use to control the -behavior of your ``MongoClient``, see the guide on -:ref:`MongoClient Settings `. +behavior of your ``MongoClient``, see the +:ref:`Specify MongoClient Settings ` guide. .. tip:: diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index bc815fa43..ac14ca67b 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -17,92 +17,6 @@ parameters of the connection URI to specify the behavior of the client. - Type - Description - .. * - **minPoolSize** - .. - integer - .. - Specifies the minimum number of connections that must exist at - .. any moment in a single connection pool. - - .. | **Default**: ``0`` - - .. * - **maxPoolSize** - .. - integer - .. - Specifies the maximum number of connections that a connection - .. pool can have at a given time. - - .. | **Default**: ``100`` - - .. * - **waitQueueTimeoutMS** - .. - integer - .. - Specifies the maximum amount of time, in milliseconds that a - .. thread can wait for a connection to become available. - - .. | **Default**: ``120000`` (120 seconds) - - * - **serverSelectionTimeoutMS** - - integer - - Specifies the maximum amount of time, in milliseconds, the driver - will wait for server selection to succeed before throwing an - exception. - - | **Default**: ``30000`` (30 seconds) - - * - **localThresholdMS** - - integer - - When communicating with multiple instances of MongoDB in a replica - set, the driver will only send requests to a server whose - response time is less than or equal to the server with the fastest - response time plus the local threshold, in milliseconds. - - | **Default**: ``15`` - - * - **heartbeatFrequencyMS** - - integer - - Specifies the frequency, in milliseconds that the driver will - wait between attempts to determine the current state of each - server in the cluster. - - | **Default**: ``10000`` (10 seconds) - - * - **replicaSet** - - string - - Specifies that the :ref:`connection string ` - provided includes multiple hosts. When specified, the driver - attempts to find all members of that set. - - | **Default**: ``null`` - - * - **ssl** - - boolean - - Specifies that all communication with MongoDB instances must - use TLS/SSL. Superseded by the **tls** option. - - | **Default**: ``false`` - - * - **tls** - - boolean - - Specifies that all communication with MongoDB instances must - use TLS. Supersedes the **ssl** option. - - | **Default**: ``false`` - - * - **tlsInsecure** - - boolean - - Specifies that the driver must allow invalid hostnames for TLS - connections. Has the same effect as setting - **tlsAllowInvalidHostnames** to ``true``. To configure TLS security - constraints in other ways, use a - :ref:`custom SSLContext `. - - | **Default**: ``false`` - - * - **tlsAllowInvalidHostnames** - - boolean - - Specifies that the driver must allow invalid hostnames in the - certificate for TLS connections. Supersedes - **sslInvalidHostNameAllowed**. - - | **Default**: ``false`` - * - **connectTimeoutMS** - integer - Specifies the maximum amount of time, in milliseconds, the Java @@ -112,24 +26,6 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``10000`` (10 seconds) - * - **socketTimeoutMS** - - integer - - Specifies the maximum amount of time, in milliseconds, the Java - driver will wait to send or receive a request before timing out. - A value of ``0`` instructs the driver to never time out while waiting - to send or receive a request. - - | **Default**: ``0`` - - .. * - **maxIdleTimeMS** - .. - integer - .. - Specifies the maximum amount of time, in milliseconds, that the driver - .. allows a pooled connection to idle before closing the - .. connection. A value of ``0`` indicates that there is no upper bound - .. on how long the driver allows a pooled connection to be idle. - - .. | **Default**: ``0`` - * - **maxLifeTimeMS** - integer - Specifies the maximum amount of time, in milliseconds, the Java @@ -253,7 +149,6 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``true`` - * - **retryReads** - boolean - Specifies that the driver must retry supported read operations @@ -279,33 +174,6 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``unspecified`` - * - **directConnection** - - boolean - - Specifies that the driver must connect to the host directly. - - | **Default**: ``false`` - - .. * - **maxConnecting** - .. - integer - .. - Specifies the maximum number of connections a pool can establish - .. concurrently. - - .. | **Default**: ``2`` - - * - **srvServiceName** - - string - - Specifies the service name of the - `SRV resource records `__ - the driver retrieves to construct your - :manual:`seed list `. - You must use the - :manual:`DNS Seed List Connection Format ` - in your - :ref:`connection URI ` - to use this option. - - | **Default**: ``mongodb`` - * - **proxyHost** - string - Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index a74d0e8e9..905ac6587 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -1,4 +1,5 @@ .. _java-connection-pools: +.. _connection-pools: .. _mcs-connectionpool-settings: ================ diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index 47128729a..50cf728a3 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -37,7 +37,11 @@ string ` or by passing a ``MongoClientSettings`` object to the - Type - Description - * - + * - **socketTimeoutMS** + - integer + - | Specifies the maximum amount of time, in milliseconds, the Java driver will wait to send or receive a request before timing out. A value of ``0`` instructs the driver to never time out while waiting to send or receive a request. + | + | **Default**: ``0`` .. tab:: Connection String :tabid: uri diff --git a/source/get-started.txt b/source/get-started.txt index 49621c323..0a2a07058 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -12,14 +12,6 @@ Get Started with the Java Driver :description: Learn how to create an app to connect to MongoDB deployment by using the {+driver-short+}. :keywords: quick start, tutorial, basics -.. toctree:: - - Download & Install - Create a Deployment - Create a Connection String - Connect to MongoDB - Next Steps - Overview -------- From 4e87ba5e21fd45f5094ff2f59ba4903786ee9a0f Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 01:35:49 -0400 Subject: [PATCH 09/31] build error --- .../mongoclientsettings.txt | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/source/connection/specify-connection-options/mongoclientsettings.txt b/source/connection/specify-connection-options/mongoclientsettings.txt index 273923edb..1c5597583 100644 --- a/source/connection/specify-connection-options/mongoclientsettings.txt +++ b/source/connection/specify-connection-options/mongoclientsettings.txt @@ -69,10 +69,6 @@ connection behavior: - Applies the ``ClusterSettings.Builder`` block and then sets the :ref:`cluster settings `. - .. * - ``applyToConnectionPoolSettings()`` - .. - Applies the ``ConnectionPoolSettings.Builder`` block and then sets the - .. :ref:`connection pool settings `. - * - ``applyToLoggerSettings()`` - Applies the ``LoggerSettings.Builder`` block and then sets the :ref:`logger settings `. @@ -81,14 +77,6 @@ connection behavior: - Applies the ``ServerSettings.Builder`` block and then sets the :ref:`server settings `. - .. * - ``applyToSocketSettings()`` - .. - Applies the ``SocketSettings.Builder`` block and then sets the - .. :ref:`socket settings `. - - .. * - ``applyToSslSettings()`` - .. - Applies the ``SslSettings.Builder`` block and then sets the - .. :ref:`TLS/SSL settings `. - * - ``autoEncryptionSettings()`` - | Sets the :ref:`auto-encryption settings `. | From f270017d8ae8ac65665c0478503ee6459b01af09 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 02:01:10 -0400 Subject: [PATCH 10/31] build error --- source/crud/query-documents.txt | 1 + source/security/tls.txt | 13 ++++++------- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/crud/query-documents.txt b/source/crud/query-documents.txt index 47a9f87b5..1093774c9 100644 --- a/source/crud/query-documents.txt +++ b/source/crud/query-documents.txt @@ -12,6 +12,7 @@ Query Documents Specify a Query Find Documents + Specify Which Fields to Return Limit Returned Results Sort Results Skip Returned Results diff --git a/source/security/tls.txt b/source/security/tls.txt index 992e5c0fc..27cb2d988 100644 --- a/source/security/tls.txt +++ b/source/security/tls.txt @@ -137,23 +137,22 @@ using a method in the ``MongoClientSettings.Builder`` class. :header-rows: 1 * - Method - - Description + - Description * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. + - Uses the settings from a ``ConnectionString`` object. * - ``applySettings()`` - - Uses the TLS/SSL settings specified in a ``SslSettings`` object. + - Uses the TLS/SSL settings specified in a ``SslSettings`` object. * - ``context()`` - - Sets the ``SSLContext`` for use when you enable TLS/SSL. + - Sets the ``SSLContext`` for use when you enable TLS/SSL. * - ``enabled()`` - - Whether to enable TLS/SSL. (You must enable this for Atlas clusters.) + - Whether to enable TLS/SSL. (You must enable this for Atlas clusters.) * - ``invalidHostNameAllowed()`` - - Whether to allow a mismatch between the server’s hostname and the - hostname specified by the TLS certificate. + - Whether to allow a mismatch between the server's hostname and the hostname specified by the TLS certificate. .. _tls_configure-certificates: From 6be0ca01ee2cace3c23cce0da05697cb261e9c81 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 02:55:38 -0400 Subject: [PATCH 11/31] build error --- source/connection/connection-troubleshooting.txt | 5 +++++ source/crud/transactions.txt | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/source/connection/connection-troubleshooting.txt b/source/connection/connection-troubleshooting.txt index d678ae409..5aee84cb4 100644 --- a/source/connection/connection-troubleshooting.txt +++ b/source/connection/connection-troubleshooting.txt @@ -158,6 +158,11 @@ Connection Troubleshooting .. _java-troubleshooting-connection-string-auth: + .. replacement:: connection-pools-learn-more + + To learn more about how connection pooling works in the driver, see the + :ref:`Connection Pools ` page. + .. _java-connection-certificate: Security Certificate Errors diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index f9c533412..42a26e888 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -148,7 +148,9 @@ If you require more control over your transactions, you can use the ``startTrans method. You can use this method with the ``commitTransaction()`` and ``abortTransaction()`` methods described in the preceding section to manually manage the transaction lifecycle. -.. sharedinclude:: dbx/transactions-parallelism.rst +.. note:: Parallel Operations Not Supported + + The {+driver-short+} does not support running parallel operations within a single transaction. Additional Information ---------------------- From a0fd25da908ae7210af87b4bc6965822b0befacd Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 03:31:56 -0400 Subject: [PATCH 12/31] build error --- .../cluster-settings.txt | 198 ++++++++++-------- 1 file changed, 106 insertions(+), 92 deletions(-) diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 315ea6b51..6ff862510 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -37,54 +37,61 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: :header-rows: 1 :widths: 20 10 20 - * - Option Name - - Type - - Description + * - Option Name + - Type + - Description - * - **serverSelectionTimeoutMS** - - integer - - Specifies the maximum amount of time, in milliseconds, the driver - will wait for server selection to succeed before throwing an - exception. - + * - **serverSelectionTimeoutMS** + - integer + - | Specifies the maximum amount of time, in milliseconds, the driver + will wait for server selection to succeed before throwing an + exception. + | | **Default**: ``30000`` (30 seconds) - * - **localThresholdMS** - - integer - - When communicating with multiple instances of MongoDB in a replica - set, the driver will only send requests to a server whose - response time is less than or equal to the server with the fastest - response time plus the local threshold, in milliseconds. - + * - **localThresholdMS** + - integer + - | When communicating with multiple instances of MongoDB in a replica + set, the driver will only send requests to a server whose response + time is less than or equal to the server with the fastest response + time plus the local threshold, in milliseconds. + | | **Default**: ``15`` - * - **heartbeatFrequencyMS** - - integer - - Specifies the frequency, in milliseconds that the driver will - wait between attempts to determine the current state of each - server in the cluster. - + * - **heartbeatFrequencyMS** + - integer + - Specifies the frequency, in milliseconds that the driver will wait + between attempts to determine the current state of each server in + the cluster. + | | **Default**: ``10000`` (10 seconds) - * - **replicaSet** - - string - - Specifies that the :ref:`connection string ` + * - **replicaSet** + - string + - Specifies that the :ref:`connection string ` provided includes multiple hosts. When specified, the driver - attempts to find all members of that set. - + attempts to find all members of that set. + | | **Default**: ``null`` - * - **directConnection** - - boolean - - Specifies that the driver must connect to the host directly. This - maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your ``MongoClientSettings``. - + * - **directConnection** + - boolean + - Specifies that the driver must connect to the host directly. This + maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your + ``MongoClientSettings``. + | | **Default**: ``false`` - * - **srvServiceName** - - string - - Specifies the service name of the `SRV resource records `__ the driver retrieves to construct your :manual:`seed list `. You must use the :manual:`DNS Seed List Connection Format ` in your :ref:`connection URI ` to use this option. - + * - **srvServiceName** + - string + - | Specifies the service name of the `SRV resource records + `__ the driver retrieves to + construct your :manual:`seed list + `. You must use the + :manual:`DNS Seed List Connection Format + ` in + your :ref:`connection URI ` to use this option. + | | **Default**: ``mongodb`` .. tab:: MongoClientSettings @@ -102,62 +109,69 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: :header-rows: 1 :stub-columns: 1 :widths: 40 60 - - * - Method - - Description - - * - ``addClusterListener()`` - - Adds a listener for cluster-related events. - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the cluster settings specified in a ``ClusterSettings`` object. - - * - ``hosts()`` - - Sets all the specified locations of a Mongo deployment. - - * - ``localThreshold()`` - - | Sets the amount of time that a server’s round trip can take and still be eligible for server selection. - | - | **Default**: ``15 milliseconds`` - - * - ``mode()`` - - Sets how to connect to a MongoDB deployment. - - * - ``requiredClusterType()`` - - Sets the type of cluster required for the cluster. - - * - ``requiredReplicaSetName()`` - - Sets the replica set name required for the cluster. - - * - ``serverSelectionTimeout()`` - - | Sets the maximum time to select a primary node before throwing a timeout exception. - | - | **Default**: ``30 seconds`` - - * - ``serverSelector()`` - - Adds a server selector to apply before server selection. - - * - ``srvHost()`` - - | Sets the host name to use to look up an SRV DNS record to find the MongoDB hosts. - | - | If you want to enable the processing of TXT records associated with the host, specify the SRV host in the connection string using the ``applyConnectionString()`` method. - | - | For example: + + * - Method + - Description + + * - ``addClusterListener()`` + - Adds a listener for cluster-related events. + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the cluster settings specified in a ``ClusterSettings`` object. + + * - ``hosts()`` + - Sets all the specified locations of a Mongo deployment. + + * - ``localThreshold()`` + - | Sets the amount of time that a server’s round trip can take and + still be eligible for server selection. + | + | **Default**: ``15 milliseconds`` + + * - ``mode()`` + - Sets how to connect to a MongoDB deployment. + + * - ``requiredClusterType()`` + - Sets the type of cluster required for the cluster. + + * - ``requiredReplicaSetName()`` + - Sets the replica set name required for the cluster. + + * - ``serverSelectionTimeout()`` + - | Sets the maximum time to select a primary node before throwing a + timeout exception. + | + | **Default**: ``30 seconds`` + + * - ``serverSelector()`` + - Adds a server selector to apply before server selection. + + * - ``srvHost()`` + - | Sets the host name to use to look up an SRV DNS record to find the + MongoDB hosts. + | + | If you want to enable the processing of TXT records associated + with the host, specify the SRV host in the connection string using + the ``applyConnectionString()`` method. + | + | For example: - .. code-block:: java - :emphasize-lines: 3 + .. code-block:: java + :emphasize-lines: 3 - MongoClient mongoClient = + MongoClient mongoClient = MongoClients.create(MongoClientSettings.builder() - .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) - - * - ``srvMaxHosts()`` - - | Sets the maximum number of hosts the driver can connect to when using the DNS seedlist (SRV) connection protocol, identified by the ``mongodb+srv`` connection string prefix. - | - | Throws an exception if you are not using the SRV connection protocol. + .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) + + * - ``srvMaxHosts()`` + - | Sets the maximum number of hosts the driver can connect to when + using the DNS seedlist (SRV) connection protocol, identified by + the ``mongodb+srv`` connection string prefix. + | + | Throws an exception if you are not using the SRV connection protocol. Example ~~~~~~~ @@ -174,6 +188,6 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. tip:: - This is analogous to the ``directConnection`` parameter you can specify - in your connection URI. See :ref:`` for more - information. + This is analogous to the ``directConnection`` parameter you can specify + in your connection URI. See :ref:`` for more + information. From 4cd355f432d64b98c3b1aee59549072f8a897e39 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 03:40:33 -0400 Subject: [PATCH 13/31] widths test --- .../specify-connection-options/cluster-settings.txt | 1 - source/security/socks.txt | 11 +++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 6ff862510..c856e1808 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -35,7 +35,6 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. list-table:: :header-rows: 1 - :widths: 20 10 20 * - Option Name - Type diff --git a/source/security/socks.txt b/source/security/socks.txt index 05f513b1f..bbbdfc8a7 100644 --- a/source/security/socks.txt +++ b/source/security/socks.txt @@ -55,11 +55,14 @@ The following table describes the SOCKS5 client options: - String - Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. You must provide this value to connect to a SOCKS5 proxy. + | + | **Default**: ``null`` * - **proxyPort** - non-negative Integer - - Specifies the TCP port number of the SOCKS5 proxy server. This option - defaults to ``1080`` when you set ``proxyHost``. + - | Specifies the TCP port number of the SOCKS5 proxy server. + | + | **Default**: ``1080`` when you set ``proxyHost`` * - **proxyUsername** - String @@ -67,6 +70,8 @@ The following table describes the SOCKS5 client options: The driver ignores ``null`` and empty string values for this setting. The driver requires that you pass values for both ``proxyUsername`` and ``proxyPassword`` or that you omit both values. + | + | **Default**: ``null`` * - **proxyPassword** - String @@ -75,6 +80,8 @@ The following table describes the SOCKS5 client options: The driver requires that you pass values for both ``proxyUsername`` and ``proxyPassword`` or that you omit both values. + | **Default**: ``null`` + Examples -------- From 9a39adea87b1fa5edb3eecf2e27432466cb84aab Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 09:20:27 -0400 Subject: [PATCH 14/31] widths --- .../connection/specify-connection-options/cluster-settings.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index c856e1808..5ca17154b 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -35,6 +35,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. list-table:: :header-rows: 1 + :widths: 20 20 60 * - Option Name - Type From b59bd1c87857c1ecbf07f5ad6a5adbbd2576864d Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 10:36:31 -0400 Subject: [PATCH 15/31] crud config --- .../connection/specify-connection-options.txt | 1 + .../cluster-settings.txt | 4 +- .../configure-crud.txt | 133 ++++++++++++++++++ .../connection-options.txt | 112 --------------- .../connection-pools.txt | 9 ++ .../socket-settings.txt | 11 +- source/crud/crud-settings.txt | 50 +++++++ .../crud/read-write-pref-concerns.rst | 10 ++ .../code-snippets/MCSettings.java | 15 ++ 9 files changed, 230 insertions(+), 115 deletions(-) create mode 100644 source/connection/specify-connection-options/configure-crud.txt create mode 100644 source/crud/crud-settings.txt create mode 100644 source/includes/crud/read-write-pref-concerns.rst diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index daaefeaf0..b947fdaf1 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -11,6 +11,7 @@ Specify Connection Options Stable API Connection Pools Cluster Settings + Configure Client-level CRUD Settings Network Compression JNDI Datasource AWS Lambda diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 5ca17154b..f33a36176 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -24,7 +24,7 @@ In this guide, you can learn about how the {+driver-short+} manages clusters. You can specify settings for your clusters using either a :ref:`connection string ` or by passing a ``MongoClientSettings`` object to the -:ref:`MongoClients ` contructor. Select the :guilabel:`Connection +:ref:`MongoClients ` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: @@ -35,7 +35,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. list-table:: :header-rows: 1 - :widths: 20 20 60 + :widths: 40 40 20 * - Option Name - Type diff --git a/source/connection/specify-connection-options/configure-crud.txt b/source/connection/specify-connection-options/configure-crud.txt new file mode 100644 index 000000000..68a6c8ff0 --- /dev/null +++ b/source/connection/specify-connection-options/configure-crud.txt @@ -0,0 +1,133 @@ +.. _configure-client-crud: + +==================================== +Configure Client-level CRUD Settings +==================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +Overview +-------- + +In this guide, you can learn about how the {+driver-short+} configures CRUD +operations for ``MongoClient`` instances. + +.. include:: /includes/crud/read-write-pref-concerns.rst + +``MongoDatabase`` and ``MongoCollection`` instances inherit their preferences +and concerns from the ``MongoClient`` that accesses them. However, you can apply +custom settings to your databases and collections. See the :ref:`Configure Custom +CRUD Settings ` page for more information. + +You can specify client-level CRUD settings by using either a :ref:`connection +string ` or by passing a ``MongoClientSettings`` object to the +:ref:`MongoClients ` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: + +.. tabs:: + + .. tab:: Connection String + :tabid: uri + + .. code-block:: java + + ConnectionString connectionString = "mongodb://:/?readPreference=nearest" + MongoClient mongoClient = MongoClients.create(connectionString) + + .. list-table:: + :header-rows: 1 + :widths: 20 10 20 + + * - Option Name + - Type + - Description + + * - **journal** + - boolean + - | Specifies that the driver must wait for the connected MongoDB + instance to group commit to the journal file on disk for all + writes. + | + | **Default**: ``false`` + + * - **w** + - string or integer + - | Specifies the write concern. For more information about values, see the server documentation for the :manual:`w option `. + | + | **Default**: ``1`` + + * - **wtimeoutMS** + - integer + - | Specifies a time limit, in milliseconds, for the write concern. For + more information, see the server documentation for the + :manual:`wtimeoutMS option + `. A value of + ``0`` instructs the driver to never time out write operations. + | + | **Default**: ``0`` + + * - **readPreference** + - string + - | Specifies the read preference. For more information about values, + see the server documentation for the :manual:`readPreference option + `. + | + | **Default**: ``primary`` + + * - **readPreferenceTags** + - string + - | Specifies the read preference tags. For more information about + values, see the server documentation for the + :manual:`readPreferenceTags option + `. + | + | **Default**: ``null`` + + * - **maxStalenessSeconds** + - integer + - | Specifies, in seconds, how stale a secondary can be before the + driver stops communicating with that secondary. The minimum value + is either 90 seconds or the heartbeat frequency plus 10 seconds, + whichever is greater. For more information, see the server + documentation for the :manual:`maxStalenessSeconds option + `. Not + providing a parameter or explicitly specifying ``-1`` indicates + that there must be no staleness check for secondaries. + | + | **Default**: ``-1`` + + * - **uuidRepresentation** + - string + - | Specifies the UUID representation to use for read and write + operations. For more information, see the driver documentation for + the `MongoClientSettings.getUuidRepresentation() method + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__. + | + | **Default**: ``unspecified`` + + .. tab:: MongoClientSettings + :tabid: MongoClient + + Chain the `readConcern() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__, + `readPreference() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__, + or `writeConcern() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#writeConcern(com.mongodb.WriteConcern)>`__ + method to modify the way the driver manages its connection pool. The + following example chains the ``readPreference()`` method to + set the read preference level to the ``nearest`` replica set member: + + .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin ReadConcern + :end-before: end ReadConcern + :language: java + :dedent: + + \ No newline at end of file diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index ac14ca67b..9f79a4485 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -17,76 +17,6 @@ parameters of the connection URI to specify the behavior of the client. - Type - Description - * - **connectTimeoutMS** - - integer - - Specifies the maximum amount of time, in milliseconds, the Java - driver waits for a connection to open before timing out. A value of - ``0`` instructs the driver to never time out while waiting for a connection - to open. - - | **Default**: ``10000`` (10 seconds) - - * - **maxLifeTimeMS** - - integer - - Specifies the maximum amount of time, in milliseconds, the Java - driver will continue to use a pooled connection before closing the - connection. A value of ``0`` indicates that there is no upper bound - on how long the driver can keep a pooled connection open. - - | **Default**: ``0`` - - * - **journal** - - boolean - - Specifies that the driver must wait for the connected MongoDB - instance to group commit to the journal file on disk for all writes. - - | **Default**: ``false`` - - * - **w** - - string or integer - - Specifies the write concern. For more information about values, see - the server documentation for the :manual:`w option - `. - - | **Default**: ``1`` - - * - **wtimeoutMS** - - integer - - Specifies a time limit, in milliseconds, for the write concern. For - more information, see the server documentation for the - :manual:`wtimeoutMS option `. - A value of ``0`` instructs the driver to never time out write operations. - - | **Default**: ``0`` - - * - **readPreference** - - string - - Specifies the read preference. For more information about values, see - the server documentation for the - :manual:`readPreference option `. - - | **Default**: ``primary`` - - * - **readPreferenceTags** - - string - - Specifies the read preference tags. For more information about values, see - the server documentation for the - :manual:`readPreferenceTags option `. - - | **Default**: ``null`` - - * - **maxStalenessSeconds** - - integer - - Specifies, in seconds, how stale a secondary can be before the - driver stops communicating with that secondary. The minimum value is - either 90 seconds or the heartbeat frequency plus 10 seconds, whichever - is greater. For more information, see the server documentation for the - :manual:`maxStalenessSeconds option `. - Not providing a parameter or explicitly specifying ``-1`` indicates - that there must be no staleness check for secondaries. - - | **Default**: ``-1`` - * - **authMechanism** - string - Specifies the :ref:`authentication mechanism @@ -165,48 +95,6 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``auto`` - * - **uuidRepresentation** - - string - - Specifies the UUID representation to use for read and write - operations. For more information, see the driver documentation - for the - `MongoClientSettings.getUuidRepresentation() method <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__. - - | **Default**: ``unspecified`` - - * - **proxyHost** - - string - - Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. - You must provide this value to connect to a SOCKS5 proxy. - - | To learn how to connect to a SOCKS5 proxy, see the :ref:`Connect to - MongoDB by Using a SOCKS5 Proxy ` guide. - - | **Default**: ``null`` - - * - **proxyPort** - - non-negative integer - - Specifies the TCP port number of the SOCKS5 proxy server. - - | **Default**: ``1080`` when you set ``proxyHost`` - - * - **proxyUsername** - - string - - Specifies the username for authentication to the SOCKS5 proxy server. - The driver ignores ``null`` and empty string values for this setting. - The driver requires that you pass values for both ``proxyUsername`` - and ``proxyPassword`` or that you omit both values. - - | **Default**: ``null`` - - * - **proxyPassword** - - string - - Specifies the password for authentication to the SOCKS5 proxy server. - The driver ignores ``null`` and empty string values for this setting. - The driver requires that you pass values for both ``proxyUsername`` - and ``proxyPassword`` or that you omit both values. - - | **Default**: ``null`` For a complete list of options, see the `ConnectionString <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index 905ac6587..379c610aa 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -116,6 +116,15 @@ see the corresponding syntax: *Default*: ``120000`` (120 seconds) + * - ``maxLifeTimeMS`` + + - Specifies the maximum amount of time, in milliseconds, the Java driver + will continue to use a pooled connection before closing the + connection. A value of ``0`` indicates that there is no upper bound on + how long the driver can keep a pooled connection open. + + *Default*: ``0`` + .. tab:: MongoClientSettings :tabid: MongoClient diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index 50cf728a3..1bee6b533 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -22,7 +22,7 @@ settings. You can specify settings for your sockets using either a :ref:`connection string ` or by passing a ``MongoClientSettings`` object to the -:ref:`MongoClients ` contructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: +:ref:`MongoClients ` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: .. tabs:: @@ -37,6 +37,15 @@ string ` or by passing a ``MongoClientSettings`` object to the - Type - Description + * - **connectTimeoutMS** + - integer + - Specifies the maximum amount of time, in milliseconds, the Java + driver waits for a connection to open before timing out. A value of + ``0`` instructs the driver to never time out while waiting for a + connection to open. + | + | **Default**: ``10000`` (10 seconds) + * - **socketTimeoutMS** - integer - | Specifies the maximum amount of time, in milliseconds, the Java driver will wait to send or receive a request before timing out. A value of ``0`` instructs the driver to never time out while waiting to send or receive a request. diff --git a/source/crud/crud-settings.txt b/source/crud/crud-settings.txt new file mode 100644 index 000000000..e5c8b0296 --- /dev/null +++ b/source/crud/crud-settings.txt @@ -0,0 +1,50 @@ +.. _java-configure-custom-crud: + +============================== +Configure Custom CRUD Settings +============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +Overview +-------- + +In this guide, you can learn about how the {+driver-short+} configures CRUD +operations for ``MongoDatabase`` and ``MongoCollection`` instances. + +.. include:: /includes/crud/read-write-pref-concerns.rst + +By default, ``MongoDatabase`` and ``MongoCollection`` instances inherit their preferences +and concerns from the ``MongoClient`` that accesses them. See the +:ref:`Configure Client-level CRUD Settings ` page for +more information. However, you can apply custom settings to your individual databases and +collections by using the following methods: + +- `MongoDatabase.withReadConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#withReadConcern(com.mongodb.ReadConcern)>`__ + +- `MongoDatabase.withReadPreference() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#withReadPreference(com.mongodb.ReadPreference)>`__ + +- `MongoDatabase.withWriteConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#withWriteConcern(com.mongodb.WriteConcern)>`__ + +- `MongoCollection.withReadConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withReadConcern(com.mongodb.ReadConcern)>`__ + +- `MongoCollection.withReadPreference() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__ + +- `MongoCollection.withWriteConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withWriteConcern(com.mongodb.WriteConcern)>`__ + +.. tip:: + + The ``withReadConcern()``, ``withReadPreference()``, and + ``withWriteConcern`` methods create a new instance of a + ``MongoDatabase`` or ``MongoCollection`` with the desired preference + or concern. The ``MongoDatabase`` or ``MongoCollection`` upon which + the method is called retains its original preference and concern + settings. \ No newline at end of file diff --git a/source/includes/crud/read-write-pref-concerns.rst b/source/includes/crud/read-write-pref-concerns.rst new file mode 100644 index 000000000..afae0d46e --- /dev/null +++ b/source/includes/crud/read-write-pref-concerns.rst @@ -0,0 +1,10 @@ +**Read preferences**, **read concerns**, and **write concerns** control +how the driver routes read operations and waits for acknowledgment for +read and write operations when connected to a MongoDB replica set. +Read preferences and read concerns apply to all read operations; +write concerns apply to all write operations. + +For more information, see the server documentation on +:manual:`read preferences `, +:manual:`read concerns `, and +:manual:`write concerns `. \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/MCSettings.java b/source/includes/fundamentals/code-snippets/MCSettings.java index ba06e969c..2b020e7f3 100644 --- a/source/includes/fundamentals/code-snippets/MCSettings.java +++ b/source/includes/fundamentals/code-snippets/MCSettings.java @@ -151,4 +151,19 @@ private static void createLoggerSettings() { System.out.print("---------------------------------------"); } } + + private static void createReadConcern() { + try { + ////begin ReadConcern + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder().applyConnectionString(new ConnectionString("")) + .readPreference(ReadPreference.nearest()) + .build()); + //end ReadConcern + mongoClient.listDatabaseNames().forEach(n -> System.out.println(n)); + mongoClient.close(); + } finally { + System.out.print("---------------------------------------"); + } + } } \ No newline at end of file From b16294a96ca579433993890a20b9f5afda275277 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 13:01:09 -0400 Subject: [PATCH 16/31] table format --- .../connection/specify-connection-options.txt | 3 +- .../cluster-settings.txt | 62 ++++++------ .../configure-crud.txt | 94 +++++++++++++++---- .../connection-options.txt | 42 --------- .../mongoclientsettings.txt | 30 ------ .../socket-settings.txt | 2 +- source/security.txt | 10 +- 7 files changed, 117 insertions(+), 126 deletions(-) diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index b947fdaf1..6a65aa3b2 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -7,7 +7,8 @@ Specify Connection Options .. toctree:: Connection URI Options - MongoClient Settings + MongoClient Settings + Stable API Connection Pools Cluster Settings diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index f33a36176..67cd9b720 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -22,7 +22,7 @@ Overview In this guide, you can learn about how the {+driver-short+} manages clusters. -You can specify settings for your clusters using either a :ref:`connection +You can specify settings for your clusters by using either a :ref:`connection string ` or by passing a ``MongoClientSettings`` object to the :ref:`MongoClients ` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: @@ -43,56 +43,56 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - **serverSelectionTimeoutMS** - integer - - | Specifies the maximum amount of time, in milliseconds, the driver - will wait for server selection to succeed before throwing an - exception. - | - | **Default**: ``30000`` (30 seconds) + - Specifies the maximum amount of time, in milliseconds, the driver + will wait for server selection to succeed before throwing an + exception. + + **Default**: ``30000`` (30 seconds) * - **localThresholdMS** - integer - - | When communicating with multiple instances of MongoDB in a replica + - When communicating with multiple instances of MongoDB in a replica set, the driver will only send requests to a server whose response time is less than or equal to the server with the fastest response time plus the local threshold, in milliseconds. - | - | **Default**: ``15`` + + **Default**: ``15`` * - **heartbeatFrequencyMS** - integer - - Specifies the frequency, in milliseconds that the driver will wait - between attempts to determine the current state of each server in - the cluster. - | - | **Default**: ``10000`` (10 seconds) + - Specifies the frequency, in milliseconds that the driver will wait + between attempts to determine the current state of each server in + the cluster. + + **Default**: ``10000`` (10 seconds) * - **replicaSet** - string - Specifies that the :ref:`connection string ` provided includes multiple hosts. When specified, the driver attempts to find all members of that set. - | - | **Default**: ``null`` + + **Default**: ``null`` * - **directConnection** - boolean - Specifies that the driver must connect to the host directly. This maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your ``MongoClientSettings``. - | - | **Default**: ``false`` + + **Default**: ``false`` * - **srvServiceName** - string - - | Specifies the service name of the `SRV resource records - `__ the driver retrieves to - construct your :manual:`seed list - `. You must use the - :manual:`DNS Seed List Connection Format - ` in - your :ref:`connection URI ` to use this option. - | - | **Default**: ``mongodb`` + - Specifies the service name of the `SRV resource records + `__ the driver retrieves to + construct your :manual:`seed list + `. You must use the + :manual:`DNS Seed List Connection Format + ` in + your :ref:`connection URI ` to use this option. + + **Default**: ``mongodb`` .. tab:: MongoClientSettings :tabid: MongoClient @@ -126,7 +126,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: - Sets all the specified locations of a Mongo deployment. * - ``localThreshold()`` - - | Sets the amount of time that a server’s round trip can take and + - Sets the amount of time that a server’s round trip can take and still be eligible for server selection. | | **Default**: ``15 milliseconds`` @@ -141,7 +141,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: - Sets the replica set name required for the cluster. * - ``serverSelectionTimeout()`` - - | Sets the maximum time to select a primary node before throwing a + - Sets the maximum time to select a primary node before throwing a timeout exception. | | **Default**: ``30 seconds`` @@ -150,7 +150,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: - Adds a server selector to apply before server selection. * - ``srvHost()`` - - | Sets the host name to use to look up an SRV DNS record to find the + - Sets the host name to use to look up an SRV DNS record to find the MongoDB hosts. | | If you want to enable the processing of TXT records associated @@ -167,7 +167,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) * - ``srvMaxHosts()`` - - | Sets the maximum number of hosts the driver can connect to when + - Sets the maximum number of hosts the driver can connect to when using the DNS seedlist (SRV) connection protocol, identified by the ``mongodb+srv`` connection string prefix. | diff --git a/source/connection/specify-connection-options/configure-crud.txt b/source/connection/specify-connection-options/configure-crud.txt index 68a6c8ff0..d0553c6a9 100644 --- a/source/connection/specify-connection-options/configure-crud.txt +++ b/source/connection/specify-connection-options/configure-crud.txt @@ -13,6 +13,9 @@ Configure Client-level CRUD Settings .. facet:: :name: genre :values: reference + +.. meta:: + :keywords: retries Overview -------- @@ -43,7 +46,7 @@ string ` or by passing a ``MongoClientSettings`` object to the .. list-table:: :header-rows: 1 - :widths: 20 10 20 + :widths: 25,25,50 * - Option Name - Type @@ -54,14 +57,14 @@ string ` or by passing a ``MongoClientSettings`` object to the - | Specifies that the driver must wait for the connected MongoDB instance to group commit to the journal file on disk for all writes. - | - | **Default**: ``false`` + | + | **Default**: ``false`` * - **w** - string or integer - | Specifies the write concern. For more information about values, see the server documentation for the :manual:`w option `. - | - | **Default**: ``1`` + | + | **Default**: ``1`` * - **wtimeoutMS** - integer @@ -70,16 +73,16 @@ string ` or by passing a ``MongoClientSettings`` object to the :manual:`wtimeoutMS option `. A value of ``0`` instructs the driver to never time out write operations. - | - | **Default**: ``0`` + | + | **Default**: ``0`` * - **readPreference** - string - | Specifies the read preference. For more information about values, see the server documentation for the :manual:`readPreference option `. - | - | **Default**: ``primary`` + | + | **Default**: ``primary`` * - **readPreferenceTags** - string @@ -87,8 +90,8 @@ string ` or by passing a ``MongoClientSettings`` object to the values, see the server documentation for the :manual:`readPreferenceTags option `. - | - | **Default**: ``null`` + | + | **Default**: ``null`` * - **maxStalenessSeconds** - integer @@ -100,8 +103,8 @@ string ` or by passing a ``MongoClientSettings`` object to the `. Not providing a parameter or explicitly specifying ``-1`` indicates that there must be no staleness check for secondaries. - | - | **Default**: ``-1`` + | + | **Default**: ``-1`` * - **uuidRepresentation** - string @@ -109,13 +112,72 @@ string ` or by passing a ``MongoClientSettings`` object to the operations. For more information, see the driver documentation for the `MongoClientSettings.getUuidRepresentation() method <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__. - | - | **Default**: ``unspecified`` + | + | **Default**: ``unspecified`` + + * - **retryWrites** + - boolean + - | Specifies that the driver must retry supported write operations if + they are unable to complete due to a network error. + | + | **Default**: ``true`` + + * - **retryReads** + - boolean + - | Specifies that the driver must retry supported read operations if + they are unable to complete due to a network error. + | + | **Default**: ``true`` .. tab:: MongoClientSettings :tabid: MongoClient - Chain the `readConcern() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__, + Chain the following methods to your ``MongoClientSettings`` constructor to modify the driver's read/write behavior: + + .. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 40 60 + + * - ``readConcern()`` + - | Sets the read concern. + | - :manual:`Server manual page ` + | - `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__ + + * - ``readPreference()`` + - | Sets the read preference. + | - :manual:`Server manual page ` + | - `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__ + | + | **Default**: ``primary`` + + * - ``retryReads()`` + - | Whether the driver performs :manual:`retry reads + ` if a network error occurs. + | - :manual:`Server manual page ` + | + | **Default**: ``true`` + + * - ``retryWrites()`` + - | Whether the driver performs :manual:`retry writes + ` if a network error occurs. + | + | **Default**: ``true`` + + * - ``uuidRepresentation()`` + - Sets the UUID representation to use when encoding instances of UUID + and decoding BSON binary values with subtype of 3. + + * - ``writeConcern()`` + - | Sets the :manual:`write concern `. + | + | **Default**: ``WriteConcern#ACKNOWLEDGED``. + | For more information about the default value, see :manual:`Implicit Default Write Concern `. + + + + `readConcern() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__, `readPreference() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__, or `writeConcern() diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index 9f79a4485..ea25aacaa 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -17,34 +17,6 @@ parameters of the connection URI to specify the behavior of the client. - Type - Description - * - **authMechanism** - - string - - Specifies the :ref:`authentication mechanism - ` that the driver uses if a credential - was supplied. - - | **Default**: By default, the client picks the most secure - mechanism available based on the server version. For possible - values, see the server documentation for the - :manual:`authMechanism option - `. - - * - **authSource** - - string - - Specifies the database in which the supplied credentials are validated. - - | **Default**: ``admin`` - - * - **authMechanismProperties** - - string - - Specifies authentication properties for the specified authentication - mechanism as a list of colon-separated properties and values. - For more information, see the server documentation for - the :manual:`authMechanismProperties option - `. - - | **Default**: ``null`` - * - **appName** - string - Specifies the name of the application provided to MongoDB instances @@ -72,20 +44,6 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``null`` - * - **retryWrites** - - boolean - - Specifies that the driver must retry supported write operations - if they are unable to complete due to a network error. - - | **Default**: ``true`` - - * - **retryReads** - - boolean - - Specifies that the driver must retry supported read operations - if they are unable to complete due to a network error. - - | **Default**: ``true`` - * - **serverMonitoringMode** - string - Specifies which server monitoring protocol the driver uses. When set to diff --git a/source/connection/specify-connection-options/mongoclientsettings.txt b/source/connection/specify-connection-options/mongoclientsettings.txt index 1c5597583..ec4bba754 100644 --- a/source/connection/specify-connection-options/mongoclientsettings.txt +++ b/source/connection/specify-connection-options/mongoclientsettings.txt @@ -102,26 +102,6 @@ connection behavior: * - ``credential()`` - Sets the :ref:`credential `. - * - ``readConcern()`` - - Sets the :manual:`read concern `. - - * - ``readPreference()`` - - | Sets the :manual:`read preference `. - | - | **Default**: ``primary`` - - * - ``retryReads()`` - - | Whether the driver performs :manual:`retry reads ` - if a network error occurs. - | - | **Default**: ``true`` - - * - ``retryWrites()`` - - | Whether the driver performs :manual:`retry writes ` - if a network error occurs. - | - | **Default**: ``true`` - * - ``serverApi()`` - Sets the :ref:`server API ` to use when sending commands to the server. @@ -129,16 +109,6 @@ connection behavior: * - ``transportSettings()`` - Sets `TransportSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/TransportSettings.html>`__. - * - ``uuidRepresentation()`` - - Sets the UUID representation to use when encoding instances of UUID - and decoding BSON binary values with subtype of 3. - - * - ``writeConcern()`` - - | Sets the :manual:`write concern `. - | - | **Default**: ``WriteConcern#ACKNOWLEDGED``. For more information about - the default value, see :manual:`Implicit Default Write Concern `. - .. _connection-string-example: Example diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index 1bee6b533..52fbaf853 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -20,7 +20,7 @@ Overview In this guide, you can learn about how the {+driver-short+} manages socket settings. -You can specify settings for your sockets using either a :ref:`connection +You can specify settings for your sockets by using either a :ref:`connection string ` or by passing a ``MongoClientSettings`` object to the :ref:`MongoClients ` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: diff --git a/source/security.txt b/source/security.txt index 15a5d2a07..84ff04a9d 100644 --- a/source/security.txt +++ b/source/security.txt @@ -1,8 +1,8 @@ .. _java-security: -======== -Security -======== +=========================== +Security and Authentication +=========================== .. meta:: :description: Learn how to use security features with the {+driver-long+}. @@ -20,7 +20,7 @@ Security Overview -------- -Learn how to set up security options for your application in the following -sections: +Learn how to set up security and authentication options for your application in +the following sections: .. include:: /includes/security/security-pages.rst \ No newline at end of file From dff066c66a82f8da319429c18a7ffab1cead15de Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 17 Mar 2025 16:18:00 -0400 Subject: [PATCH 17/31] connection options --- .../connection/specify-connection-options.txt | 1 - .../cluster-settings.txt | 73 ++++---- .../configure-crud.txt | 176 +++++++++--------- .../connection-options.txt | 59 ------ .../connection-pools.txt | 38 ++-- .../network-compression.txt | 59 ++++-- .../server-settings.txt | 159 +++++++++++----- .../socket-settings.txt | 176 ++++++++++-------- .../specify-connection-options/stable-api.txt | 18 +- 9 files changed, 403 insertions(+), 356 deletions(-) delete mode 100644 source/connection/specify-connection-options/connection-options.txt diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 6a65aa3b2..776924fb3 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -6,7 +6,6 @@ Specify Connection Options .. toctree:: - Connection URI Options MongoClient Settings Stable API diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 67cd9b720..7b023598e 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -33,9 +33,11 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. tab:: Connection String :tabid: uri - .. list-table:: - :header-rows: 1 - :widths: 40 40 20 + Include the following parameters in your connection string to modify the driver's behavior when interacting with your MongoDB cluster: + + .. list-table:: + :header-rows: 1 + :widths: 20,20,60 * - Option Name - Type @@ -52,33 +54,24 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - **localThresholdMS** - integer - When communicating with multiple instances of MongoDB in a replica - set, the driver will only send requests to a server whose response - time is less than or equal to the server with the fastest response - time plus the local threshold, in milliseconds. + set, the driver will only send requests to a server whose response + time is less than or equal to the server with the fastest response + time plus the local threshold, in milliseconds. **Default**: ``15`` - - * - **heartbeatFrequencyMS** - - integer - - Specifies the frequency, in milliseconds that the driver will wait - between attempts to determine the current state of each server in - the cluster. - - **Default**: ``10000`` (10 seconds) - * - **replicaSet** - string - Specifies that the :ref:`connection string ` - provided includes multiple hosts. When specified, the driver - attempts to find all members of that set. + provided includes multiple hosts. When specified, the driver + attempts to find all members of that set. **Default**: ``null`` * - **directConnection** - boolean - Specifies that the driver must connect to the host directly. This - maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your - ``MongoClientSettings``. + maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your + ``MongoClientSettings``. **Default**: ``false`` @@ -128,8 +121,8 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - ``localThreshold()`` - Sets the amount of time that a server’s round trip can take and still be eligible for server selection. - | - | **Default**: ``15 milliseconds`` + + **Default**: ``15 milliseconds`` * - ``mode()`` - Sets how to connect to a MongoDB deployment. @@ -142,22 +135,19 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - ``serverSelectionTimeout()`` - Sets the maximum time to select a primary node before throwing a - timeout exception. - | - | **Default**: ``30 seconds`` + timeout exception. + + **Default**: ``30 seconds`` * - ``serverSelector()`` - Adds a server selector to apply before server selection. * - ``srvHost()`` - - Sets the host name to use to look up an SRV DNS record to find the - MongoDB hosts. - | - | If you want to enable the processing of TXT records associated - with the host, specify the SRV host in the connection string using - the ``applyConnectionString()`` method. - | - | For example: + - Sets the host name to use to look up an SRV DNS record to find the MongoDB hosts. + + If you want to enable the processing of TXT records associated with the host, specify the SRV host in the connection string using the ``applyConnectionString()`` method. + + For example: .. code-block:: java :emphasize-lines: 3 @@ -170,11 +160,8 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: - Sets the maximum number of hosts the driver can connect to when using the DNS seedlist (SRV) connection protocol, identified by the ``mongodb+srv`` connection string prefix. - | - | Throws an exception if you are not using the SRV connection protocol. - - Example - ~~~~~~~ + + Throws an exception if you are not using the SRV connection protocol. This example specifies for the driver to connect directly to a server, regardless of the type of MongoDB cluster it's a part of: @@ -186,8 +173,12 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: :emphasize-lines: 3-4 :dedent: - .. tip:: + .. tip:: + + This is analogous to the ``directConnection`` parameter you can specify + in your connection URI. See :ref:`` for more + information. - This is analogous to the ``directConnection`` parameter you can specify - in your connection URI. See :ref:`` for more - information. + For more information, see the `MongoClientSettings.Builder + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ + API documentation. \ No newline at end of file diff --git a/source/connection/specify-connection-options/configure-crud.txt b/source/connection/specify-connection-options/configure-crud.txt index d0553c6a9..d424bb1f0 100644 --- a/source/connection/specify-connection-options/configure-crud.txt +++ b/source/connection/specify-connection-options/configure-crud.txt @@ -38,15 +38,13 @@ string ` or by passing a ``MongoClientSettings`` object to the .. tab:: Connection String :tabid: uri - - .. code-block:: java - - ConnectionString connectionString = "mongodb://:/?readPreference=nearest" - MongoClient mongoClient = MongoClients.create(connectionString) + Include the following parameters in your connection string to modify the + driver's read/write behavior: + .. list-table:: :header-rows: 1 - :widths: 25,25,50 + :widths: 20,20,60 * - Option Name - Type @@ -54,80 +52,92 @@ string ` or by passing a ``MongoClientSettings`` object to the * - **journal** - boolean - - | Specifies that the driver must wait for the connected MongoDB - instance to group commit to the journal file on disk for all - writes. - | - | **Default**: ``false`` + - Specifies that the driver must wait for the connected MongoDB instance to group commit to the journal file on disk for all writes. + + **Default**: ``false`` * - **w** - string or integer - - | Specifies the write concern. For more information about values, see the server documentation for the :manual:`w option `. - | - | **Default**: ``1`` + - Specifies the write concern. For more information about values, see + the server documentation for the :manual:`w option + `. + + **Default**: ``1`` * - **wtimeoutMS** - integer - - | Specifies a time limit, in milliseconds, for the write concern. For - more information, see the server documentation for the - :manual:`wtimeoutMS option - `. A value of - ``0`` instructs the driver to never time out write operations. - | - | **Default**: ``0`` + - Specifies a time limit, in milliseconds, for the write concern. For + more information, see the server documentation for the + :manual:`wtimeoutMS option + `. A value of + ``0`` instructs the driver to never time out write operations. + + **Default**: ``0`` * - **readPreference** - string - - | Specifies the read preference. For more information about values, - see the server documentation for the :manual:`readPreference option - `. - | - | **Default**: ``primary`` + - Specifies the read preference. For more information about values, see + the server documentation for the :manual:`readPreference option + `. + + **Default**: ``primary`` * - **readPreferenceTags** - string - - | Specifies the read preference tags. For more information about - values, see the server documentation for the - :manual:`readPreferenceTags option - `. - | - | **Default**: ``null`` + - Specifies the read preference tags. For more information about + values, see the server documentation for the + :manual:`readPreferenceTags option + `. + + **Default**: ``null`` * - **maxStalenessSeconds** - integer - - | Specifies, in seconds, how stale a secondary can be before the - driver stops communicating with that secondary. The minimum value - is either 90 seconds or the heartbeat frequency plus 10 seconds, - whichever is greater. For more information, see the server - documentation for the :manual:`maxStalenessSeconds option - `. Not - providing a parameter or explicitly specifying ``-1`` indicates - that there must be no staleness check for secondaries. - | - | **Default**: ``-1`` + - Specifies, in seconds, how stale a secondary can be before the driver + stops communicating with that secondary. The minimum value is either + 90 seconds or the heartbeat frequency plus 10 seconds, whichever is + greater. For more information, see the server documentation for the + :manual:`maxStalenessSeconds option + `. Not + providing a parameter or explicitly specifying ``-1`` indicates that + there must be no staleness check for secondaries. + + **Default**: ``-1`` * - **uuidRepresentation** - string - - | Specifies the UUID representation to use for read and write - operations. For more information, see the driver documentation for - the `MongoClientSettings.getUuidRepresentation() method - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__. - | - | **Default**: ``unspecified`` + - Specifies the UUID representation to use for read and write + operations. For more information, see the driver documentation for + the `MongoClientSettings.getUuidRepresentation() method + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__. + + **Default**: ``unspecified`` * - **retryWrites** - boolean - - | Specifies that the driver must retry supported write operations if - they are unable to complete due to a network error. - | - | **Default**: ``true`` + - Specifies that the driver must retry supported write operations if + they are unable to complete due to a network error. + + **Default**: ``true`` * - **retryReads** - boolean - - | Specifies that the driver must retry supported read operations if - they are unable to complete due to a network error. - | - | **Default**: ``true`` + - Specifies that the driver must retry supported read operations if + they are unable to complete due to a network error. + + **Default**: ``true`` + + The following example sets the read preference to read from the nearest + replica set member: + + .. code-block:: java + + ConnectionString connectionString = "mongodb://:/?readPreference=nearest" + MongoClient mongoClient = MongoClients.create(connectionString) + + For more information about these parameters, see the `ConnectionString + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ + API documentation. .. tab:: MongoClientSettings :tabid: MongoClient @@ -140,56 +150,48 @@ string ` or by passing a ``MongoClientSettings`` object to the :widths: 40 60 * - ``readConcern()`` - - | Sets the read concern. - | - :manual:`Server manual page ` - | - `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__ + - Sets the read concern. + :manual:`Server manual page ` + `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__ * - ``readPreference()`` - - | Sets the read preference. - | - :manual:`Server manual page ` - | - `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__ - | - | **Default**: ``primary`` + - Sets the :manual:`read preference ` + + **Default**: ``primary`` * - ``retryReads()`` - - | Whether the driver performs :manual:`retry reads - ` if a network error occurs. - | - :manual:`Server manual page ` - | - | **Default**: ``true`` + - Whether the driver performs :manual:`retry reads + ` if a network error occurs. + + **Default**: ``true`` * - ``retryWrites()`` - - | Whether the driver performs :manual:`retry writes - ` if a network error occurs. - | - | **Default**: ``true`` + - Whether the driver performs :manual:`retry writes + ` if a network error occurs. + + **Default**: ``true`` * - ``uuidRepresentation()`` - Sets the UUID representation to use when encoding instances of UUID and decoding BSON binary values with subtype of 3. * - ``writeConcern()`` - - | Sets the :manual:`write concern `. - | - | **Default**: ``WriteConcern#ACKNOWLEDGED``. + - Sets the :manual:`write concern `. + + **Default**: ``WriteConcern#ACKNOWLEDGED``. | For more information about the default value, see :manual:`Implicit Default Write Concern `. - - - `readConcern() - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__, - `readPreference() - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__, - or `writeConcern() - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#writeConcern(com.mongodb.WriteConcern)>`__ - method to modify the way the driver manages its connection pool. The - following example chains the ``readPreference()`` method to - set the read preference level to the ``nearest`` replica set member: + The following example sets the read preference to read from the nearest + replica set member: .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java :start-after: begin ReadConcern :end-before: end ReadConcern :language: java :dedent: + + For more information about these methods, see the `MongoClientSettings.Builder + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#>`__ + API documentation. \ No newline at end of file diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt deleted file mode 100644 index ea25aacaa..000000000 --- a/source/connection/specify-connection-options/connection-options.txt +++ /dev/null @@ -1,59 +0,0 @@ -.. _java-connection-uri-options: -.. _connection-options: - -====================== -Connection URI Options -====================== - -This section explains MongoDB connection and authentication options -supported by the {+driver-short+}. You can pass the connection options as -parameters of the connection URI to specify the behavior of the client. - -.. list-table:: - :header-rows: 1 - :widths: 20 10 20 - - * - Option Name - - Type - - Description - - * - **appName** - - string - - Specifies the name of the application provided to MongoDB instances - during the connection handshake. Can be used for server logs and - profiling. - - | **Default**: ``null`` - - * - **compressors** - - string - - Specifies one or more compression algorithms that the driver - will attempt to use to compress requests sent to the connected - MongoDB instance. Possible values include: ``zlib``, ``snappy``, - and ``zstd``. - - | **Default**: ``null`` - - * - **zlibCompressionLevel** - - integer - - Specifies the degree of compression that `Zlib `__ - uses to decrease the size of requests to the connected MongoDB - instance. The level can range from ``-1`` to ``9``, with lower values - compressing faster (but resulting in larger requests) and larger values - compressing slower (but resulting in smaller requests). - - | **Default**: ``null`` - - * - **serverMonitoringMode** - - string - - Specifies which server monitoring protocol the driver uses. When set to - ``auto``, the monitoring mode is determined by the environment in which - the driver is running. The driver uses ``poll`` mode in function-as-a-service - (FaaS) environments and ``stream`` mode in other environments. - - | **Default**: ``auto`` - - -For a complete list of options, see the -`ConnectionString <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ -API documentation. diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index 379c610aa..a7166694e 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -53,7 +53,6 @@ You can specify settings for your connection pool using either a connection string or by passing a ``MongoClientSettings`` object to the ``MongoClients.create()`` method. -The following code creates a client with a maximum connection pool size of ``50``. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the corresponding syntax: @@ -61,11 +60,6 @@ see the corresponding syntax: .. tab:: Connection String :tabid: uri - - .. code-block:: java - - ConnectionString connectionString = "mongodb://:/?maxPoolSize=50" - MongoClient mongoClient = MongoClients.create(connectionString) The following are connection string settings you can use to configure your connection pool: @@ -124,17 +118,22 @@ see the corresponding syntax: how long the driver can keep a pooled connection open. *Default*: ``0`` + + The following code creates a client with a maximum connection pool size of ``50``. + + .. code-block:: java + + ConnectionString connectionString = "mongodb://:/?maxPoolSize=50" + MongoClient mongoClient = MongoClients.create(connectionString) + + For more information about these parameters, see the `ConnectionString + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ + API documentation. .. tab:: MongoClientSettings :tabid: MongoClient - Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ method to modify the way the driver manages its connection pool. The following example chains the ``applyToConnectionPoolSettings()`` method to set the thread to wait at most ``10 SECONDS`` for an available connection, and the ``maxSize`` of the connection pool to 200: - - .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java - :start-after: begin MongoSettings - :end-before: end MongoSettings - :language: java - :dedent: + Chain the `applyToConnectionPoolSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToConnectionPoolSettings(com.mongodb.Block)>`__ method to modify the way the driver manages its connection pool. The following table describes the methods you can chain to your settings to modify the driver's behavior: @@ -189,7 +188,18 @@ see the corresponding syntax: This ``maxSize`` and ``minSize`` settings apply to each server in the cluster you connect the driver to. - For example, assume you connect the driver to a cluster with three ``mongos`` servers. This means that there can be at most ``maxSize`` connections and at least ``minSize`` connections to each ``mongos`` server. + For example, assume you connect the driver to a cluster with three + ``mongos`` servers. This means that there can be at most ``maxSize`` + connections and at least ``minSize`` connections to each ``mongos`` + server. + + The following example chains the ``applyToConnectionPoolSettings()`` method to set the thread to wait at most ``10 SECONDS`` for an available connection, and the ``maxSize`` of the connection pool to 200: + + .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java + :start-after: begin MongoSettings + :end-before: end MongoSettings + :language: java + :dedent: Additional Information ---------------------- diff --git a/source/connection/specify-connection-options/network-compression.txt b/source/connection/specify-connection-options/network-compression.txt index 34b71badd..0a2213006 100644 --- a/source/connection/specify-connection-options/network-compression.txt +++ b/source/connection/specify-connection-options/network-compression.txt @@ -62,21 +62,50 @@ tab to see the corresponding syntax: .. tabs:: - .. tab:: Connection String - :tabid: connectionstring - - .. literalinclude:: /includes/connect/NetworkCompression.java - :start-after: start-specify-connection-string - :end-before: end-specify-connection-string - :language: java - - .. tab:: MongoClientSettings - :tabid: mongoclientsettings - - .. literalinclude:: /includes/connect/NetworkCompression.java - :start-after: start-specify-client-settings - :end-before: end-specify-client-settings - :language: java + .. tab:: Connection String + :tabid: uri + + .. literalinclude:: /includes/connect/NetworkCompression.java + :start-after: start-specify-connection-string + :end-before: end-specify-connection-string + :language: java + + Include the following parameters in your connection string to enable compression: + + .. list-table:: + :header-rows: 1 + :widths: 20,20,60 + + * - Option Name + - Type + - Description + + * - **compressors** + - string + - Specifies one or more compression algorithms that the driver will + attempt to use to compress requests sent to the connected MongoDB + instance. Possible values include: ``zlib``, ``snappy``, and + ``zstd``. + + **Default**: ``null`` + + * - **zlibCompressionLevel** + - integer + - Specifies the degree of compression that `Zlib `__ + uses to decrease the size of requests to the connected MongoDB + instance. The level can range from ``-1`` to ``9``, with lower values + compressing faster (but resulting in larger requests) and larger + values compressing slower (but resulting in smaller requests). + + **Default**: ``null`` + + .. tab:: MongoClientSettings + :tabid: mongoclientsettings + + .. literalinclude:: /includes/connect/NetworkCompression.java + :start-after: start-specify-client-settings + :end-before: end-specify-client-settings + :language: java .. _java-compression-dependencies: diff --git a/source/connection/specify-connection-options/server-settings.txt b/source/connection/specify-connection-options/server-settings.txt index d2ac7b02e..baa6d5c3d 100644 --- a/source/connection/specify-connection-options/server-settings.txt +++ b/source/connection/specify-connection-options/server-settings.txt @@ -23,54 +23,111 @@ settings. Configuring Server Settings --------------------------- -Chain the `applyToServerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToServerSettings(com.mongodb.Block)>`__ -method to modify the driver's behavior when monitoring each MongoDB -deployment. - -The following table describes the methods you can chain to your -settings to modify the driver's behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``addServerListener()`` - - Adds a listener for server-related events. - - * - ``addServerMonitorListener()`` - - Adds a listener for server monitor-related events. - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the server settings specified in a ``ServerSettings`` object. - - * - ``heartbeatFrequency()`` - - | Sets the interval for a cluster monitor to attempt reaching a server. - | - | **Default**: ``10 seconds`` - - * - ``minHeartbeatFrequency()`` - - | Sets the minimum interval for server monitoring checks. - | - | **Default**: ``500 milliseconds`` - -Example -~~~~~~~ - -This example specifies the following driver behavior in a MongoDB deployment: - -- The minimum interval for server monitoring checks to be at least - ``700 MILLISECONDS`` -- The cluster monitor to attempt reaching a server every ``15 SECONDS`` - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin ServerSettings - :end-before: end ServerSettings - :language: java - :emphasize-lines: 3-5 - :dedent: +.. tabs:: + + .. tab:: Connection String + :tabid: uri + + Include the following parameters in your connection string to modify the + driver's behavior when interacting with the server: + + .. list-table:: + :header-rows: 1 + :widths: 20,20,60 + + * - Option Name + - Type + - Description + + * - **appName** + - string + - Specifies the name of the application provided to MongoDB instances + during the connection handshake. Can be used for server logs and + profiling. + + **Default**: ``null`` + + * - **serverMonitoringMode** + - string + - Specifies which server monitoring protocol the driver uses. When set + to ``auto``, the monitoring mode is determined by the environment in + which the driver is running. The driver uses ``poll`` mode in + function-as-a-service (FaaS) environments and ``stream`` mode in + other environments. + + **Default**: ``auto`` + + * - **heartbeatFrequencyMS** + - integer + - Specifies the frequency, in milliseconds that the driver will wait + between attempts to determine the current state of each server in + the cluster. + + **Default**: ``10000`` (10 seconds) + + + This example specifies that the cluster monitor will attempt to reach a + server every 15 seconds: + + .. code-block:: java + + ConnectionString connectionString = "mongodb://:/?heartbeatFrequencyMS=15000" + MongoClient mongoClient = MongoClients.create(connectionString) + + For more information about these parameters, see the `ConnectionString + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ + API documentation. + + + .. tab:: MongoClientSettings + :tabid: MongoClient + + Chain the `applyToServerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToServerSettings(com.mongodb.Block)>`__ method to modify the driver's behavior when monitoring each MongoDB deployment. + + The following table describes the methods you can chain to your settings to modify the driver's behavior: + + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``addServerListener()`` + - Adds a listener for server-related events. + + * - ``addServerMonitorListener()`` + - Adds a listener for server monitor-related events. + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the server settings specified in a ``ServerSettings`` object. + + * - ``heartbeatFrequency()`` + - Sets the interval for a cluster monitor to attempt reaching a server. + + **Default**: ``10 seconds`` + + * - ``minHeartbeatFrequency()`` + - Sets the minimum interval for server monitoring checks. + + **Default**: ``500 milliseconds`` + + This example specifies the following driver behavior in a MongoDB deployment: + + - The minimum interval for server monitoring checks to be at least + ``700 MILLISECONDS`` + - The cluster monitor to attempt reaching a server every ``15 SECONDS`` + + .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin ServerSettings + :end-before: end ServerSettings + :language: java + :emphasize-lines: 3-5 + :dedent: + + For more information, see the `MongoClientSettings.Builder + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ + API documentation. diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index 52fbaf853..49183cc19 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -29,31 +29,46 @@ string ` or by passing a ``MongoClientSettings`` object to the .. tab:: Connection String :tabid: uri - .. list-table:: - :header-rows: 1 - :widths: 20 10 20 + .. list-table:: + :header-rows: 1 + :widths: 20,20,60 - * - Option Name - - Type - - Description + * - Option Name + - Type + - Description - * - **connectTimeoutMS** - - integer - - Specifies the maximum amount of time, in milliseconds, the Java - driver waits for a connection to open before timing out. A value of - ``0`` instructs the driver to never time out while waiting for a - connection to open. - | - | **Default**: ``10000`` (10 seconds) + * - **connectTimeoutMS** + - integer + - Specifies the maximum amount of time, in milliseconds, the Java + driver waits for a connection to open before timing out. A value of + ``0`` instructs the driver to never time out while waiting for a + connection to open. + + **Default**: ``10000`` (10 seconds) - * - **socketTimeoutMS** - - integer - - | Specifies the maximum amount of time, in milliseconds, the Java driver will wait to send or receive a request before timing out. A value of ``0`` instructs the driver to never time out while waiting to send or receive a request. - | - | **Default**: ``0`` - - .. tab:: Connection String - :tabid: uri + * - **socketTimeoutMS** + - integer + - Specifies the maximum amount of time, in milliseconds, the Java + driver will wait to send or receive a request before timing out. A + value of ``0`` instructs the driver to never time out while waiting + to send or receive a request. + + **Default**: ``0`` + + This example specifies that the driver will time out after 15 seconds of + waiting for a connection to open: + + .. code-block:: java + + ConnectionString connectionString = "mongodb://:/?connectTimeoutMS=15000" + MongoClient mongoClient = MongoClients.create(connectionString) + + For more information about these parameters, see the `ConnectionString + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ + API documentation. + + .. tab:: MongoClientSettings + :tabid: MongoClient Chain the `applyToSocketSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSocketSettings(com.mongodb.Block)>`__ method to modify the driver's behavior when connecting and communicating @@ -62,61 +77,62 @@ string ` or by passing a ``MongoClientSettings`` object to the The following table describes the methods you can chain to your settings to modify the driver's behavior: -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - - * - ``applySettings()`` - - Uses the socket settings specified in a ``SocketSettings`` object. - - * - ``connectTimeout()`` - - | Sets the maximum time to connect to an available socket before throwing - a timeout exception. - | - | **Default**: ``10 seconds`` - - * - ``readTimeout()`` - - | Sets the maximum time to read from an available socket before throwing a - timeout exception. - | - | **Default**: ``0``, which indicates no timeout - - * - ``receiveBufferSize()`` - - | Sets the socket's buffer size when receiving. - | - | **Default**: The operating system default - - * - ``sendBufferSize()`` - - | Sets the socket's buffer size when sending. - | - | **Default**: The operating system default - -.. note:: Connect to MongoDB by using a SOCKS5 Proxy - - You can chain the ``applyToProxySettings()`` method to your socket settings to - connect to MongoDB by using a SOCKS5 proxy. To learn how to use a SOCKS5 proxy - and set proxy settings, see the :ref:`Connect to MongoDB by Using a SOCKS5 Proxy - ` guide. - -.. _java-socketsettings-example: - -Example -------- - -This example specifies the following driver behavior in a MongoDB socket: - -- To connect to an available socket within ``10 SECONDS`` -- To read from an available socket within ``15 SECONDS`` - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin SocketSettings - :end-before: end SocketSettings - :language: java - :emphasize-lines: 3-5 - :dedent: + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``applyConnectionString()`` + - Uses the settings from a ``ConnectionString`` object. + + * - ``applySettings()`` + - Uses the socket settings specified in a ``SocketSettings`` object. + + * - ``connectTimeout()`` + - | Sets the maximum time to connect to an available socket before throwing + a timeout exception. + | + | **Default**: ``10 seconds`` + + * - ``readTimeout()`` + - | Sets the maximum time to read from an available socket before throwing a + timeout exception. + | + | **Default**: ``0``, which indicates no timeout + + * - ``receiveBufferSize()`` + - | Sets the socket's buffer size when receiving. + | + | **Default**: The operating system default + + * - ``sendBufferSize()`` + - | Sets the socket's buffer size when sending. + | + | **Default**: The operating system default + + .. note:: Connect to MongoDB by using a SOCKS5 Proxy + + You can chain the ``applyToProxySettings()`` method to your socket settings to + connect to MongoDB by using a SOCKS5 proxy. To learn how to use a SOCKS5 proxy + and set proxy settings, see the :ref:`Connect to MongoDB by Using a SOCKS5 Proxy + ` guide. + + .. _java-socketsettings-example: + + This example specifies the following driver behavior in a MongoDB socket: + + - To connect to an available socket within ``10 SECONDS`` + - To read from an available socket within ``15 SECONDS`` + + .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin SocketSettings + :end-before: end SocketSettings + :language: java + :emphasize-lines: 3-5 + :dedent: + + For more information, see the `MongoClientSettings.Builder + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ + API documentation. diff --git a/source/connection/specify-connection-options/stable-api.txt b/source/connection/specify-connection-options/stable-api.txt index f536c5eff..ec9168631 100644 --- a/source/connection/specify-connection-options/stable-api.txt +++ b/source/connection/specify-connection-options/stable-api.txt @@ -122,14 +122,16 @@ described in the following table. - Description * - Strict - - | **Optional**. When set, if you call a command that is not part of the declared API version, the driver raises an exception. - | - | Default: **false** - - * - DeprecationErrors - - | **Optional**. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception. - | - | Default: **false** + - **Optional**. When set, if you call a command that is not part of the + declared API version, the driver raises an exception. + + Default: **false** + + * - DeprecationErrors + - **Optional**. When set, if you call a command that is deprecated in the + declared API version, the driver raises an exception. + + Default: **false** The following example shows how you can set the two options on an instance of ``ServerApi`` by chaining methods on the ``ServerApi.Builder``: From c3abb134bda84d430ee37ab7410f19c1392c78a4 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 18 Mar 2025 02:26:20 -0400 Subject: [PATCH 18/31] mongo client settings --- source/connection/mongoclient.txt | 50 ++++- .../connection/specify-connection-options.txt | 2 - .../cluster-settings.txt | 14 +- .../mongoclientsettings.txt | 200 ------------------ .../network-compression.txt | 44 ++-- .../server-settings.txt | 3 - .../code-snippets/MCSettings.java | 1 + source/logging-monitoring/logging.txt | 56 +++++ source/security/encrypt-fields.txt | 19 ++ 9 files changed, 165 insertions(+), 224 deletions(-) delete mode 100644 source/connection/specify-connection-options/mongoclientsettings.txt diff --git a/source/connection/mongoclient.txt b/source/connection/mongoclient.txt index c31023eac..b92e2ccff 100644 --- a/source/connection/mongoclient.txt +++ b/source/connection/mongoclient.txt @@ -32,9 +32,51 @@ MongoClient ----------- You can connect to and communicate with MongoDB using the ``MongoClient`` -class. +class. To create a `MongoClientSettings +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ object, use the ``MongoClientSettings.builder()`` method and chain methods to specify your +settings. After chaining them, use the ``build()`` method to create the +``MongoClientSettings`` object. -Use the ``MongoClients.create()`` method to construct a ``MongoClient``. +To learn about the different settings you can use to control the behavior of your ``MongoClient``, see the :ref:`Specify MongoClient Settings ` guide. + +Example +~~~~~~~ + +This example demonstrates specifying a ``ConnectionString``: + +.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin ConnectionString + :end-before: end ConnectionString + :language: java + :emphasize-lines: 3 + :dedent: + +.. note:: Chain Order + + Some options in the settings map to a connection string option. + If you specify the same options in your settings and connection + string, the order you chain them determines which option the driver + uses. The driver uses the **last** setting it reads. + + For example, this snippet contains settings with the following times + for the driver to connect to an available socket: + + - The connection string specifies within ``2 SECONDS`` + - The :ref:`socket settings ` specifies within + ``5 SECONDS`` + + .. code-block:: java + :emphasize-lines: 2,4 + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://:@:/?connectTimeoutMS=2000")) + .applyToSocketSettings(builder -> + builder.connectTimeout(5L, SECONDS)) + .build()); + + Since the driver reads the socket settings options last, the driver + expects to connect to an available socket within ``5 SECONDS`` before + timing out. .. important:: Reuse Your Client @@ -44,10 +86,6 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``. All resource usage limits, such as max connections, apply to individual ``MongoClient`` instances. -To learn about the different settings you can use to control the -behavior of your ``MongoClient``, see the -:ref:`Specify MongoClient Settings ` guide. - .. tip:: Always call ``MongoClient.close()`` to clean up resources when an diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 776924fb3..7d25f26c5 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -6,8 +6,6 @@ Specify Connection Options .. toctree:: - MongoClient Settings - Stable API Connection Pools Cluster Settings diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 7b023598e..1dfe84fc4 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -86,6 +86,18 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: your :ref:`connection URI ` to use this option. **Default**: ``mongodb`` + + This example connects the driver directly to a server, + regardless of the type of MongoDB cluster it's a part of: + + .. code-block:: java + + ConnectionString connectionString = "mongodb://:/?directConnection=true" + MongoClient mongoClient = MongoClients.create(connectionString) + + For more information about these parameters, see the `ConnectionString + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ + API documentation. .. tab:: MongoClientSettings :tabid: MongoClient @@ -163,7 +175,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: Throws an exception if you are not using the SRV connection protocol. - This example specifies for the driver to connect directly to a server, + This example connects the driver directly to a server, regardless of the type of MongoDB cluster it's a part of: .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java diff --git a/source/connection/specify-connection-options/mongoclientsettings.txt b/source/connection/specify-connection-options/mongoclientsettings.txt deleted file mode 100644 index ec4bba754..000000000 --- a/source/connection/specify-connection-options/mongoclientsettings.txt +++ /dev/null @@ -1,200 +0,0 @@ -.. _mongoclientsettings: -.. _specify-mongoclient-settings: - -============================ -Specify MongoClient Settings -============================ - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: java sync, customize, connection, code example - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -Overview --------- - -In this guide, you can learn about the different settings to control -the behavior of your ``MongoClient``. - -The following sections describe commonly used settings: - -- :ref:`MongoClient Settings ` -- :ref:`Server Settings ` - -.. _mcs-settings: - -MongoClient Settings --------------------- - -You can control the behavior of your ``MongoClient`` by creating and passing -in a `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ -object to the `MongoClients.create() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html#create(com.mongodb.MongoClientSettings)>`__ -method. - -To create a ``MongoClientSettings`` object, use the -``MongoClientSettings.builder()`` method and chain methods to specify your -settings. After chaining them, use the ``build()`` method to create the -``MongoClientSettings`` object. - -The following table describes the methods you can chain to modify your -connection behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``addCommandListener()`` - - Adds a listener for :ref:`command events `. - - * - ``applicationName()`` - - Sets the logical name of the application using the ``MongoClient``. - - * - ``applyConnectionString()`` - - Applies the settings from the given ``ConnectionString`` to the - builder. If you omit this method, the driver attempts to connect to - ``localhost``. - - * - ``applyToClusterSettings()`` - - Applies the ``ClusterSettings.Builder`` block and then sets the - :ref:`cluster settings `. - - * - ``applyToLoggerSettings()`` - - Applies the ``LoggerSettings.Builder`` block and then sets the - :ref:`logger settings `. - - * - ``applyToServerSettings()`` - - Applies the ``ServerSettings.Builder`` block and then sets the - :ref:`server settings `. - - * - ``autoEncryptionSettings()`` - - | Sets the :ref:`auto-encryption settings `. - | - | If you omit ``keyVaultClient`` or set - ``bypassAutomaticEncryption`` to false in your - ``AutoEncryptionSettings``, the driver creates a separate, - internal ``MongoClient``. - | - | The internal ``MongoClient`` configuration differs from the - parent ``MongoClient`` by setting the ``minPoolSize`` to 0 and - omitting the ``AutoEncryptionSettings``. - - * - ``codecRegistry()`` - - Sets the :ref:`codec registry `. - - * - ``commandListenerList()`` - - Sets the :ref:`command listeners `. - - * - ``compressorList()`` - - Sets the :ref:`compressors ` to use for compressing - messages to the server. - - * - ``credential()`` - - Sets the :ref:`credential `. - - * - ``serverApi()`` - - Sets the :ref:`server API ` to use when sending - commands to the server. - - * - ``transportSettings()`` - - Sets `TransportSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/TransportSettings.html>`__. - -.. _connection-string-example: - -Example -~~~~~~~ - -This example demonstrates specifying a ``ConnectionString``: - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin ConnectionString - :end-before: end ConnectionString - :language: java - :emphasize-lines: 3 - :dedent: - -.. note:: Chain Order - - Some options in the settings map to a connection string option. - If you specify the same options in your settings and connection - string, the order you chain them determines which option the driver - uses. The driver uses the **last** setting it reads. - - For example, this snippet contains settings with the following times - for the driver to connect to an available socket: - - - The connection string specifies within ``2 SECONDS`` - - The :ref:`socket settings ` specifies within - ``5 SECONDS`` - - .. code-block:: java - :emphasize-lines: 2,4 - - MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://:@:/?connectTimeoutMS=2000")) - .applyToSocketSettings(builder -> - builder.connectTimeout(5L, SECONDS)) - .build()); - - Since the driver reads the socket settings options last, the driver - expects to connect to an available socket within ``5 SECONDS`` before - timing out. - -.. tip:: Log Your Settings - - To log the ``MongoClient`` instance settings, - set the ``org.mongodb.driver.client`` named - logger to the ``INFO`` level. - - To learn more about logging with the {+driver-long+}, see the - :ref:`java-fundamentals-logging` guide. - - -.. _mcs-logger-settings: - -Logger Settings ---------------- - -Chain the `applyToLoggerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToLoggerSettings(com.mongodb.Block)>`__ -method to modify the logging behavior of the driver. - -The following table describes the methods you can chain to your -settings to modify the logging behavior: - -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Method - - Description - - * - ``maxDocumentLength()`` - - | Sets the maximum document length, in characters, of a single log - message. - | - | **Default**: ``1000`` - -Example -~~~~~~~ - -This example specifies that the maximum number of characters for a single log -message is set to ``5000`` characters. - -.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin LoggerSettings - :end-before: end LoggerSettings - :language: java - :emphasize-lines: 3-4 - :dedent: - - diff --git a/source/connection/specify-connection-options/network-compression.txt b/source/connection/specify-connection-options/network-compression.txt index 0a2213006..29e3fc10e 100644 --- a/source/connection/specify-connection-options/network-compression.txt +++ b/source/connection/specify-connection-options/network-compression.txt @@ -56,8 +56,7 @@ by specifying the algorithms in one of the following ways: - Use the ``compressors`` parameter in your connection string. - Chain the ``compressorList()`` method to the ``MongoClientSettings.builder()`` method. -This example shows how to specify the Snappy, Zstandard, and Zlib compression -algorithms. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` +Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the corresponding syntax: .. tabs:: @@ -65,11 +64,6 @@ tab to see the corresponding syntax: .. tab:: Connection String :tabid: uri - .. literalinclude:: /includes/connect/NetworkCompression.java - :start-after: start-specify-connection-string - :end-before: end-specify-connection-string - :language: java - Include the following parameters in your connection string to enable compression: .. list-table:: @@ -98,14 +92,40 @@ tab to see the corresponding syntax: values compressing slower (but resulting in smaller requests). **Default**: ``null`` + + The following specifies the order in which the driver will attempt to + compress requests before they are sent: + + .. literalinclude:: /includes/connect/NetworkCompression.java + :start-after: start-specify-connection-string + :end-before: end-specify-connection-string + :language: java + + For more information about these parameters, see the `ConnectionString + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ + API documentation. .. tab:: MongoClientSettings - :tabid: mongoclientsettings + :tabid: mongoclientsettings + + Chain the following methods to your ``MongoClientSettings`` constructor to modify the driver's compression behavior: + + .. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``compressorList()`` + - Sets the compressors to use for compressing messages to the server. + + .. literalinclude:: /includes/connect/NetworkCompression.java + :start-after: start-specify-client-settings + :end-before: end-specify-client-settings + :language: java - .. literalinclude:: /includes/connect/NetworkCompression.java - :start-after: start-specify-client-settings - :end-before: end-specify-client-settings - :language: java + For more information, see the `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ API documentation. .. _java-compression-dependencies: diff --git a/source/connection/specify-connection-options/server-settings.txt b/source/connection/specify-connection-options/server-settings.txt index baa6d5c3d..f4e63548b 100644 --- a/source/connection/specify-connection-options/server-settings.txt +++ b/source/connection/specify-connection-options/server-settings.txt @@ -99,9 +99,6 @@ Configuring Server Settings * - ``addServerMonitorListener()`` - Adds a listener for server monitor-related events. - * - ``applyConnectionString()`` - - Uses the settings from a ``ConnectionString`` object. - * - ``applySettings()`` - Uses the server settings specified in a ``ServerSettings`` object. diff --git a/source/includes/fundamentals/code-snippets/MCSettings.java b/source/includes/fundamentals/code-snippets/MCSettings.java index 2b020e7f3..863e5da1b 100644 --- a/source/includes/fundamentals/code-snippets/MCSettings.java +++ b/source/includes/fundamentals/code-snippets/MCSettings.java @@ -141,6 +141,7 @@ private static void createLoggerSettings() { ////begin LoggerSettings MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder().applyConnectionString(new ConnectionString("")) + .applicationName("") .applyToLoggerSettings(builder -> builder.maxDocumentLength(5_000)) .build()); diff --git a/source/logging-monitoring/logging.txt b/source/logging-monitoring/logging.txt index 3bd5bc7af..ed82a95b8 100644 --- a/source/logging-monitoring/logging.txt +++ b/source/logging-monitoring/logging.txt @@ -461,3 +461,59 @@ project. For more information about configuring Log4j2, see the `official Log4J2 configuration guide `__. + +.. _mcs-logger-settings: + +Connection Settings +------------------- + +You can apply logging settings to your ``MongoClient`` instance using the `applyToLoggerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToLoggerSettings(com.mongodb.Block)>`__ +and `applicationName() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applicationName(java.lang.String)>`__ methods. + +The following table describes the methods you can chain to your +logger settings to modify the logging behavior: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Method + - Description + + * - ``maxDocumentLength()`` + - Sets the maximum document length, in characters, of a single log message. + + **Default**: ``1000`` + +Example +~~~~~~~ + +This example names the application sending requests and specifies that the maximum number of characters for a single log message is set to ``5000`` characters. + +.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java + :start-after: begin LoggerSettings + :end-before: end LoggerSettings + :language: java + :emphasize-lines: 3-4 + :dedent: + +You should see output that resembles the following: + +.. code-block:: none + :copyable: false + + 01:20:38.782 [main] INFO org.mongodb.driver.client -- MongoClient with + metadata {"application": {"name": ""}, ..., + loggerSettings=LoggerSettings{maxDocumentLength=5000}, ... timeoutMS=null} + ... + 01:20:41.022 [main] DEBUG org.mongodb.driver.protocol.command -- Command + "listDatabases" succeeded ... Command reply: {"databases": [...], ...} + 01:20:41.024 [main] DEBUG org.mongodb.driver.connection -- Connection checked in: address=
, driver-generated ID=6 + myDb + sample_airbnb + sample_analytics + ... + +For more information, see the `MongoClientSettings.Builder +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +API documentation. \ No newline at end of file diff --git a/source/security/encrypt-fields.txt b/source/security/encrypt-fields.txt index 2419c2178..8cd36addc 100644 --- a/source/security/encrypt-fields.txt +++ b/source/security/encrypt-fields.txt @@ -26,3 +26,22 @@ :tabid: gradle-dependency .. include:: /includes/fundamentals/code-snippets/crypt-gradle-versioned.rst + +Connection Settings +------------------- + +You can apply encryption settings when creating a ``MongoClient`` instance by +passing an `AutoEncryptionSettings +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/AutoEncryptionSettings.html>`__ +object to the `autoEncryptionSettings() +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#autoEncryptionSettings(com.mongodb.AutoEncryptionSettings)>`__ +method. + +.. TODO: Add example + +.. note:: + + If you omit ``keyVaultClient`` or set ``bypassAutomaticEncryption`` to false + in your ``AutoEncryptionSettings``, the driver creates a separate, internal + ``MongoClient``. The internal ``MongoClient`` configuration differs from the + parent ``MongoClient`` by setting the ``minPoolSize`` to 0 and omitting the ``AutoEncryptionSettings``. \ No newline at end of file From 8a6817ea62967b4e7204345b0e767528b08502d2 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 18 Mar 2025 09:57:41 -0400 Subject: [PATCH 19/31] index updates --- snooty.toml | 1 + .../connection/specify-connection-options.txt | 25 +++++++-- .../cluster-settings.txt | 44 ++++++++-------- .../configure-crud.txt | 47 ++++++++--------- .../network-compression.txt | 14 ++--- .../server-settings.txt | 16 +++--- .../socket-settings.txt | 52 ++++++++++--------- .../connect/logging-monitoring-pages.rst | 3 ++ source/logging-monitoring.txt | 12 ++++- 9 files changed, 127 insertions(+), 87 deletions(-) create mode 100644 source/includes/connect/logging-monitoring-pages.rst diff --git a/snooty.toml b/snooty.toml index f4ed42363..add7ff2b1 100644 --- a/snooty.toml +++ b/snooty.toml @@ -14,6 +14,7 @@ toc_landing_pages = [ "/builders", "/data-formats", "/references", + "/logging-monitoring", "/api-documentation", "/security", "/security/auth" diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 7d25f26c5..ab8557aa5 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -9,11 +9,12 @@ Specify Connection Options Stable API Connection Pools Cluster Settings + Server Settings + Socket Settings Configure Client-level CRUD Settings Network Compression JNDI Datasource - AWS Lambda - Connection Security Settings + AWS Lambda `, which includes the following: + +.. include:: /includes/security/security-pages.rst + +Logging and Monitoring +---------------------- + +You can learn how to using logging and monitoring with the {+driver-short+} in +the :ref:`Logging and Monitoring section `, which +includes the following: + +.. include:: /includes/security/logging-monitoring-pages.rst \ No newline at end of file diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 1dfe84fc4..561c7289f 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -37,45 +37,45 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. list-table:: :header-rows: 1 - :widths: 20,20,60 + :widths: 25,20,60 * - Option Name - Type - Description - * - **serverSelectionTimeoutMS** + * - ``serverSelectionTimeoutMS`` - integer - Specifies the maximum amount of time, in milliseconds, the driver will wait for server selection to succeed before throwing an exception. - **Default**: ``30000`` (30 seconds) + *Default*: ``30000`` (30 seconds) - * - **localThresholdMS** + * - ``localThresholdMS`` - integer - When communicating with multiple instances of MongoDB in a replica set, the driver will only send requests to a server whose response time is less than or equal to the server with the fastest response time plus the local threshold, in milliseconds. - **Default**: ``15`` - * - **replicaSet** + *Default*: ``15`` + * - ``replicaSet`` - string - Specifies that the :ref:`connection string ` provided includes multiple hosts. When specified, the driver attempts to find all members of that set. - **Default**: ``null`` + *Default*: ``null`` - * - **directConnection** + * - ``directConnection`` - boolean - Specifies that the driver must connect to the host directly. This maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your ``MongoClientSettings``. - **Default**: ``false`` + *Default*: ``false`` - * - **srvServiceName** + * - ``srvServiceName`` - string - Specifies the service name of the `SRV resource records `__ the driver retrieves to @@ -85,7 +85,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: ` in your :ref:`connection URI ` to use this option. - **Default**: ``mongodb`` + *Default*: ``mongodb`` This example connects the driver directly to a server, regardless of the type of MongoDB cluster it's a part of: @@ -132,9 +132,9 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - ``localThreshold()`` - Sets the amount of time that a server’s round trip can take and - still be eligible for server selection. + still be eligible for server selection. - **Default**: ``15 milliseconds`` + *Default*: ``15 milliseconds`` * - ``mode()`` - Sets how to connect to a MongoDB deployment. @@ -149,7 +149,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: - Sets the maximum time to select a primary node before throwing a timeout exception. - **Default**: ``30 seconds`` + *Default*: ``30 seconds`` * - ``serverSelector()`` - Adds a server selector to apply before server selection. @@ -170,8 +170,8 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - ``srvMaxHosts()`` - Sets the maximum number of hosts the driver can connect to when - using the DNS seedlist (SRV) connection protocol, identified by - the ``mongodb+srv`` connection string prefix. + using the DNS seedlist (SRV) connection protocol, identified by + the ``mongodb+srv`` connection string prefix. Throws an exception if you are not using the SRV connection protocol. @@ -187,10 +187,12 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. tip:: - This is analogous to the ``directConnection`` parameter you can specify - in your connection URI. See :ref:`` for more - information. + This is analogous to the ``directConnection`` parameter you can specify + in your connection URI. See :ref:`` for more + information. - For more information, see the `MongoClientSettings.Builder + For more information about the chained methods, see the `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ - API documentation. \ No newline at end of file + API documentation. + + \ No newline at end of file diff --git a/source/connection/specify-connection-options/configure-crud.txt b/source/connection/specify-connection-options/configure-crud.txt index d424bb1f0..594597946 100644 --- a/source/connection/specify-connection-options/configure-crud.txt +++ b/source/connection/specify-connection-options/configure-crud.txt @@ -44,27 +44,27 @@ string ` or by passing a ``MongoClientSettings`` object to the .. list-table:: :header-rows: 1 - :widths: 20,20,60 + :widths: 25,20,60 * - Option Name - Type - Description - * - **journal** + * - ``journal`` - boolean - Specifies that the driver must wait for the connected MongoDB instance to group commit to the journal file on disk for all writes. - **Default**: ``false`` + *Default*: ``false`` - * - **w** + * - ``w`` - string or integer - Specifies the write concern. For more information about values, see the server documentation for the :manual:`w option `. - **Default**: ``1`` + *Default*: ``1`` - * - **wtimeoutMS** + * - ``wtimeoutMS`` - integer - Specifies a time limit, in milliseconds, for the write concern. For more information, see the server documentation for the @@ -72,26 +72,26 @@ string ` or by passing a ``MongoClientSettings`` object to the `. A value of ``0`` instructs the driver to never time out write operations. - **Default**: ``0`` + *Default*: ``0`` - * - **readPreference** + * - ``readPreference`` - string - Specifies the read preference. For more information about values, see the server documentation for the :manual:`readPreference option `. - **Default**: ``primary`` + *Default*: ``primary`` - * - **readPreferenceTags** + * - ``readPreferenceTags`` - string - Specifies the read preference tags. For more information about values, see the server documentation for the :manual:`readPreferenceTags option `. - **Default**: ``null`` + *Default*: ``null`` - * - **maxStalenessSeconds** + * - ``maxStalenessSeconds`` - integer - Specifies, in seconds, how stale a secondary can be before the driver stops communicating with that secondary. The minimum value is either @@ -102,30 +102,30 @@ string ` or by passing a ``MongoClientSettings`` object to the providing a parameter or explicitly specifying ``-1`` indicates that there must be no staleness check for secondaries. - **Default**: ``-1`` + *Default*: ``-1`` - * - **uuidRepresentation** + * - ``uuidRepresentation`` - string - Specifies the UUID representation to use for read and write operations. For more information, see the driver documentation for the `MongoClientSettings.getUuidRepresentation() method <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__. - **Default**: ``unspecified`` + *Default*: ``unspecified`` - * - **retryWrites** + * - ``retryWrites`` - boolean - Specifies that the driver must retry supported write operations if they are unable to complete due to a network error. - **Default**: ``true`` + *Default*: ``true`` - * - **retryReads** + * - ``retryReads`` - boolean - Specifies that the driver must retry supported read operations if they are unable to complete due to a network error. - **Default**: ``true`` + *Default*: ``true`` The following example sets the read preference to read from the nearest replica set member: @@ -145,7 +145,6 @@ string ` or by passing a ``MongoClientSettings`` object to the Chain the following methods to your ``MongoClientSettings`` constructor to modify the driver's read/write behavior: .. list-table:: - :header-rows: 1 :stub-columns: 1 :widths: 40 60 @@ -157,19 +156,19 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``readPreference()`` - Sets the :manual:`read preference ` - **Default**: ``primary`` + *Default*: ``primary`` * - ``retryReads()`` - Whether the driver performs :manual:`retry reads ` if a network error occurs. - **Default**: ``true`` + *Default*: ``true`` * - ``retryWrites()`` - Whether the driver performs :manual:`retry writes ` if a network error occurs. - **Default**: ``true`` + *Default*: ``true`` * - ``uuidRepresentation()`` - Sets the UUID representation to use when encoding instances of UUID @@ -178,7 +177,7 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``writeConcern()`` - Sets the :manual:`write concern `. - **Default**: ``WriteConcern#ACKNOWLEDGED``. + *Default*: ``WriteConcern#ACKNOWLEDGED``. | For more information about the default value, see :manual:`Implicit Default Write Concern `. The following example sets the read preference to read from the nearest diff --git a/source/connection/specify-connection-options/network-compression.txt b/source/connection/specify-connection-options/network-compression.txt index 29e3fc10e..dd50f656a 100644 --- a/source/connection/specify-connection-options/network-compression.txt +++ b/source/connection/specify-connection-options/network-compression.txt @@ -68,22 +68,22 @@ tab to see the corresponding syntax: .. list-table:: :header-rows: 1 - :widths: 20,20,60 + :widths: 25,20,60 * - Option Name - Type - Description - * - **compressors** + * - ``compressors`` - string - Specifies one or more compression algorithms that the driver will attempt to use to compress requests sent to the connected MongoDB instance. Possible values include: ``zlib``, ``snappy``, and ``zstd``. - **Default**: ``null`` + *Default*: ``null`` - * - **zlibCompressionLevel** + * - ``zlibCompressionLevel`` - integer - Specifies the degree of compression that `Zlib `__ uses to decrease the size of requests to the connected MongoDB @@ -91,7 +91,7 @@ tab to see the corresponding syntax: compressing faster (but resulting in larger requests) and larger values compressing slower (but resulting in smaller requests). - **Default**: ``null`` + *Default*: ``null`` The following specifies the order in which the driver will attempt to compress requests before they are sent: @@ -125,7 +125,9 @@ tab to see the corresponding syntax: :end-before: end-specify-client-settings :language: java - For more information, see the `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ API documentation. + For more information about the chained methods, see the `MongoClientSettings.Builder + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ + API documentation. .. _java-compression-dependencies: diff --git a/source/connection/specify-connection-options/server-settings.txt b/source/connection/specify-connection-options/server-settings.txt index f4e63548b..e60c40120 100644 --- a/source/connection/specify-connection-options/server-settings.txt +++ b/source/connection/specify-connection-options/server-settings.txt @@ -33,7 +33,7 @@ Configuring Server Settings .. list-table:: :header-rows: 1 - :widths: 20,20,60 + :widths: 25,20,60 * - Option Name - Type @@ -119,12 +119,14 @@ Configuring Server Settings - The cluster monitor to attempt reaching a server every ``15 SECONDS`` .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin ServerSettings - :end-before: end ServerSettings - :language: java - :emphasize-lines: 3-5 - :dedent: + :start-after: begin ServerSettings + :end-before: end ServerSettings + :language: java + :emphasize-lines: 3-5 + :dedent: - For more information, see the `MongoClientSettings.Builder + For more information about the chained methods, see the `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ API documentation. + + diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index 49183cc19..c80cb0edb 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -1,8 +1,8 @@ .. _mcs-socket-settings: -================ +=============== Socket Settings -================ +=============== .. contents:: On this page :local: @@ -31,29 +31,29 @@ string ` or by passing a ``MongoClientSettings`` object to the .. list-table:: :header-rows: 1 - :widths: 20,20,60 + :widths: 25,20,60 * - Option Name - Type - Description - * - **connectTimeoutMS** + * - ``connectTimeoutMS`` - integer - Specifies the maximum amount of time, in milliseconds, the Java driver waits for a connection to open before timing out. A value of ``0`` instructs the driver to never time out while waiting for a connection to open. - **Default**: ``10000`` (10 seconds) + *Default*: ``10000`` (10 seconds) - * - **socketTimeoutMS** + * - ``socketTimeoutMS`` - integer - Specifies the maximum amount of time, in milliseconds, the Java driver will wait to send or receive a request before timing out. A value of ``0`` instructs the driver to never time out while waiting to send or receive a request. - **Default**: ``0`` + *Default*: ``0`` This example specifies that the driver will time out after 15 seconds of waiting for a connection to open: @@ -91,26 +91,26 @@ string ` or by passing a ``MongoClientSettings`` object to the - Uses the socket settings specified in a ``SocketSettings`` object. * - ``connectTimeout()`` - - | Sets the maximum time to connect to an available socket before throwing + - Sets the maximum time to connect to an available socket before throwing a timeout exception. - | - | **Default**: ``10 seconds`` + + *Default*: ``10 seconds`` * - ``readTimeout()`` - - | Sets the maximum time to read from an available socket before throwing a + - Sets the maximum time to read from an available socket before throwing a timeout exception. - | - | **Default**: ``0``, which indicates no timeout + + *Default*: ``0``, which indicates no timeout * - ``receiveBufferSize()`` - - | Sets the socket's buffer size when receiving. - | - | **Default**: The operating system default + - Sets the socket's buffer size when receiving. + + *Default*: The operating system default * - ``sendBufferSize()`` - - | Sets the socket's buffer size when sending. - | - | **Default**: The operating system default + - Sets the socket's buffer size when sending. + + *Default*: The operating system default .. note:: Connect to MongoDB by using a SOCKS5 Proxy @@ -127,12 +127,14 @@ string ` or by passing a ``MongoClientSettings`` object to the - To read from an available socket within ``15 SECONDS`` .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java - :start-after: begin SocketSettings - :end-before: end SocketSettings - :language: java - :emphasize-lines: 3-5 - :dedent: + :start-after: begin SocketSettings + :end-before: end SocketSettings + :language: java + :emphasize-lines: 3-5 + :dedent: - For more information, see the `MongoClientSettings.Builder + For more information about the chained methods, see the `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ API documentation. + + diff --git a/source/includes/connect/logging-monitoring-pages.rst b/source/includes/connect/logging-monitoring-pages.rst new file mode 100644 index 000000000..188343270 --- /dev/null +++ b/source/includes/connect/logging-monitoring-pages.rst @@ -0,0 +1,3 @@ +- :ref:`Logging ` +- :ref:`Monitoring ` +- :ref:`Change Streams ` \ No newline at end of file diff --git a/source/logging-monitoring.txt b/source/logging-monitoring.txt index af9de0f1b..7e6983d57 100644 --- a/source/logging-monitoring.txt +++ b/source/logging-monitoring.txt @@ -1,3 +1,5 @@ +.. _java-logging-monitoring: + ====================== Logging and Monitoring ====================== @@ -11,4 +13,12 @@ Logging and Monitoring Logging Monitoring - Change Streams \ No newline at end of file + Change Streams + +Overview +-------- + +Learn how to set up logging and monitoring for your application in +the following sections: + +.. include:: /includes/security/logging-monitoring-pages.rst \ No newline at end of file From 226ef506fea9f8dd9d6434d4c79ab737c371168b Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 18 Mar 2025 10:30:09 -0400 Subject: [PATCH 20/31] formatting --- .../connection/specify-connection-options.txt | 14 ++++++++++++-- .../connection-pools.txt | 18 +++++++++--------- .../server-settings.txt | 16 ++++++++-------- .../socket-settings.txt | 4 ++-- .../logging-monitoring-pages.rst | 0 source/logging-monitoring.txt | 2 +- 6 files changed, 32 insertions(+), 22 deletions(-) rename source/includes/{connect => logging-monitoring}/logging-monitoring-pages.rst (100%) diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index ab8557aa5..0dbfa0221 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -14,7 +14,7 @@ Specify Connection Options Configure Client-level CRUD Settings Network Compression JNDI Datasource - AWS Lambda .. facet:: :name: genre @@ -30,6 +30,16 @@ This section describes the MongoDB connection and authentication options available in the {+driver-short+}. You can specify connection options in the following ways: +- :ref:`Stable API ` +- :ref:`Connection Pools ` +- :ref:`Cluster Settings ` +- :ref:`Server Settings ` +- :ref:`Socket Settings ` +- :ref:`Configure Client-level CRUD Settings ` +- :ref:`Network Compression ` +- :ref:`JNDI Datasource ` +- `AWS Lambda `__ + Security and Authentication --------------------------- @@ -46,4 +56,4 @@ You can learn how to using logging and monitoring with the {+driver-short+} in the :ref:`Logging and Monitoring section `, which includes the following: -.. include:: /includes/security/logging-monitoring-pages.rst \ No newline at end of file +.. include:: /includes/logging-monitoring/logging-monitoring-pages.rst \ No newline at end of file diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index a7166694e..08d4a6ab8 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -168,21 +168,21 @@ see the corresponding syntax: closed. * - ``maxSize()`` - - | Sets the maximum number of connections associated with a connection + - Sets the maximum number of connections associated with a connection pool. - | - | **Default**: ``100`` + + *Default*: ``100`` * - ``maxWaitTime()`` - - | Sets the maximum time to wait for an available connection. - | - | **Default**: ``2 minutes`` + - Sets the maximum time to wait for an available connection. + + *Default*: ``2 minutes`` * - ``minSize()`` - - | Sets the minimum number of connections associated with a connection + - Sets the minimum number of connections associated with a connection pool. - | - | **Default**: ``0`` + + *Default*: ``0`` .. note:: diff --git a/source/connection/specify-connection-options/server-settings.txt b/source/connection/specify-connection-options/server-settings.txt index e60c40120..5a8e76929 100644 --- a/source/connection/specify-connection-options/server-settings.txt +++ b/source/connection/specify-connection-options/server-settings.txt @@ -39,15 +39,15 @@ Configuring Server Settings - Type - Description - * - **appName** + * - ``appName`` - string - Specifies the name of the application provided to MongoDB instances during the connection handshake. Can be used for server logs and profiling. - **Default**: ``null`` + *Default*: ``null`` - * - **serverMonitoringMode** + * - ``serverMonitoringMode`` - string - Specifies which server monitoring protocol the driver uses. When set to ``auto``, the monitoring mode is determined by the environment in @@ -55,15 +55,15 @@ Configuring Server Settings function-as-a-service (FaaS) environments and ``stream`` mode in other environments. - **Default**: ``auto`` + *Default*: ``auto`` - * - **heartbeatFrequencyMS** + * - ``heartbeatFrequencyMS`` - integer - Specifies the frequency, in milliseconds that the driver will wait between attempts to determine the current state of each server in the cluster. - **Default**: ``10000`` (10 seconds) + *Default*: ``10000`` (10 seconds) This example specifies that the cluster monitor will attempt to reach a @@ -105,12 +105,12 @@ Configuring Server Settings * - ``heartbeatFrequency()`` - Sets the interval for a cluster monitor to attempt reaching a server. - **Default**: ``10 seconds`` + *Default*: ``10 seconds`` * - ``minHeartbeatFrequency()`` - Sets the minimum interval for server monitoring checks. - **Default**: ``500 milliseconds`` + *Default*: ``500 milliseconds`` This example specifies the following driver behavior in a MongoDB deployment: diff --git a/source/connection/specify-connection-options/socket-settings.txt b/source/connection/specify-connection-options/socket-settings.txt index c80cb0edb..77f0ee5af 100644 --- a/source/connection/specify-connection-options/socket-settings.txt +++ b/source/connection/specify-connection-options/socket-settings.txt @@ -92,13 +92,13 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``connectTimeout()`` - Sets the maximum time to connect to an available socket before throwing - a timeout exception. + a timeout exception. *Default*: ``10 seconds`` * - ``readTimeout()`` - Sets the maximum time to read from an available socket before throwing a - timeout exception. + timeout exception. *Default*: ``0``, which indicates no timeout diff --git a/source/includes/connect/logging-monitoring-pages.rst b/source/includes/logging-monitoring/logging-monitoring-pages.rst similarity index 100% rename from source/includes/connect/logging-monitoring-pages.rst rename to source/includes/logging-monitoring/logging-monitoring-pages.rst diff --git a/source/logging-monitoring.txt b/source/logging-monitoring.txt index 7e6983d57..5241c7144 100644 --- a/source/logging-monitoring.txt +++ b/source/logging-monitoring.txt @@ -21,4 +21,4 @@ Overview Learn how to set up logging and monitoring for your application in the following sections: -.. include:: /includes/security/logging-monitoring-pages.rst \ No newline at end of file +.. include:: /includes/logging-monitoring/logging-monitoring-pages.rst \ No newline at end of file From bfcc532bc29f9575fad9f7fea0b1dd672104c1b7 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 18 Mar 2025 10:55:54 -0400 Subject: [PATCH 21/31] landing page --- .../connection/specify-connection-options.txt | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 0dbfa0221..209b4ba09 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -4,6 +4,19 @@ Specify Connection Options ========================== +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, Atlas, code example + .. toctree:: Stable API @@ -16,13 +29,6 @@ Specify Connection Options JNDI Datasource AWS Lambda -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: connection string, URI, Atlas, code example - Overview -------- From 46eeead7b4c7b869c3e7c028bb18eaf07a7ffbdf Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 18 Mar 2025 11:28:30 -0400 Subject: [PATCH 22/31] crud settings --- source/crud.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/crud.txt b/source/crud.txt index e11c55c8b..0c9ffa4af 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -16,6 +16,7 @@ CRUD Operations Transactions Collations Large File Storage with GridFS + Configure Custom CRUD Settings CRUD (Create, Read, Update, Delete) operations enable you to work with data stored in MongoDB. From df0fa37360f4d11716a8dff25d8b34e4796b2891 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 18 Mar 2025 11:43:00 -0400 Subject: [PATCH 23/31] move integrations --- source/index.txt | 1 + source/{references => }/integrations.txt | 0 2 files changed, 1 insertion(+) rename source/{references => }/integrations.txt (100%) diff --git a/source/index.txt b/source/index.txt index b78ebf057..b266d7c95 100644 --- a/source/index.txt +++ b/source/index.txt @@ -31,6 +31,7 @@ MongoDB Java Driver Atlas Vector Search Logging and Monitoring Security + Third-Party Integrations Reference API Documentation Issues & Help diff --git a/source/references/integrations.txt b/source/integrations.txt similarity index 100% rename from source/references/integrations.txt rename to source/integrations.txt From adfb29d8c6642c9176d974f9b3e400a81bfd5ce0 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 19 Mar 2025 11:35:18 -0400 Subject: [PATCH 24/31] aggregation and modify --- config/redirects | 6 +- source/aggregation.txt | 1 + source/aggregation/aggregation-examples.txt | 230 +++++++++++++++++ source/crud.txt | 1 + source/crud/replace-documents.txt | 123 ++++++++++ source/crud/update-documents.txt | 152 +++++++++++- source/crud/update-documents/modify.txt | 258 -------------------- 7 files changed, 508 insertions(+), 263 deletions(-) create mode 100644 source/aggregation/aggregation-examples.txt create mode 100644 source/crud/replace-documents.txt delete mode 100644 source/crud/update-documents/modify.txt diff --git a/config/redirects b/config/redirects index f7c6750f9..20aa70b26 100644 --- a/config/redirects +++ b/config/redirects @@ -25,10 +25,10 @@ raw: ${prefix}/master -> ${base}/upcoming/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query-documents/project/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query-documents/geo/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/query-documents/text/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/update-documents/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/update-documents/insert/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/insert/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/insert/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/update-documents/delete/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/update-documents/modify/ +[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/update-documents/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/update-documents/embedded-arrays/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/update-documents/upsert/ [v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/bulk/ diff --git a/source/aggregation.txt b/source/aggregation.txt index 22bf262cb..83f35ba40 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -21,6 +21,7 @@ Aggregation :caption: Aggregation Aggregation Expressions + Aggregation Examples Overview -------- diff --git a/source/aggregation/aggregation-examples.txt b/source/aggregation/aggregation-examples.txt new file mode 100644 index 000000000..576c9d7e5 --- /dev/null +++ b/source/aggregation/aggregation-examples.txt @@ -0,0 +1,230 @@ +.. _java-aggregation-examples: + +==================== +Aggregation Examples +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, transform, computed + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +This page demonstrates how to use aggregation pipelines. + +Import Classes +~~~~~~~~~~~~~~ + +Create a new Java file called ``AggTour.java`` and include the following import statements: + +.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java + :language: java + :dedent: + :start-after: begin imports + :end-before: end imports + +Connect to a MongoDB Deployment ++++++++++++++++++++++++++++++++ + +.. code-block:: java + + public class AggTour { + + public static void main(String[] args) { + // Replace the uri string with your MongoDB deployment's connection string + String uri = ""; + + MongoClient mongoClient = MongoClients.create(uri); + MongoDatabase database = mongoClient.getDatabase("aggregation"); + MongoCollection collection = database.getCollection("restaurants"); + + // Paste the aggregation code here + } + } + +.. tip:: + + To learn more about connecting to MongoDB, see the :ref:`Connection + Guide `. + +Insert Sample Data +++++++++++++++++++ + +.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java + :language: java + :dedent: + :start-after: begin insert + :end-before: end insert + +Basic Aggregation Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To perform an aggregation, pass a list of aggregation stages to the +``MongoCollection.aggregate()`` method. + +The Java driver provides the +`Aggregates <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html>`__ +helper class that contains builders for aggregation stages. + +In the following example, the aggregation pipeline: + +- Uses a :manual:`$match ` stage to filter for documents whose + ``categories`` array field contains the element ``Bakery``. The example uses + ``Aggregates.match`` to build the ``$match`` stage. + +- Uses a :manual:`$group ` stage to group the matching documents by the ``stars`` + field, accumulating a count of documents for each distinct value of ``stars``. + +.. note:: + + You can build the expressions used in this example using the :ref:`aggregation builders `. + +.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java + :language: java + :dedent: + :start-after: begin aggregation basic + :end-before: end aggregation basic + +The preceding aggregation produces the following results: + +.. code-block:: none + :copyable: false + + {"_id": 4, "count": 2} + {"_id": 5, "count": 1} + +For more information about the methods and classes mentioned in this section, +see the following API Documentation: + +- `MongoCollection.aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__ +- `Aggregates.match <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#match(org.bson.conversions.Bson)>`__ + +Explain Aggregation Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To view information about how MongoDB executes your operation, use the +``explain()`` method of the ``AggregateIterable`` class. The ``explain()`` +method returns **execution plans** and performance statistics. An execution +plan is a potential way MongoDB can complete an operation. +The ``explain()`` method provides both the winning plan, which is the plan MongoDB +executed, and any rejected plans. + +.. tip:: + + To learn more about query plans and execution statistics, see + :manual:`Explain Results ` in the Server manual. + +.. include:: /includes/fundamentals/explain-verbosity.rst + +The following example prints the JSON representation of the +winning plans for any aggregation stages that produce execution plans: + +.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java + :language: java + :dedent: + :start-after: begin aggregation explain + :end-before: end aggregation explain + +The example produces the following output as the ``$group`` stage +is the only stage that produces an execution plan: + +.. code-block:: none + :copyable: false + + { + "stage": "GROUP", + "planNodeId": 2, + "inputStage": { + "stage": "COLLSCAN", + "planNodeId": 1, + "filter": { + "categories": { + "$eq": "Bakery" + } + }, + "direction": "forward" + } + } + +For more information about the topics mentioned in this section, see the +following resources: + +- :manual:`Explain Output ` Server Manual Entry +- :manual:`Query Plans ` Server Manual Entry +- `ExplainVerbosity <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ExplainVerbosity>`__ API Documentation +- `explain() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#explain()>`__ API Documentation +- `AggregateIterable <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html>`__ API Documentation + +Aggregation Expression Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} provides builders for accumulator expressions for use with +``$group``. You must declare all other expressions in JSON format or +compatible document format. + +.. tip:: + + The syntax in either of the following examples will define an :manual:`$arrayElemAt ` + expression. + + The ``$`` in front of "categories" tells MongoDB that this is a :manual:`field path `, + using the ``categories`` field from the input document. + + .. code-block:: java + :copyable: false + + new Document("$arrayElemAt", Arrays.asList("$categories", 0)) + + .. code-block:: java + :copyable: false + + Document.parse("{ $arrayElemAt: ['$categories', 0] }") + + Alternatively, you can construct expressions by using the Aggregation + Expression Operations API. To learn more, see + :ref:`java-aggregation-expression-operations`. + +In the following example, the aggregation pipeline uses a +``$project`` stage and various ``Projections`` to return the ``name`` +field and the calculated field ``firstCategory`` whose value is the +first element in the ``categories`` field. + +.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java + :language: java + :dedent: + :start-after: begin aggregation expression + :end-before: end aggregation expression + +The preceding aggregation produces the following results: + +.. code-block:: none + :copyable: false + + {"name": "456 Cookies Shop", "firstCategory": "Bakery"} + {"name": "Sun Bakery Trattoria", "firstCategory": "Pizza"} + {"name": "456 Steak Restaurant", "firstCategory": "Steak"} + {"name": "Blue Bagels Grill", "firstCategory": "Bagels"} + {"name": "XYZ Steak Buffet", "firstCategory": "Steak"} + {"name": "Hot Bakery Cafe", "firstCategory": "Bakery"} + {"name": "Green Feast Pizzeria", "firstCategory": "Pizza"} + {"name": "ZZZ Pasta Buffet", "firstCategory": "Pasta"} + {"name": "XYZ Coffee Bar", "firstCategory": "Coffee"} + {"name": "XYZ Bagels Restaurant", "firstCategory": "Bagels"} + +For more information about the methods and classes mentioned in this section, +see the following API Documentation: + +- `Accumulators <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Accumulators.html>`__ +- `$group <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#group(TExpression,java.util.List)>`__ +- `$project <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ +- `Projections <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html>`__ diff --git a/source/crud.txt b/source/crud.txt index 0c9ffa4af..a1f6eddd9 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -10,6 +10,7 @@ CRUD Operations Insert Documents Query Documents Update Documents + Replace Documents Delete Documents Bulk Operations Compound Operations diff --git a/source/crud/replace-documents.txt b/source/crud/replace-documents.txt new file mode 100644 index 000000000..9785a34c0 --- /dev/null +++ b/source/crud/replace-documents.txt @@ -0,0 +1,123 @@ +.. _java-replace-document: +.. _replace-operation: + +================= +Replace Documents +================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to replace documents in a MongoDB +collection. A replace operation specifies the fields and values to replace +a single document from your collection. + +Replace One Method +------------------ + +A replace operation substitutes one document from your collection. The +substitution occurs between a document your query filter matches and a +replacement document. + +The `replaceOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,TDocument)>`__ +method removes all the existing fields and values in the +matching document (except the ``_id`` field) and substitutes it with the +replacement document. + +You can call the ``replaceOne()`` method on a ``MongoCollection`` +instance as follows: + +.. code-block:: java + + collection.replaceOne(, ); + +Replace Operation Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``replaceOne()`` method has the following parameters: + +- ``query`` specifies a query filter with the criteria to match a + document to replace in your collection. +- ``replacement`` specifies fields and values of a new ``Document`` + object to replace the matched document. +- *(Optional)* ``replaceOptions`` specifies options that you can set to + customize how the driver performs the replace operation. To learn more + about this type, see the API documentation for `ReplaceOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__. + +Replace One Example +~~~~~~~~~~~~~~~~~~~ + +In this example, a paint store sells five different +colors of paint. The ``paint_inventory`` collection represents their +current inventory: + +.. code-block:: json + + { "_id": 1, "color": "red", "qty": 5 } + { "_id": 2, "color": "purple", "qty": 8 } + { "_id": 3, "color": "yellow", "qty": 0 } + { "_id": 4, "color": "green", "qty": 6 } + { "_id": 5, "color": "pink", "qty": 0 } + +The paint store realizes they must update their inventory again. What they +thought was 20 cans of pink paint is actually 25 cans of orange paint. + +To update the inventory, call the ``replaceOne()`` method specifying the +following: + +- A query filter that matches documents where the ``color`` is "pink" +- A replacement document where the ``color`` is "orange" and the ``qty`` is "25" + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin replaceOneExample + :end-before: end replaceOneExample + +The output of the preceding code resembles the following: + +.. code-block:: none + :copyable: false + + Matched document count: 1 + Modified document count: 1 + +The following shows the updated document: + +.. code-block:: json + :copyable: false + + { "_id": 5, "color": "orange", "qty": 25 } + +If multiple documents match the query filter specified in +the ``replaceOne()`` method, it replaces the first result. You can +specify a sort in a ``ReplaceOptions`` instance to apply an order to +matched documents before the server performs the replace operation, as +shown in the following code: + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin replaceoptions + :end-before: end replaceoptions + +If zero documents match the query filter in the replace operation, +``replaceOne()`` makes no changes to documents in the collection. See +our :ref:`upsert guide ` to +learn how to insert a new document instead of replacing one if no +documents match. + +.. important:: + + The ``replaceOne()`` method cannot make changes to a document that + violate unique index constraints on the collection. + For more information about constraints on unique indexes, + see :manual:`Unique Indexes ` in the + {+mdb-server+} manual. diff --git a/source/crud/update-documents.txt b/source/crud/update-documents.txt index cb55d9a4f..7a7e9916e 100644 --- a/source/crud/update-documents.txt +++ b/source/crud/update-documents.txt @@ -1,4 +1,7 @@ +.. _java-fundamentals-change-document: .. _java-write-operations: +.. _update-operation: +.. _java-fundamentals-update: ================ Update Documents @@ -10,10 +13,155 @@ Update Documents .. toctree:: :caption: Update Documents - Modify Update Array Elements Upsert -- :doc:`/crud/update-documents/modify` +Overview +-------- + +In this guide, you can learn how to update documents in a MongoDB +collection. Update operations specify the fields and values to change in one or more +documents. They apply changes specified in an update document to one or more +documents that match your query filter. + +To learn how to updated embedded arrays or to update or insert in a +single query, see the following pages: + - :doc:`/crud/update-documents/embedded-arrays` - :doc:`/crud/update-documents/upsert` + +Update operations can modify fields and values: + +- The `updateOne() + <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ + method changes the first document your query filter matches and the +- `updateMany() + <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ + method changes all the documents your query filter matches. + +You can call the ``updateOne()`` and ``updateMany()`` methods on a +``MongoCollection`` instance as follows: + +.. code-block:: java + + collection.updateOne(, ); + collection.updateMany(, ); + +Update Operation Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``updateOne()`` and ``updateMany()`` methods both have the following +parameters: + +- ``query`` specifies a query filter with the criteria to match + documents to update in your collection. +- ``update`` specifies the fields and values to modify in the matching + document or documents. The examples in this section use the + :ref:`updates-builders` to create the update document. +- *(Optional)* ``updateOptions`` specifies options that you can set to + customize how the driver performs the update operation. To learn more + about this type, see the API documentation for `UpdateOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__. + +You can create the ``updateDocument`` using an ``Updates`` builder as +follows: + +.. code-block:: java + + Bson update = Updates.operator(, ); + +To view a complete list of Updates builders and their usage, see `Updates +<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__ +in the API documentation. + +Examples +-------- + +In the following examples, a paint store sells five different +colors of paint. The ``paint_inventory`` collection represents their +current inventory: + +.. code-block:: json + + { "_id": 1, "color": "red", "qty": 5 } + { "_id": 2, "color": "purple", "qty": 8 } + { "_id": 3, "color": "yellow", "qty": 0 } + { "_id": 4, "color": "green", "qty": 6 } + { "_id": 5, "color": "pink", "qty": 0 } + +Update One Example +~~~~~~~~~~~~~~~~~~ + +The following example demonstrates how to change the value of the +``color`` field in the first matching document in which the value of +``qty`` is ``0``: + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin updateOneExample + :end-before: end updateOneExample + +If multiple documents match the query filter specified in +the ``updateOne()`` method, it updates the first result. You can +specify a sort in an ``UpdateOptions`` instance to apply an order to +matched documents before the server performs the update operation, as +shown in the following code: + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin updateoptions + :end-before: end updateoptions + +Update Many Example +~~~~~~~~~~~~~~~~~~~ + +The paint store receives a fresh shipment and needs to update their inventory. +The shipment contains 20 cans of each paint color. + +To update the inventory, call the ``updateMany()`` method specifying the +following: + +- Query filter that matches all the colors +- Update document that contains instructions to increment the ``qty`` + field by ``20`` + +.. literalinclude:: /includes/fundamentals/code-snippets/Update.java + :language: java + :dedent: + :start-after: begin updateManyExample + :end-before: end updateManyExample + +The output of the preceding code resembles the following: + +.. code-block:: none + :copyable: false + + Matched document count: 5 + Modified document count: 5 + +The following shows the updated documents in the ``paint_inventory`` collection: + +.. code-block:: json + :copyable: false + + { "_id": 1, "color": "red", "qty": 25 } + { "_id": 2, "color": "purple", "qty": 28 } + { "_id": 3, "color": "yellow", "qty": 20 } + { "_id": 4, "color": "green", "qty": 26 } + { "_id": 5, "color": "pink", "qty": 20 } + +If zero documents match the query filter in the update operation, +``updateMany()`` makes no changes to documents in the collection. See +our :ref:`upsert guide ` to +learn how to insert a new document instead of updating one if no +documents match. + +.. important:: + + The ``updateOne()`` and ``updateMany()`` methods cannot make changes + to a document that violate unique index constraints on the + collection. For more information about constraints on unique indexes, + see :manual:`Unique Indexes ` in the + {+mdb-server+} manual. \ No newline at end of file diff --git a/source/crud/update-documents/modify.txt b/source/crud/update-documents/modify.txt deleted file mode 100644 index 88e61f8ba..000000000 --- a/source/crud/update-documents/modify.txt +++ /dev/null @@ -1,258 +0,0 @@ -.. _java-fundamentals-change-document: - -================ -Modify Documents -================ - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn how to modify documents in a MongoDB -collection using two distinct operation types: - -- :ref:`Update ` -- :ref:`Replace ` - -Update operations specify the fields and values to change in one or more -documents. A replace operation specifies the fields and values to replace -a single document from your collection. - -In the following examples, a paint store sells five different -colors of paint. The ``paint_inventory`` collection represents their -current inventory: - -.. code-block:: json - - { "_id": 1, "color": "red", "qty": 5 } - { "_id": 2, "color": "purple", "qty": 8 } - { "_id": 3, "color": "yellow", "qty": 0 } - { "_id": 4, "color": "green", "qty": 6 } - { "_id": 5, "color": "pink", "qty": 0 } - -.. _update-operation: - -.. _java-fundamentals-update: - -Update ------- - -Update operations can modify fields and values. They apply changes -specified in an update document to one or more documents that match your -query filter. - -The `updateOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ -method changes the first document your query filter matches and the -`updateMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ -method changes all the documents your query filter matches. - -You can call the ``updateOne()`` and ``updateMany()`` methods on a -``MongoCollection`` instance as follows: - -.. code-block:: java - - collection.updateOne(, ); - collection.updateMany(, ); - -Update Operation Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``updateOne()`` and ``updateMany()`` methods both have the following -parameters: - -- ``query`` specifies a query filter with the criteria to match - documents to update in your collection. -- ``update`` specifies the fields and values to modify in the matching - document or documents. The examples in this section use the - :ref:`updates-builders` to create the update document. -- *(Optional)* ``updateOptions`` specifies options that you can set to - customize how the driver performs the update operation. To learn more - about this type, see the API documentation for `UpdateOptions - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__. - -You can create the ``updateDocument`` using an ``Updates`` builder as -follows: - -.. code-block:: java - - Bson update = Updates.operator(, ); - -To view a complete list of Updates builders and their usage, see `Updates -<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__ -in the API documentation. - -Update One Example -~~~~~~~~~~~~~~~~~~ - -The following example demonstrates how to change the value of the -``color`` field in the first matching document in which the value of -``qty`` is ``0``: - -.. literalinclude:: /includes/fundamentals/code-snippets/Update.java - :language: java - :dedent: - :start-after: begin updateOneExample - :end-before: end updateOneExample - -If multiple documents match the query filter specified in -the ``updateOne()`` method, it updates the first result. You can -specify a sort in an ``UpdateOptions`` instance to apply an order to -matched documents before the server performs the update operation, as -shown in the following code: - -.. literalinclude:: /includes/fundamentals/code-snippets/Update.java - :language: java - :dedent: - :start-after: begin updateoptions - :end-before: end updateoptions - -Update Many Example -~~~~~~~~~~~~~~~~~~~ - -The paint store receives a fresh shipment and needs to update their inventory. -The shipment contains 20 cans of each paint color. - -To update the inventory, call the ``updateMany()`` method specifying the -following: - -- Query filter that matches all the colors -- Update document that contains instructions to increment the ``qty`` - field by ``20`` - -.. literalinclude:: /includes/fundamentals/code-snippets/Update.java - :language: java - :dedent: - :start-after: begin updateManyExample - :end-before: end updateManyExample - -The output of the preceding code resembles the following: - -.. code-block:: none - :copyable: false - - Matched document count: 5 - Modified document count: 5 - -The following shows the updated documents in the ``paint_inventory`` collection: - -.. code-block:: json - :copyable: false - - { "_id": 1, "color": "red", "qty": 25 } - { "_id": 2, "color": "purple", "qty": 28 } - { "_id": 3, "color": "yellow", "qty": 20 } - { "_id": 4, "color": "green", "qty": 26 } - { "_id": 5, "color": "pink", "qty": 20 } - -If zero documents match the query filter in the update operation, -``updateMany()`` makes no changes to documents in the collection. See -our :ref:`upsert guide ` to -learn how to insert a new document instead of updating one if no -documents match. - -.. important:: - - The ``updateOne()`` and ``updateMany()`` methods cannot make changes - to a document that violate unique index constraints on the - collection. For more information about constraints on unique indexes, - see :manual:`Unique Indexes ` in the - {+mdb-server+} manual. - -.. _replace-operation: - -Replace -------- - -A replace operation substitutes one document from your collection. The -substitution occurs between a document your query filter matches and a -replacement document. - -The `replaceOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,TDocument)>`__ -method removes all the existing fields and values in the -matching document (except the ``_id`` field) and substitutes it with the -replacement document. - -You can call the ``replaceOne()`` method on a ``MongoCollection`` -instance as follows: - -.. code-block:: java - - collection.replaceOne(, ); - -Replace Operation Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``replaceOne()`` method has the following parameters: - -- ``query`` specifies a query filter with the criteria to match a - document to replace in your collection. -- ``replacement`` specifies fields and values of a new ``Document`` - object to replace the matched document. -- *(Optional)* ``replaceOptions`` specifies options that you can set to - customize how the driver performs the replace operation. To learn more - about this type, see the API documentation for `ReplaceOptions - <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__. - -Replace One Example -~~~~~~~~~~~~~~~~~~~ - -The paint store realizes they must update their inventory again. What they -thought was 20 cans of pink paint is actually 25 cans of orange paint. - -To update the inventory, call the ``replaceOne()`` method specifying the -following: - -- A query filter that matches documents where the ``color`` is "pink" -- A replacement document where the ``color`` is "orange" and the ``qty`` is "25" - -.. literalinclude:: /includes/fundamentals/code-snippets/Update.java - :language: java - :dedent: - :start-after: begin replaceOneExample - :end-before: end replaceOneExample - -The output of the preceding code resembles the following: - -.. code-block:: none - :copyable: false - - Matched document count: 1 - Modified document count: 1 - -The following shows the updated document: - -.. code-block:: json - :copyable: false - - { "_id": 5, "color": "orange", "qty": 25 } - -If multiple documents match the query filter specified in -the ``replaceOne()`` method, it replaces the first result. You can -specify a sort in a ``ReplaceOptions`` instance to apply an order to -matched documents before the server performs the replace operation, as -shown in the following code: - -.. literalinclude:: /includes/fundamentals/code-snippets/Update.java - :language: java - :dedent: - :start-after: begin replaceoptions - :end-before: end replaceoptions - -If zero documents match the query filter in the replace operation, -``replaceOne()`` makes no changes to documents in the collection. See -our :ref:`upsert guide ` to -learn how to insert a new document instead of replacing one if no -documents match. - -.. important:: - - The ``replaceOne()`` method cannot make changes to a document that - violate unique index constraints on the collection. - For more information about constraints on unique indexes, - see :manual:`Unique Indexes ` in the - {+mdb-server+} manual. From 58b8ced89ef95499eea21e091e737e62a33e01f6 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 19 Mar 2025 11:40:24 -0400 Subject: [PATCH 25/31] drop down --- snooty.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/snooty.toml b/snooty.toml index add7ff2b1..7a827e359 100644 --- a/snooty.toml +++ b/snooty.toml @@ -10,6 +10,7 @@ toc_landing_pages = [ "/connection", "/connection/specify-connection-options", "/crud", + "/crud/update-documents", "/aggregation", "/builders", "/data-formats", From d4484240ccb18fc14b592e423c474038d9f08c38 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 19 Mar 2025 11:44:57 -0400 Subject: [PATCH 26/31] page nav --- source/crud/update-documents.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/crud/update-documents.txt b/source/crud/update-documents.txt index 7a7e9916e..522089cef 100644 --- a/source/crud/update-documents.txt +++ b/source/crud/update-documents.txt @@ -7,6 +7,12 @@ Update Documents ================ +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + .. meta:: :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. From c8f8bae425125a9ec9f95b79dd89b453e8ced2ac Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 19 Mar 2025 11:48:14 -0400 Subject: [PATCH 27/31] crud landing --- snooty.toml | 1 - source/crud.txt | 12 ------------ source/crud/update-documents.txt | 2 +- 3 files changed, 1 insertion(+), 14 deletions(-) diff --git a/snooty.toml b/snooty.toml index 7a827e359..34305fdbd 100644 --- a/snooty.toml +++ b/snooty.toml @@ -9,7 +9,6 @@ intersphinx = [ toc_landing_pages = [ "/connection", "/connection/specify-connection-options", - "/crud", "/crud/update-documents", "/aggregation", "/builders", diff --git a/source/crud.txt b/source/crud.txt index a1f6eddd9..8a5f3277e 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -18,15 +18,3 @@ CRUD Operations Collations Large File Storage with GridFS Configure Custom CRUD Settings - -CRUD (Create, Read, Update, Delete) operations enable you to work with -data stored in MongoDB. - -- :ref:`Query Documents ` find and return - documents stored in your database. -- :ref:`Write Operations ` insert, modify, - or delete documents in your database. - -Some operations combine aspects of read and write operations. See our -guide on :ref:`compound operations ` -to learn more about these hybrid methods. diff --git a/source/crud/update-documents.txt b/source/crud/update-documents.txt index 522089cef..79441a230 100644 --- a/source/crud/update-documents.txt +++ b/source/crud/update-documents.txt @@ -31,7 +31,7 @@ documents. They apply changes specified in an update document to one or more documents that match your query filter. To learn how to updated embedded arrays or to update or insert in a -single query, see the following pages: +single operation, see the following pages: - :doc:`/crud/update-documents/embedded-arrays` - :doc:`/crud/update-documents/upsert` From 2891ab3a081b779b052455030541bb745c26fc36 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 19 Mar 2025 11:50:17 -0400 Subject: [PATCH 28/31] aggregation --- source/aggregation.txt | 216 ++--------------------------------------- 1 file changed, 6 insertions(+), 210 deletions(-) diff --git a/source/aggregation.txt b/source/aggregation.txt index 83f35ba40..e16972d2f 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -45,6 +45,12 @@ The **aggregation pipeline** is the assembly line, **aggregation stages** are the assembly stations, and **operator expressions** are the specialized tools. +For more information about aggregation in the {+driver-short+}, see the +following pages: + +- :ref:`` +- :ref:`` + Compare Aggregation and Find Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -83,213 +89,3 @@ Useful References - :manual:`Aggregation stages ` - :manual:`Operator expressions ` - :ref:`Aggregation Builders ` - -Runnable Examples ------------------ - -Import Classes -~~~~~~~~~~~~~~ - -Create a new Java file called ``AggTour.java`` and include the following import statements: - -.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java - :language: java - :dedent: - :start-after: begin imports - :end-before: end imports - -Connect to a MongoDB Deployment -+++++++++++++++++++++++++++++++ - -.. code-block:: java - - public class AggTour { - - public static void main(String[] args) { - // Replace the uri string with your MongoDB deployment's connection string - String uri = ""; - - MongoClient mongoClient = MongoClients.create(uri); - MongoDatabase database = mongoClient.getDatabase("aggregation"); - MongoCollection collection = database.getCollection("restaurants"); - - // Paste the aggregation code here - } - } - -.. tip:: - - To learn more about connecting to MongoDB, see the :ref:`Connection - Guide `. - -Insert Sample Data -++++++++++++++++++ - -.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java - :language: java - :dedent: - :start-after: begin insert - :end-before: end insert - -Basic Aggregation Example -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To perform an aggregation, pass a list of aggregation stages to the -``MongoCollection.aggregate()`` method. - -The Java driver provides the -`Aggregates <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html>`__ -helper class that contains builders for aggregation stages. - -In the following example, the aggregation pipeline: - -- Uses a :manual:`$match ` stage to filter for documents whose - ``categories`` array field contains the element ``Bakery``. The example uses - ``Aggregates.match`` to build the ``$match`` stage. - -- Uses a :manual:`$group ` stage to group the matching documents by the ``stars`` - field, accumulating a count of documents for each distinct value of ``stars``. - -.. note:: - - You can build the expressions used in this example using the :ref:`aggregation builders `. - -.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java - :language: java - :dedent: - :start-after: begin aggregation basic - :end-before: end aggregation basic - -The preceding aggregation produces the following results: - -.. code-block:: none - :copyable: false - - {"_id": 4, "count": 2} - {"_id": 5, "count": 1} - -For more information about the methods and classes mentioned in this section, -see the following API Documentation: - -- `MongoCollection.aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__ -- `Aggregates.match <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#match(org.bson.conversions.Bson)>`__ - -Explain Aggregation Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To view information about how MongoDB executes your operation, use the -``explain()`` method of the ``AggregateIterable`` class. The ``explain()`` -method returns **execution plans** and performance statistics. An execution -plan is a potential way MongoDB can complete an operation. -The ``explain()`` method provides both the winning plan, which is the plan MongoDB -executed, and any rejected plans. - -.. tip:: - - To learn more about query plans and execution statistics, see - :manual:`Explain Results ` in the Server manual. - -.. include:: /includes/fundamentals/explain-verbosity.rst - -The following example prints the JSON representation of the -winning plans for any aggregation stages that produce execution plans: - -.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java - :language: java - :dedent: - :start-after: begin aggregation explain - :end-before: end aggregation explain - -The example produces the following output as the ``$group`` stage -is the only stage that produces an execution plan: - -.. code-block:: none - :copyable: false - - { - "stage": "GROUP", - "planNodeId": 2, - "inputStage": { - "stage": "COLLSCAN", - "planNodeId": 1, - "filter": { - "categories": { - "$eq": "Bakery" - } - }, - "direction": "forward" - } - } - -For more information about the topics mentioned in this section, see the -following resources: - -- :manual:`Explain Output ` Server Manual Entry -- :manual:`Query Plans ` Server Manual Entry -- `ExplainVerbosity <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ExplainVerbosity>`__ API Documentation -- `explain() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#explain()>`__ API Documentation -- `AggregateIterable <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html>`__ API Documentation - -Aggregation Expression Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The {+driver-short+} provides builders for accumulator expressions for use with -``$group``. You must declare all other expressions in JSON format or -compatible document format. - -.. tip:: - - The syntax in either of the following examples will define an :manual:`$arrayElemAt ` - expression. - - The ``$`` in front of "categories" tells MongoDB that this is a :manual:`field path `, - using the ``categories`` field from the input document. - - .. code-block:: java - :copyable: false - - new Document("$arrayElemAt", Arrays.asList("$categories", 0)) - - .. code-block:: java - :copyable: false - - Document.parse("{ $arrayElemAt: ['$categories', 0] }") - - Alternatively, you can construct expressions by using the Aggregation - Expression Operations API. To learn more, see - :ref:`java-aggregation-expression-operations`. - -In the following example, the aggregation pipeline uses a -``$project`` stage and various ``Projections`` to return the ``name`` -field and the calculated field ``firstCategory`` whose value is the -first element in the ``categories`` field. - -.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java - :language: java - :dedent: - :start-after: begin aggregation expression - :end-before: end aggregation expression - -The preceding aggregation produces the following results: - -.. code-block:: none - :copyable: false - - {"name": "456 Cookies Shop", "firstCategory": "Bakery"} - {"name": "Sun Bakery Trattoria", "firstCategory": "Pizza"} - {"name": "456 Steak Restaurant", "firstCategory": "Steak"} - {"name": "Blue Bagels Grill", "firstCategory": "Bagels"} - {"name": "XYZ Steak Buffet", "firstCategory": "Steak"} - {"name": "Hot Bakery Cafe", "firstCategory": "Bakery"} - {"name": "Green Feast Pizzeria", "firstCategory": "Pizza"} - {"name": "ZZZ Pasta Buffet", "firstCategory": "Pasta"} - {"name": "XYZ Coffee Bar", "firstCategory": "Coffee"} - {"name": "XYZ Bagels Restaurant", "firstCategory": "Bagels"} - -For more information about the methods and classes mentioned in this section, -see the following API Documentation: - -- `Accumulators <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Accumulators.html>`__ -- `$group <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#group(TExpression,java.util.List)>`__ -- `$project <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ -- `Projections <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html>`__ From bf6e3487f2d82c65729c4c6323abb4aab2f609d6 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 11:12:14 -0400 Subject: [PATCH 29/31] MW feedback --- config/redirects | 116 +++++++++--------- source/connection/mongoclient.txt | 2 +- .../connection/specify-connection-options.txt | 7 +- .../cluster-settings.txt | 6 +- .../configure-crud.txt | 18 +-- source/crud/bulk.txt | 2 +- 6 files changed, 75 insertions(+), 76 deletions(-) diff --git a/config/redirects b/config/redirects index 20aa70b26..8fa1740a3 100644 --- a/config/redirects +++ b/config/redirects @@ -14,61 +14,61 @@ raw: ${prefix}/master -> ${base}/upcoming/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/ [*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ [*-v4.8]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/query-documents/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query-documents/find/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/query-documents/cursor/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/query-documents/sort/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/query-documents/skip/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/query-documents/limit/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query-documents/project/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query-documents/geo/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/query-documents/text/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/insert/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/insert/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/update-documents/delete/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/update-documents/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/update-documents/embedded-arrays/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/update-documents/upsert/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/bulk/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-documents/specify-query/ -[v5.3-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/ -[v5.3-master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/mongoclient -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/ -[v5.3-master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/builders/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/builders/aggregates/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/builders/filters/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/builders/indexes/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/builders/projections/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/builders/sort/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/builders/updates/ -[v5.3-master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/ -[v5.3-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/aggregation/ -[v5.3-master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/aggregation/aggregation-expression-operations/ -[v5.3-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/ -[v5.3-master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/ -[v5.3-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/ -[v5.3-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ -[v5.3-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ -[v5.3-master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/ -[v5.3-master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/ -[v5.3-master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/ -[v5.3-master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/ -[v5.3-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/ -[v5.3-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/ -[v5.3-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/ +[*-master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/query-documents/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query-documents/find/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/query-documents/cursor/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/query-documents/sort/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/query-documents/skip/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/query-documents/limit/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query-documents/project/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query-documents/geo/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/query-documents/text/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/insert/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/insert/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/update-documents/delete/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/update-documents/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/update-documents/embedded-arrays/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/update-documents/upsert/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/bulk/ +[*-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-documents/specify-query/ +[*-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/ +[*-master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/ +[*-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/ +[*-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/mongoclient +[*-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/ +[*-master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/ +[*-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/ +[*-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/ +[*-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/ +[*-master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/ +[*-master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/builders/ +[*-master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/builders/aggregates/ +[*-master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/builders/filters/ +[*-master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/builders/indexes/ +[*-master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/builders/projections/ +[*-master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/builders/sort/ +[*-master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/builders/updates/ +[*-master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/ +[*-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/aggregation/ +[*-master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/aggregation/aggregation-expression-operations/ +[*-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/ +[*-master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/ +[*-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/ +[*-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ +[*-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ +[*-master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/ +[*-master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/ +[*-master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/ +[*-master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/ +[*-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/ +[*-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/ +[*-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/ diff --git a/source/connection/mongoclient.txt b/source/connection/mongoclient.txt index b92e2ccff..22035b574 100644 --- a/source/connection/mongoclient.txt +++ b/source/connection/mongoclient.txt @@ -74,7 +74,7 @@ This example demonstrates specifying a ``ConnectionString``: builder.connectTimeout(5L, SECONDS)) .build()); - Since the driver reads the socket settings options last, the driver + Because the driver reads the socket settings options last, the driver expects to connect to an available socket within ``5 SECONDS`` before timing out. diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 209b4ba09..760e0138b 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -33,8 +33,7 @@ Overview -------- This section describes the MongoDB connection and authentication options -available in the {+driver-short+}. You can specify connection options in the -following ways: +available in the {+driver-short+}. You can specify the following connection options: - :ref:`Stable API ` - :ref:`Connection Pools ` @@ -51,7 +50,7 @@ Security and Authentication MongoDB supports many options for securing your data before and during transportation. For information about security options, see the :ref:`Security -section `, which includes the following: +section `, which includes the following pages: .. include:: /includes/security/security-pages.rst @@ -60,6 +59,6 @@ Logging and Monitoring You can learn how to using logging and monitoring with the {+driver-short+} in the :ref:`Logging and Monitoring section `, which -includes the following: +includes the following pages: .. include:: /includes/logging-monitoring/logging-monitoring-pages.rst \ No newline at end of file diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index 561c7289f..f76c519ab 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -24,7 +24,7 @@ In this guide, you can learn about how the {+driver-short+} manages clusters. You can specify settings for your clusters by using either a :ref:`connection string ` or by passing a ``MongoClientSettings`` object to the -:ref:`MongoClients ` constructor. Select the :guilabel:`Connection +:ref:`MongoClient ` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available: @@ -46,7 +46,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - ``serverSelectionTimeoutMS`` - integer - Specifies the maximum amount of time, in milliseconds, the driver - will wait for server selection to succeed before throwing an + waits for server selection to succeed before throwing an exception. *Default*: ``30000`` (30 seconds) @@ -54,7 +54,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: * - ``localThresholdMS`` - integer - When communicating with multiple instances of MongoDB in a replica - set, the driver will only send requests to a server whose response + set, the driver sends requests only to a server whose response time is less than or equal to the server with the fastest response time plus the local threshold, in milliseconds. diff --git a/source/connection/specify-connection-options/configure-crud.txt b/source/connection/specify-connection-options/configure-crud.txt index 594597946..c613920a0 100644 --- a/source/connection/specify-connection-options/configure-crud.txt +++ b/source/connection/specify-connection-options/configure-crud.txt @@ -20,15 +20,15 @@ Configure Client-level CRUD Settings Overview -------- -In this guide, you can learn about how the {+driver-short+} configures CRUD +In this guide, you can learn about how to use the {+driver-short+} to configure CRUD operations for ``MongoClient`` instances. .. include:: /includes/crud/read-write-pref-concerns.rst ``MongoDatabase`` and ``MongoCollection`` instances inherit their preferences and concerns from the ``MongoClient`` that accesses them. However, you can apply -custom settings to your databases and collections. See the :ref:`Configure Custom -CRUD Settings ` page for more information. +custom settings to your databases and collections. For more information, see the +:ref:`Configure Custom CRUD Settings ` page. You can specify client-level CRUD settings by using either a :ref:`connection string ` or by passing a ``MongoClientSettings`` object to the @@ -40,7 +40,7 @@ string ` or by passing a ``MongoClientSettings`` object to the :tabid: uri Include the following parameters in your connection string to modify the - driver's read/write behavior: + driver's read or write behavior: .. list-table:: :header-rows: 1 @@ -59,7 +59,7 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``w`` - string or integer - Specifies the write concern. For more information about values, see - the server documentation for the :manual:`w option + the {+mdb-server+} documentation for the :manual:`w option `. *Default*: ``1`` @@ -67,7 +67,7 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``wtimeoutMS`` - integer - Specifies a time limit, in milliseconds, for the write concern. For - more information, see the server documentation for the + more information, see the {+mdb-server+} documentation for the :manual:`wtimeoutMS option `. A value of ``0`` instructs the driver to never time out write operations. @@ -77,7 +77,7 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``readPreference`` - string - Specifies the read preference. For more information about values, see - the server documentation for the :manual:`readPreference option + the {+mdb-server+} documentation for the :manual:`readPreference option `. *Default*: ``primary`` @@ -85,7 +85,7 @@ string ` or by passing a ``MongoClientSettings`` object to the * - ``readPreferenceTags`` - string - Specifies the read preference tags. For more information about - values, see the server documentation for the + values, see the {+mdb-server+} documentation for the :manual:`readPreferenceTags option `. @@ -96,7 +96,7 @@ string ` or by passing a ``MongoClientSettings`` object to the - Specifies, in seconds, how stale a secondary can be before the driver stops communicating with that secondary. The minimum value is either 90 seconds or the heartbeat frequency plus 10 seconds, whichever is - greater. For more information, see the server documentation for the + greater. For more information, see the {+mdb-server+} documentation for the :manual:`maxStalenessSeconds option `. Not providing a parameter or explicitly specifying ``-1`` indicates that diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index f675fe504..f08fcf22d 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -1,7 +1,7 @@ .. _java-fundamentals-bulkwrite: ===================== -Bulk Operations +Bulk Write Operations ===================== .. contents:: On this page From fca69c6d20766877c97f19485dc2de60f13abd2d Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 11:17:52 -0400 Subject: [PATCH 30/31] connection labels --- source/connection/mongoclient.txt | 2 +- source/connection/specify-connection-options.txt | 2 ++ .../connection/specify-connection-options/cluster-settings.txt | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/source/connection/mongoclient.txt b/source/connection/mongoclient.txt index 22035b574..b3d8ddd7b 100644 --- a/source/connection/mongoclient.txt +++ b/source/connection/mongoclient.txt @@ -134,7 +134,7 @@ Replace these values to refer to your MongoDB instance. The last part of the connection URI contains connection options as parameters. In the example, you set two connection options: ``maxPoolSize=20`` and ``w=majority``. For more information about connection options, skip to the -:ref:`connection-options` section of this guide. +:ref:`java-specify-connection-options` section of this guide. .. _connection-uri-srv: diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 760e0138b..624773a4c 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -1,4 +1,6 @@ .. _java-specify-connection-options: +.. _connection-options: +.. _specify-mongoclient-settings: ========================== Specify Connection Options diff --git a/source/connection/specify-connection-options/cluster-settings.txt b/source/connection/specify-connection-options/cluster-settings.txt index f76c519ab..e7b09d625 100644 --- a/source/connection/specify-connection-options/cluster-settings.txt +++ b/source/connection/specify-connection-options/cluster-settings.txt @@ -188,7 +188,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available: .. tip:: This is analogous to the ``directConnection`` parameter you can specify - in your connection URI. See :ref:`` for more + in your connection URI. See the Connection String tab for more information. For more information about the chained methods, see the `MongoClientSettings.Builder From 744f1149737e01559d0e3fa86ef31640729cea05 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 11:53:09 -0400 Subject: [PATCH 31/31] labels --- source/crud/query-documents.txt | 23 +++++++++++------- source/crud/read-operations.txt | 33 -------------------------- source/includes/crud/example-intro.rst | 10 ++++++++ 3 files changed, 25 insertions(+), 41 deletions(-) delete mode 100644 source/crud/read-operations.txt create mode 100644 source/includes/crud/example-intro.rst diff --git a/source/crud/query-documents.txt b/source/crud/query-documents.txt index 1093774c9..b416f9759 100644 --- a/source/crud/query-documents.txt +++ b/source/crud/query-documents.txt @@ -12,6 +12,8 @@ Query Documents Specify a Query Find Documents + Count Documents + Retrieve Distinct Values of a Field Specify Which Fields to Return Limit Returned Results Sort Results @@ -20,11 +22,16 @@ Query Documents Search Text Access Data from a Cursor -- :doc:`/crud/query-documents/find` -- :doc:`/crud/query-documents/cursor` -- :doc:`/crud/query-documents/sort` -- :doc:`/crud/query-documents/skip` -- :doc:`/crud/query-documents/limit` -- :doc:`/crud/query-documents/project` -- :doc:`/crud/query-documents/geo` -- :doc:`/crud/query-documents/text` + + +- :ref:`Specify a Query ` +- :ref:`Find Documents ` +- :ref:`Access Data from a Cursor ` +- :ref:`Count Documents ` +- :ref:`Retrieve Distinct Values of a Field ` +- :ref:`Specify Which Fields to Return ` +- :ref:`Limit Returned Results ` +- :ref:`Sort Results ` +- :ref:`Skip Returned Results ` +- :ref:`Search Geospatially ` +- :ref:`Search Text ` diff --git a/source/crud/read-operations.txt b/source/crud/read-operations.txt deleted file mode 100644 index 40cd66a08..000000000 --- a/source/crud/read-operations.txt +++ /dev/null @@ -1,33 +0,0 @@ -.. _java-read-operations: - -=============== -Read Operations -=============== - -.. meta:: - :description: Learn about the commands for running read operations on MongoDB by using the {+driver-long+}. - -.. toctree:: - :caption: Read Operations - - Retrieve Data - Access Data from a Cursor - Sort Results - Skip Returned Results - Limit Returned Results - Specify Fields to Return - Count Documents - Retrieve Distinct Values of a Field - Geospatial Data - Search Text - -- :ref:`Retrieve ` -- :ref:`Access Data From a Cursor ` -- :ref:`Sort Results ` -- :ref:`Skip Returned Results ` -- :ref:`Limit the Number of Returned Results ` -- :ref:`Specify Which Fields to Return ` -- :ref:`Count Documents ` -- :ref:`Retrieve Distinct Values of a Field ` -- :ref:`Search Geospatially ` -- :ref:`Search Text ` diff --git a/source/includes/crud/example-intro.rst b/source/includes/crud/example-intro.rst new file mode 100644 index 000000000..e2b1374dd --- /dev/null +++ b/source/includes/crud/example-intro.rst @@ -0,0 +1,10 @@ +.. note:: Example Setup + + This example connects to an instance of MongoDB by using a connection URI. To learn + more about connecting to your MongoDB instance, see the :ref:`connection guide + `. This example also uses the ``movies`` collection in the + ``sample_mflix`` database included in the :atlas:`Atlas sample datasets + `. You can load them into + your database on the free tier of MongoDB Atlas by following the :atlas:`Get + Started with Atlas Guide + `. \ No newline at end of file