From c36554386d422722485d0bc73262137b53b99f31 Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Mon, 17 Mar 2025 13:27:09 -0700 Subject: [PATCH 01/26] DOCSP-48375 ToC reorg part one (#1035) --- config/redirects | 61 +++- snooty.toml | 19 +- source/aggregation-tutorials.txt | 124 ------- source/{fundamentals => }/aggregation.txt | 116 ++++++- .../filtered-subset.txt | 0 .../group-total.txt | 0 .../multi-field-join.txt | 0 .../one-to-one-join.txt | 0 .../unpack-arrays.txt | 0 .../collations.txt | 3 +- .../quick-start/connect-to-mongodb.txt | 0 .../create-a-connection-string.txt | 0 .../quick-start/create-a-deployment.txt | 0 .../quick-start/download-and-install.txt | 0 .../quick-start/facets.toml | 0 .../quick-start/next-steps.txt | 0 .../connection.txt => connect.txt} | 42 +-- .../connection-options.txt | 16 +- .../connection-options/connection-pools.txt | 30 ++ .../connection-options}/csot.txt | 0 .../network-compression.txt | 0 .../connection-options/server-selection.txt | 21 ++ .../connection-options}/stable-api.txt | 0 source/connect/connection-targets.txt | 18 + .../connection-troubleshooting.txt | 0 .../connect.txt => connect/mongoclient.txt} | 12 +- source/crud.txt | 38 +++ .../bulk.txt => crud/bulk-write.txt} | 2 +- .../crud/compound-operations.txt | 0 source/crud/configure.txt | 321 ++++++++++++++++++ .../crud/write-operations => crud}/delete.txt | 1 + source/{fundamentals => crud}/gridfs.txt | 2 +- .../crud/write-operations => crud}/insert.txt | 1 + .../write-operations => crud}/pkFactory.txt | 0 source/crud/query.txt | 253 ++++++++++++++ .../{usage-examples => crud/query}/count.txt | 1 + .../read-operations => crud/query}/cursor.txt | 1 + .../query}/distinct.txt | 1 + .../read-operations => crud/query}/geo.txt | 3 +- .../query}/project.txt | 1 + .../crud => crud/query}/query-document.txt | 1 + .../query}/retrieve.txt | 11 +- .../query/specify-documents-to-return.txt | 28 ++ .../read-operations => crud/query}/text.txt | 1 + .../crud/read-write-pref.txt | 0 .../{fundamentals => crud}/transactions.txt | 1 + .../upsert.txt => crud/update.txt} | 15 +- .../update}/embedded-arrays.txt | 1 + .../update}/modify.txt | 12 +- source/crud/update/replace.txt | 21 ++ source/data-formats.txt | 35 ++ source/data-formats/bson.txt | 25 ++ .../time-series.txt | 4 +- source/fundamentals/bson.txt | 31 -- source/fundamentals/crud.txt | 57 ---- source/fundamentals/crud/read-operations.txt | 38 --- source/fundamentals/crud/write-operations.txt | 1 - source/get-started.txt | 229 +++++++++++++ source/index.txt | 117 +++---- source/{fundamentals => }/indexes.txt | 3 +- source/monitoring-and-logging.txt | 24 ++ .../change-streams.txt} | 28 +- .../logging.txt | 0 .../monitoring.txt | 2 + source/quick-start.txt | 45 --- source/reference.txt | 14 + source/{ => reference}/compatibility.txt | 0 source/{ => reference}/quick-reference.txt | 2 +- .../release-notes.txt} | 7 +- source/{ => reference}/upgrade.txt | 0 source/{fundamentals => }/run-command.txt | 0 source/security.txt | 34 ++ .../authentication.txt | 9 +- .../authentication/enterprise-mechanisms.txt | 0 .../authentication/mechanisms.txt | 0 .../encrypt-fields.txt | 0 .../connection => security}/socks.txt | 1 + .../connection => security}/tls.txt | 1 + source/{fundamentals => }/typescript.txt | 5 +- source/usage-examples.txt | 7 +- 80 files changed, 1464 insertions(+), 433 deletions(-) delete mode 100644 source/aggregation-tutorials.txt rename source/{fundamentals => }/aggregation.txt (55%) rename source/{aggregation-tutorials => aggregation}/filtered-subset.txt (100%) rename source/{aggregation-tutorials => aggregation}/group-total.txt (100%) rename source/{aggregation-tutorials => aggregation}/multi-field-join.txt (100%) rename source/{aggregation-tutorials => aggregation}/one-to-one-join.txt (100%) rename source/{aggregation-tutorials => aggregation}/unpack-arrays.txt (100%) rename source/{fundamentals => archive-reference-files}/collations.txt (99%) rename source/{ => archive-reference-files}/quick-start/connect-to-mongodb.txt (100%) rename source/{ => archive-reference-files}/quick-start/create-a-connection-string.txt (100%) rename source/{ => archive-reference-files}/quick-start/create-a-deployment.txt (100%) rename source/{ => archive-reference-files}/quick-start/download-and-install.txt (100%) rename source/{ => archive-reference-files}/quick-start/facets.toml (100%) rename source/{ => archive-reference-files}/quick-start/next-steps.txt (100%) rename source/{fundamentals/connection.txt => connect.txt} (65%) rename source/{fundamentals/connection => connect}/connection-options.txt (96%) create mode 100644 source/connect/connection-options/connection-pools.txt rename source/{fundamentals/connection => connect/connection-options}/csot.txt (100%) rename source/{fundamentals/connection => connect/connection-options}/network-compression.txt (100%) create mode 100644 source/connect/connection-options/server-selection.txt rename source/{fundamentals => connect/connection-options}/stable-api.txt (100%) create mode 100644 source/connect/connection-targets.txt rename source/{ => connect}/connection-troubleshooting.txt (100%) rename source/{fundamentals/connection/connect.txt => connect/mongoclient.txt} (95%) create mode 100644 source/crud.txt rename source/{fundamentals/crud/write-operations/bulk.txt => crud/bulk-write.txt} (99%) rename source/{fundamentals => }/crud/compound-operations.txt (100%) create mode 100644 source/crud/configure.txt rename source/{fundamentals/crud/write-operations => crud}/delete.txt (99%) rename source/{fundamentals => crud}/gridfs.txt (99%) rename source/{fundamentals/crud/write-operations => crud}/insert.txt (99%) rename source/{fundamentals/crud/write-operations => crud}/pkFactory.txt (100%) create mode 100644 source/crud/query.txt rename source/{usage-examples => crud/query}/count.txt (99%) rename source/{fundamentals/crud/read-operations => crud/query}/cursor.txt (99%) rename source/{fundamentals/crud/read-operations => crud/query}/distinct.txt (99%) rename source/{fundamentals/crud/read-operations => crud/query}/geo.txt (98%) rename source/{fundamentals/crud/read-operations => crud/query}/project.txt (99%) rename source/{fundamentals/crud => crud/query}/query-document.txt (99%) rename source/{fundamentals/crud/read-operations => crud/query}/retrieve.txt (98%) create mode 100644 source/crud/query/specify-documents-to-return.txt rename source/{fundamentals/crud/read-operations => crud/query}/text.txt (99%) rename source/{fundamentals => }/crud/read-write-pref.txt (100%) rename source/{fundamentals => crud}/transactions.txt (99%) rename source/{fundamentals/crud/write-operations/upsert.txt => crud/update.txt} (93%) rename source/{fundamentals/crud/write-operations => crud/update}/embedded-arrays.txt (99%) rename source/{fundamentals/crud/write-operations => crud/update}/modify.txt (95%) create mode 100644 source/crud/update/replace.txt create mode 100644 source/data-formats.txt create mode 100644 source/data-formats/bson.txt rename source/{fundamentals => data-formats}/time-series.txt (95%) delete mode 100644 source/fundamentals/bson.txt delete mode 100644 source/fundamentals/crud.txt delete mode 100644 source/fundamentals/crud/read-operations.txt create mode 100644 source/get-started.txt rename source/{fundamentals => }/indexes.txt (99%) create mode 100644 source/monitoring-and-logging.txt rename source/{usage-examples/changeStream.txt => monitoring-and-logging/change-streams.txt} (93%) rename source/{fundamentals => monitoring-and-logging}/logging.txt (100%) rename source/{fundamentals => monitoring-and-logging}/monitoring.txt (97%) delete mode 100644 source/quick-start.txt create mode 100644 source/reference.txt rename source/{ => reference}/compatibility.txt (100%) rename source/{ => reference}/quick-reference.txt (99%) rename source/{whats-new.txt => reference/release-notes.txt} (99%) rename source/{ => reference}/upgrade.txt (100%) rename source/{fundamentals => }/run-command.txt (100%) create mode 100644 source/security.txt rename source/{fundamentals => security}/authentication.txt (76%) rename source/{fundamentals => security}/authentication/enterprise-mechanisms.txt (100%) rename source/{fundamentals => security}/authentication/mechanisms.txt (100%) rename source/{fundamentals => security}/encrypt-fields.txt (100%) rename source/{fundamentals/connection => security}/socks.txt (99%) rename source/{fundamentals/connection => security}/tls.txt (99%) rename source/{fundamentals => }/typescript.txt (99%) diff --git a/config/redirects b/config/redirects index 5119e2f69..73b0fb329 100644 --- a/config/redirects +++ b/config/redirects @@ -23,4 +23,63 @@ raw: ${prefix}/stable -> ${base}/current/ [*-v5.5]: ${prefix}/${version}/fundamentals/run-command/ -> ${base}/${version}/usage-examples/command/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/ -[*-v6.0): ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ +[*-v6.0)]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ + +[*-master]: ${prefix}/${version}/quick-start/download-and-install/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/quick-start/create-a-deployment/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/quick-start/create-a-connection-string/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/quick-start/connect-to-mongodb/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/quick-start/next-steps/ -> ${base}/${version}/get-started/ +[*-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connect/ +[*-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connect/mongoclient/ +[*-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connect/connection-options/ +[*-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connect/connection-troubleshooting/ +[*-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connect/connection-options/network-compression/ +[*-master]: ${prefix}/${version}/fundamentals/connection/csot/ -> ${base}/${version}/connect/connection-options/csot/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/bulk-write/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/insert/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/update/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/delete/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/query/ +[*-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query/query-document/ +[*-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-write-pref/ -> ${base}/${version}/crud/read-write-pref/ +[*-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ +[*-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query/retrieve/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query/project/ +[*-master]: ${prefix}/${version}/fundamentals/usage-examples/count/ -> ${base}/${version}/crud/query/count/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/distinct/ -> ${base}/${version}/crud/query/distinct/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/query/cursor/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query/geo/ +[*-master]: ${prefix}/${version}/fundamentals/crud/time-series/ -> ${base}/${version}/data-formats/time-series/ +[*-master]: ${prefix}/${version}/fundamentals/bson/ -> ${base}/${version}/data-formats/bson/ +[*-master]: ${prefix}/${version}/fundamentals/indexes/ -> ${base}/${version}/indexes/ +[*-master]: ${prefix}/${version}/fundamentals/run-command/ -> ${base}/${version}/run-command/ +[*-master]: ${prefix}/${version}/fundamentals/monitoring/ -> ${base}/${version}/monitoring-and-logging/monitoring/ +[*-master]: ${prefix}/${version}/fundamentals/logging/ -> ${base}/${version}/monitoring-and-logging/logging/ +[*-master]: ${prefix}/${version}/usage-examples/changeStream -> ${base}/monitoring-and-logging/change-streams/ +[*-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/aggregation/ +[*-master]: ${prefix}/${version}/aggregation-tutorials/ -> ${base}/aggregation/ +[*-master]: ${prefix}/${version}/aggregation-tutorials/filtered-subset/ -> ${base}/aggregation/filtered-subset/ +[*-master]: ${prefix}/${version}/aggregation-tutorials/group-total/ -> ${base}/aggregation/group-total/ +[*-master]: ${prefix}/${version}/aggregation-tutorials/multi-field-join/ -> ${base}/aggregation/multi-field-join/ +[*-master]: ${prefix}/${version}/aggregation-tutorials/one-to-one-join/ -> ${base}/aggregation/one-to-one-join/ +[*-master]: ${prefix}/${version}/aggregation-tutorials/unpack-arrays/ -> ${base}/aggregation/unpack-arrays/ +[*-master]: ${prefix}/${version}/fundamentals/authentication -> ${base}/security/authentication/ +[*-master]: ${prefix}/${version}/fundamentals/authentication/mechanisms/ -> ${base}/security/authentication/mechanisms/ +[*-master]: ${prefix}/${version}/fundamentals/authentication/enterprise-mechanisms/ -> ${base}/security/authentication/enterprise-mechanisms/ +[*-master]: ${prefix}/${version}/fundamentals/encrypt-fields/ -> ${base}/security/encrypt-fields/ +[*-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/security/tls/ +[*-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/security/socks/ +[*-master]: ${prefix}/${version}/fundamentals/typescript/ -> ${base}/typescript/ +[*-master]: ${prefix}/${version}/whats-new/ -> ${base}/reference/release-notes/ +[*-master]: ${prefix}/${version}/compatibility/ -> ${base}/reference/compatibility/ +[*-master]: ${prefix}/${version}/upgrade/ -> ${base}/reference/upgrade/ +[*-master]: ${prefix}/${version}/quick-reference/ -> ${base}/reference/quick-reference/ +[*-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/crud/configure/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/crud/query/text/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/crud/update/modify/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/crud/update/embedded-arrays/ +[*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/pkFactory/ -> ${base}/crud/pkFactory/ + diff --git a/snooty.toml b/snooty.toml index 57178bd89..4789d56ae 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,14 +7,19 @@ intersphinx = [ ] toc_landing_pages = [ - "/fundamentals/authentication", - "/fundamentals", - "/fundamentals/connection", - "/fundamentals/crud", - "/fundamentals/bson", - "/usage-examples", - "/quick-start", + "/get-started", + "/connect", + "/aggregation", + "/aggregation/aggregation-tutorials", + "/security", + "/security/authentication", "/aggregation-tutorials", + "/data-formats", + "connect/connection-options", + "crud", + "/crud/query", + "crud/update", + "monitoring-and-logging" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/aggregation-tutorials.txt b/source/aggregation-tutorials.txt deleted file mode 100644 index 8b545467b..000000000 --- a/source/aggregation-tutorials.txt +++ /dev/null @@ -1,124 +0,0 @@ -.. _node-aggregation-tutorials-landing: - -===================== -Aggregation Tutorials -===================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: node.js, code example, runnable app - :description: Explore step-by-step aggregation tutorials for common tasks using the MongoDB Node.js Driver, including setup instructions and runnable code examples. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. toctree:: - - Filtered Subset - Group & Total - Unpack Arrays & Group - One-to-One Join - Multi-Field Join - -Overview --------- - -Aggregation tutorials provide detailed explanations of common -aggregation tasks in a step-by-step format. The tutorials are adapted -from examples in the `Practical MongoDB Aggregations book -`__ by Paul Done. - -Each tutorial includes the following sections: - -- **Introduction**, which describes the purpose and common use cases of the - aggregation type. This section also describes the example and desired - outcome that the tutorial demonstrates. - -- **Before You Get Started**, which describes the necessary databases, - collections, and sample data that you must have before building the - aggregation pipeline and performing the aggregation. - -- **Tutorial**, which describes how to build and run the aggregation - pipeline. This section describes each stage of the completed - aggregation tutorial, and then explains how to run and interpret the - output of the aggregation. - -At the end of each aggregation tutorial, you can find a link to a fully -runnable Node.js code file that you can run in your environment. - -.. tip:: - - To learn more about performing aggregations, see the - :ref:`node-aggregation` guide. - -.. _node-agg-tutorial-template-app: - -Aggregation Template App ------------------------- - -Before you begin following an aggregation tutorial, you must set up a -new Node.js app. You can use this app to connect to a MongoDB -deployment, insert sample data into MongoDB, and run the aggregation -pipeline in each tutorial. - -.. tip:: - - To learn how to install the driver and connect to MongoDB, - see the :ref:`node-quick-start-download-and-install` and - :ref:`node-quick-start-create-deployment` steps of the - Quick Start guide. - -Once you install the driver, create a file called -``agg_tutorial.js``. Paste the following code in this file to create an -app template for the aggregation tutorials: - -.. literalinclude:: /includes/aggregation/template-app.js - :language: javascript - :copyable: true - -.. important:: - - In the preceding code, read the code comments to find the sections of - the code that you must modify for the tutorial you are following. - - If you attempt to run the code without making any changes, you will - encounter a connection error. - -For every tutorial, you must replace the connection string placeholder with -your deployment's connection string. - -.. tip:: - - To learn how to locate your deployment's connection string, see the - :ref:`node-quick-start-connection-string` step of the Quick Start guide. - -For example, if your connection string is -``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles -the following: - -.. code-block:: javascript - :copyable: false - - const uri = "mongodb+srv://mongodb-example:27017"; - -To run the completed file after you modify the template for a -tutorial, run the following command in your shell: - -.. code-block:: bash - - node agg_tutorial.js - -Available Tutorials -------------------- - -- :ref:`node-aggregation-filtered-subset` -- :ref:`node-aggregation-group-total` -- :ref:`node-aggregation-arrays` -- :ref:`node-aggregation-one-to-one` -- :ref:`node-aggregation-multi-field` \ No newline at end of file diff --git a/source/fundamentals/aggregation.txt b/source/aggregation.txt similarity index 55% rename from source/fundamentals/aggregation.txt rename to source/aggregation.txt index a158b589a..c4f2504e4 100644 --- a/source/fundamentals/aggregation.txt +++ b/source/aggregation.txt @@ -5,8 +5,12 @@ Aggregation =========== +.. facet:: + :name: genre + :values: reference + .. meta:: - :description: Learn to use aggregation operations in the MongoDB Node.js Driver to create pipelines for data transformation and summarization. + :keywords: node.js, code example, runnable app .. contents:: On this page :local: @@ -14,6 +18,14 @@ Aggregation :depth: 2 :class: singlecol +.. toctree:: + + Filtered Subset + Group & Total + Unpack Arrays & Group + One-to-One Join + Multi-Field Join + .. _nodejs-aggregation-overview: Overview @@ -101,7 +113,7 @@ database: .. tip:: - For more information on connecting to your MongoDB deployment, see the :doc:`Connection Guide `. + For more information on connecting to your MongoDB deployment, see the :doc:`Connection Guide `. Aggregation Example ~~~~~~~~~~~~~~~~~~~ @@ -134,6 +146,106 @@ This example produces the following output: For more information, see the `aggregate() API documentation <{+api+}/classes/Collection.html#aggregate>`__. +.. _node-aggregation-tutorials-landing: +.. _node-aggregation-tutorials: + +Aggregation Tutorials +--------------------- + +Aggregation tutorials provide detailed explanations of common +aggregation tasks in a step-by-step format. The tutorials are adapted +from examples in the `Practical MongoDB Aggregations book +`__ by Paul Done. + +Each tutorial includes the following sections: + +- **Introduction**, which describes the purpose and common use cases of the + aggregation type. This section also describes the example and desired + outcome that the tutorial demonstrates. + +- **Before You Get Started**, which describes the necessary databases, + collections, and sample data that you must have before building the + aggregation pipeline and performing the aggregation. + +- **Tutorial**, which describes how to build and run the aggregation + pipeline. This section describes each stage of the completed + aggregation tutorial, and then explains how to run and interpret the + output of the aggregation. + +At the end of each aggregation tutorial, you can find a link to a fully +runnable Node.js code file that you can run in your environment. + +.. tip:: + + To learn more about performing aggregations, see the + :ref:`node-aggregation` guide. + +.. _node-agg-tutorial-template-app: + +Aggregation Template App +~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you begin following an aggregation tutorial, you must set up a +new Node.js app. You can use this app to connect to a MongoDB +deployment, insert sample data into MongoDB, and run the aggregation +pipeline in each tutorial. + +.. tip:: + + To learn how to install the driver and connect to MongoDB, + see the :ref:`node-get-started-download-and-install` and + :ref:`node-get-started-create-deployment` steps of the + Quick Start guide. + +Once you install the driver, create a file called +``agg_tutorial.js``. Paste the following code in this file to create an +app template for the aggregation tutorials: + +.. literalinclude:: /includes/aggregation/template-app.js + :language: javascript + :copyable: true + +.. important:: + + In the preceding code, read the code comments to find the sections of + the code that you must modify for the tutorial you are following. + + If you attempt to run the code without making any changes, you will + encounter a connection error. + +For every tutorial, you must replace the connection string placeholder with +your deployment's connection string. + +.. tip:: + + To learn how to locate your deployment's connection string, see the + :ref:`node-get-started-connection-string` step of the Quick Start guide. + +For example, if your connection string is +``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles +the following: + +.. code-block:: javascript + :copyable: false + + const uri = "mongodb+srv://mongodb-example:27017"; + +To run the completed file after you modify the template for a +tutorial, run the following command in your shell: + +.. code-block:: bash + + node agg_tutorial.js + +Available Tutorials +~~~~~~~~~~~~~~~~~~~ + +- :ref:`node-aggregation-filtered-subset` +- :ref:`node-aggregation-group-total` +- :ref:`node-aggregation-arrays` +- :ref:`node-aggregation-one-to-one` +- :ref:`node-aggregation-multi-field` + Additional Examples ~~~~~~~~~~~~~~~~~~~ diff --git a/source/aggregation-tutorials/filtered-subset.txt b/source/aggregation/filtered-subset.txt similarity index 100% rename from source/aggregation-tutorials/filtered-subset.txt rename to source/aggregation/filtered-subset.txt diff --git a/source/aggregation-tutorials/group-total.txt b/source/aggregation/group-total.txt similarity index 100% rename from source/aggregation-tutorials/group-total.txt rename to source/aggregation/group-total.txt diff --git a/source/aggregation-tutorials/multi-field-join.txt b/source/aggregation/multi-field-join.txt similarity index 100% rename from source/aggregation-tutorials/multi-field-join.txt rename to source/aggregation/multi-field-join.txt diff --git a/source/aggregation-tutorials/one-to-one-join.txt b/source/aggregation/one-to-one-join.txt similarity index 100% rename from source/aggregation-tutorials/one-to-one-join.txt rename to source/aggregation/one-to-one-join.txt diff --git a/source/aggregation-tutorials/unpack-arrays.txt b/source/aggregation/unpack-arrays.txt similarity index 100% rename from source/aggregation-tutorials/unpack-arrays.txt rename to source/aggregation/unpack-arrays.txt diff --git a/source/fundamentals/collations.txt b/source/archive-reference-files/collations.txt similarity index 99% rename from source/fundamentals/collations.txt rename to source/archive-reference-files/collations.txt index a4474eb21..2ad831cbd 100644 --- a/source/fundamentals/collations.txt +++ b/source/archive-reference-files/collations.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-collations: +.. _node-collations: ========== Collations @@ -58,7 +59,7 @@ Usage ----- You can specify a collation when you create a new collection or new index. You -can also specify a collation for :doc:`CRUD operations ` +can also specify a collation for :doc:`CRUD operations ` and aggregations. When you create a new collection with a collation, you define the default diff --git a/source/quick-start/connect-to-mongodb.txt b/source/archive-reference-files/quick-start/connect-to-mongodb.txt similarity index 100% rename from source/quick-start/connect-to-mongodb.txt rename to source/archive-reference-files/quick-start/connect-to-mongodb.txt diff --git a/source/quick-start/create-a-connection-string.txt b/source/archive-reference-files/quick-start/create-a-connection-string.txt similarity index 100% rename from source/quick-start/create-a-connection-string.txt rename to source/archive-reference-files/quick-start/create-a-connection-string.txt diff --git a/source/quick-start/create-a-deployment.txt b/source/archive-reference-files/quick-start/create-a-deployment.txt similarity index 100% rename from source/quick-start/create-a-deployment.txt rename to source/archive-reference-files/quick-start/create-a-deployment.txt diff --git a/source/quick-start/download-and-install.txt b/source/archive-reference-files/quick-start/download-and-install.txt similarity index 100% rename from source/quick-start/download-and-install.txt rename to source/archive-reference-files/quick-start/download-and-install.txt diff --git a/source/quick-start/facets.toml b/source/archive-reference-files/quick-start/facets.toml similarity index 100% rename from source/quick-start/facets.toml rename to source/archive-reference-files/quick-start/facets.toml diff --git a/source/quick-start/next-steps.txt b/source/archive-reference-files/quick-start/next-steps.txt similarity index 100% rename from source/quick-start/next-steps.txt rename to source/archive-reference-files/quick-start/next-steps.txt diff --git a/source/fundamentals/connection.txt b/source/connect.txt similarity index 65% rename from source/fundamentals/connection.txt rename to source/connect.txt index c768dba01..55526a6ec 100644 --- a/source/fundamentals/connection.txt +++ b/source/connect.txt @@ -1,34 +1,34 @@ -.. _node-connection: +.. _node-connect: -========== -Connection -========== +================== +Connect to MongoDB +================== -.. default-domain:: mongodb +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol .. facet:: :name: genre :values: reference + +.. meta:: + :description: Learn how to use {+driver-short+} to connect to MongoDB. + :keywords: client, ssl -.. meta:: - :description: Learn how to configure your application's connection to a MongoDB deployment by using the Node.js driver. - :keywords: node.js +.. toctree:: + :titlesonly: + :maxdepth: 1 .. toctree:: - Connection Guide - Connection Options - Network Compression - TLS - SOCKS5 Proxy Support - Limit Server Execution Time + Create a MongoClient + Connection Options + Choose a Connection Target Connect with AWS Lambda - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol + Connection Troubleshooting Overview -------- @@ -37,7 +37,7 @@ Learn how to configure your application's connection to a MongoDB deployment using the Node.js driver. In the following sections, you will learn: -- :ref:`How to Connect to MongoDB ` +- :ref:`How to Create a MongoClient ` - :ref:`The Available Connection Options ` - :ref:`How to Enable Network Compression ` - :ref:`How to Enable TLS on a Connection ` diff --git a/source/fundamentals/connection/connection-options.txt b/source/connect/connection-options.txt similarity index 96% rename from source/fundamentals/connection/connection-options.txt rename to source/connect/connection-options.txt index e0f4cb4ff..a5afce3c0 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/connect/connection-options.txt @@ -1,8 +1,8 @@ .. _node-connection-options: -================== -Connection Options -================== +========================== +Specify Connection Options +========================== .. facet:: :name: genre @@ -12,6 +12,16 @@ Connection Options :keywords: node.js, customize :description: Explore connection and authentication options available in the MongoDB Node.js Driver, including settings for app name, authentication mechanisms, and TLS configurations. +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Compress Network Traffic + Customize Server Selection + Stable API + Limit Server Execution Time + Connection Pools + This section explains the MongoDB connection and authentication options supported by the {+driver-short+} that you can set within a ``MongoClientOptions`` instance. diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt new file mode 100644 index 000000000..2050239bf --- /dev/null +++ b/source/connect/connection-options/connection-pools.txt @@ -0,0 +1,30 @@ +.. _node-connection-pools: + +================ +Connection Pools +================ + +.. facet:: + :name: genre + :values: reference + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about how {+driver-short+} uses connection pools to manage +connections to a MongoDB deployment and how you can configure connection pool settings +in your application. + +A connection pool is a cache of open database connections maintained by {+driver-short+}. +When your application requests a connection to MongoDB, {+driver-short+} seamlessly +gets a connection from the pool, performs operations, and returns the connection +to the pool for reuse. + +Connection pools help reduce application latency and the number of times new connections +are created by {+driver-short+}. \ No newline at end of file diff --git a/source/fundamentals/connection/csot.txt b/source/connect/connection-options/csot.txt similarity index 100% rename from source/fundamentals/connection/csot.txt rename to source/connect/connection-options/csot.txt diff --git a/source/fundamentals/connection/network-compression.txt b/source/connect/connection-options/network-compression.txt similarity index 100% rename from source/fundamentals/connection/network-compression.txt rename to source/connect/connection-options/network-compression.txt diff --git a/source/connect/connection-options/server-selection.txt b/source/connect/connection-options/server-selection.txt new file mode 100644 index 000000000..d7798049b --- /dev/null +++ b/source/connect/connection-options/server-selection.txt @@ -0,0 +1,21 @@ +.. _node-server-selection: + +========================== +Customize Server Selection +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, read preference, write + +Overview +-------- \ No newline at end of file diff --git a/source/fundamentals/stable-api.txt b/source/connect/connection-options/stable-api.txt similarity index 100% rename from source/fundamentals/stable-api.txt rename to source/connect/connection-options/stable-api.txt diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 000000000..df72aba8a --- /dev/null +++ b/source/connect/connection-targets.txt @@ -0,0 +1,18 @@ +.. _node-connection-targets: + +========================== +Choose a Connection Target +========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, server, settings, client, load balancing, srv, dns + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol \ No newline at end of file diff --git a/source/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt similarity index 100% rename from source/connection-troubleshooting.txt rename to source/connect/connection-troubleshooting.txt diff --git a/source/fundamentals/connection/connect.txt b/source/connect/mongoclient.txt similarity index 95% rename from source/fundamentals/connection/connect.txt rename to source/connect/mongoclient.txt index 17fb36766..a0176ab71 100644 --- a/source/fundamentals/connection/connect.txt +++ b/source/connect/mongoclient.txt @@ -1,16 +1,16 @@ -.. _node-connect-to-mongodb: +.. _node-mongoclient: -================ -Connection Guide -================ +==================== +Create a MongoClient +==================== .. facet:: :name: genre :values: reference .. meta:: - :description: Learn how to connect to a MongoDB Atlas or local MongoDB deployment by using the Node.js driver. - :keywords: node.js, code example, connection string, local connection, Stable API, Atlas + :description: Learn how to create a MongoClient using the {+driver-short+}. + :keywords: connection string, URI, server, Atlas, settings, client .. contents:: On this page :local: diff --git a/source/crud.txt b/source/crud.txt new file mode 100644 index 000000000..abf96d299 --- /dev/null +++ b/source/crud.txt @@ -0,0 +1,38 @@ +.. _node-crud-landing: +.. _node-crud-operations: + +=============== +CRUD Operations +=============== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use {+driver-short+} to read and write MongoDB data. + :keywords: usage examples, query, find, code example, save, create + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Insert Documents + Query Documents + Update Documents + Delete Documents + Bulk Write Operations + Compound Operations + Transactions + Configure CRUD Operations + Operations on Replica Sets + Store Large Files + +CRUD (Create, Read, Update, Delete) operations enable you to work with +data stored in MongoDB. \ No newline at end of file diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/crud/bulk-write.txt similarity index 99% rename from source/fundamentals/crud/write-operations/bulk.txt rename to source/crud/bulk-write.txt index 7cba6ee8a..35c9c6310 100644 --- a/source/fundamentals/crud/write-operations/bulk.txt +++ b/source/crud/bulk-write.txt @@ -1,4 +1,4 @@ -.. _node-fundamentals-bulk: +.. _node-bulk-write: =============== Bulk Operations diff --git a/source/fundamentals/crud/compound-operations.txt b/source/crud/compound-operations.txt similarity index 100% rename from source/fundamentals/crud/compound-operations.txt rename to source/crud/compound-operations.txt diff --git a/source/crud/configure.txt b/source/crud/configure.txt new file mode 100644 index 000000000..521f75e68 --- /dev/null +++ b/source/crud/configure.txt @@ -0,0 +1,321 @@ +.. _node-configure: + +========================= +Configure CRUD Operations +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: insert, update, replace, delete, options, code example + +Overview +-------- + +In this guide, you can learn how to configure read and write operations in {+driver-short+}. + +.. _node-fundamentals-collations: +.. _node-collations: + +Collations +---------- + +*Collations are available in MongoDB 3.4 and later.* + +You can use **collations**, a set of sorting rules, to run operations using +string ordering for specific languages and locales (a community or region that +shares common language idioms). + +MongoDB sorts strings using *binary collation* by default. This collation +method uses the `ASCII standard `_ +character values to compare and order strings. Languages and locales +have specific character ordering conventions that differ from the ASCII +standard. + +For example, in Canadian French, the right-most accented character determines +the ordering for strings when the other characters are the same. Consider the +following French words: **cote**, **coté**, **côte**, and **côté**. + +MongoDB sorts them in the following order using the default binary collation: + +.. code-block:: none + + cote + coté + côte + côté + +MongoDB sorts them in the following order using the Canadian French collation: + +.. code-block:: none + + cote + côte + coté + côté + +Using Collations +~~~~~~~~~~~~~~~~~~ + +You can specify a collation when you create a new collection or new index. You +can also specify a collation for :doc:`CRUD operations ` +and aggregations. + +When you create a new collection with a collation, you define the default +collation for any of the :manual:`operations that support collation +` called on that +collection. You can override the collation for an operation by specifying a +different one. + +.. note:: + + Currently, you cannot create a collation on an existing collection. To use + collations with an existing collection, create an index with the collation + and specify the same collation in your operations on it. + +When you create an index with a collation, you specify the sort order for +operations that use that index. To use the collation in the index, you +must provide a matching collation in the operation, and the operation must +use the index. While most index types support collation, the following +types support only binary comparison: + +- :manual:`text ` +- :manual:`2d ` +- :manual:`geoHaystack ` + +Collation Parameters +~~~~~~~~~~~~~~~~~~~~ + +The collation object contains the following parameters: + +.. code-block:: javascript + + collation: { + locale: , + caseLevel: , + caseFirst: , + strength: , + numericOrdering: , + alternate: , + maxVariable: , + backwards: + } + +You must specify the ``locale`` field in the collation; all other fields +are optional. For a complete list of supported locales and the default values +for the ``locale`` fields, see :manual:`Supported Languages and Locales +`. +For descriptions of each field, see the :manual:`Collation Document MongoDB +manual entry `. + +Set a Default Collation on a Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the following example, we create a new collection called ``souvenirs`` and +assign a default collation with the ``"fr_CA"`` locale. The collation applies +to all :manual:`operations that support collation +` performed on that +collection. + +.. literalinclude:: /code-snippets/collation/collection-collation.js + :language: javascript + :start-after: start collection collation + :end-before: end collection collation + +Any of the operations that support collations automatically apply the collation +defined on the collection. The query below searches the ``souvenirs`` +collection and applies the ``"fr_CA"`` locale collation: + +.. literalinclude:: /code-snippets/collation/collection-auto-collation.js + :language: javascript + :start-after: start auto collation + :end-before: end auto collation + +You can specify a different collation as a parameter in an operation that +supports collations. The following query specifies the ``"is"`` Iceland locale +and ``caseFirst`` optional parameter with the value ``"upper"``: + +.. literalinclude:: /code-snippets/collation/collection-specify-collation.js + :language: javascript + :start-after: start specified collation + :end-before: end specified collation + +Assign a Collation to an Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the following example, we create a new index on the ``title`` field of +a collection with a collation set to the ``"en_US"`` locale. + +.. literalinclude:: /code-snippets/collation/index-collation.js + :language: javascript + :start-after: start create index collation + :end-before: end create index collation + +The following query uses the index we created: + +.. literalinclude:: /code-snippets/collation/query-index-collation.js + :language: javascript + :start-after: start query index collation + :end-before: end query index collation + +The following queries **do not** use the index that we created. The first +query does not include a collation and the second contains a different +strength value than the collation on the index. + +.. literalinclude:: /code-snippets/collation/query-not-indexed-collation.js + :language: javascript + :start-after: start not indexed collation + :end-before: end not indexed collation + +.. literalinclude:: /code-snippets/collation/query-index-no-collation.js + :language: javascript + :start-after: start index no collation + :end-before: end index no collation + +Collation Query Examples +~~~~~~~~~~~~~~~~~~~~~~~~ + +Operations that read, update, and delete documents from a collection can use +collations. This section includes examples of a selection of these. See the +MongoDB manual for a full list of :manual:`operations that support collation +`. + +find() and sort() Example +````````````````````````` + +The following example calls both ``find()`` and ``sort()`` on a collection +that uses the default binary collation. We use the German collation by +setting the value of the ``locale`` parameter to ``"de"``. + +.. literalinclude:: /code-snippets/collation/find-sort-collation.js + :language: javascript + :start-after: start find sort collation + :end-before: end find sort collation + +findOneAndUpdate() Example +`````````````````````````` + +The following example calls the ``findOneAndUpdate()`` operation on a +collection that uses the default binary collation. The collection contains the +following documents: + +.. code-block:: none + + { "_id" : 1, "first_name" : "Hans" } + { "_id" : 2, "first_name" : "Gunter" } + { "_id" : 3, "first_name" : "Günter" } + { "_id" : 4, "first_name" : "Jürgen" } + +Consider the following ``findOneAndUpdate()`` operation on this collection +which **does not** specify a collation: + +.. literalinclude:: /code-snippets/collation/findOneAndUpdate-default-order-collation.js + :language: javascript + :start-after: start findOneAndUpdate default order collation + :end-before: end findOneAndUpdate default order collation + +Since "Gunter" is the first sorted result when using a binary collation, none +of the documents come lexically before and match the ``$lt`` comparison +operator in the query document. As a result, the operation does not update any +documents. + +Consider the same operation with a collation specified with the locale set to +``de@collation=phonebook``. This locale specifies the ``collation=phonebook`` +option which contains rules for prioritizing proper nouns, identified by +capitalization of the first letter. The ``de@collation=phonebook`` locale and +option sorts characters with umlauts before the same characters without +umlauts. + +.. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js + :language: javascript + :start-after: start findOneAndUpdate collation + :end-before: end findOneAndUpdate collation + +Since "Günter" lexically comes before "Gunter" using the +``de@collation=phonebook`` collation specified in ``findOneAndUpdate()``, +the operation returns the following updated document: + +.. code-block:: none + + { lastErrorObject: { updatedExisting: true, n: 1 }, + value: { _id: 3, first_name: 'Günter' }, + ok: 1 } + +findOneAndDelete() Example +`````````````````````````` + +The following example calls the ``findOneAndDelete()`` operation on a +collection that uses the default binary collation and contains the following +documents: + +.. code-block:: none + + { "_id" : 1, "a" : "16" } + { "_id" : 2, "a" : "84" } + { "_id" : 3, "a" : "179" } + +In this example, we set the ``numericOrdering`` collation parameter to ``true`` +to sort numeric strings based on their numerical order instead of their +lexical order. + +.. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js + :language: javascript + :start-after: start findOneAndDelete collation + :end-before: end findOneAndDelete collation + +After you run the operation above, the collection contains the following +documents: + +.. code-block:: none + + { "_id" : 1, "a" : "16" } + { "_id" : 2, "a" : "84" } + +If you perform the same operation without collation on the original +collection of three documents, it matches documents based on the lexical value +of the strings (``"16"``, ``"84"``, and ``"179"``), and deletes the first +document it finds that matches the query criteria. + +.. literalinclude:: /code-snippets/collation/findOneAndDelete-no-collation.js + :language: javascript + :start-after: start findOneAndDelete no collation + :end-before: end findOneAndDelete no collation + +Since all the documents contain lexical values in the ``a`` field that +match the criteria (greater than the lexical value of ``"100"``), the operation +removes the first result. After you run the operation above, the collection +contains the following documents: + +.. code-block:: none + + { "_id" : 2, "a" : "84" } + { "_id" : 3, "a" : "179" } + +Aggregation Example +``````````````````` + +To use collation with the `aggregate <{+api+}/classes/Collection.html#aggregate>`__ +operation, pass the collation document in the options field, after the +array of pipeline stages. + +The following example shows an aggregation pipeline on a collection that uses +the default binary collation. The aggregation groups the ``first_name`` field, +counts the total number of results in each group, and sorts the results by +the German phonebook (``"de@collation=phonebook"`` locale) order. + +.. note:: + + You can specify only one collation on an aggregation. + +.. literalinclude:: /code-snippets/collation/aggregation-collation.js + :language: javascript + :start-after: start aggregation collation + :end-before: end aggregation collation diff --git a/source/fundamentals/crud/write-operations/delete.txt b/source/crud/delete.txt similarity index 99% rename from source/fundamentals/crud/write-operations/delete.txt rename to source/crud/delete.txt index cfb8c374a..fe388e822 100644 --- a/source/fundamentals/crud/write-operations/delete.txt +++ b/source/crud/delete.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-delete: +.. _node-delete: ================ Delete Documents diff --git a/source/fundamentals/gridfs.txt b/source/crud/gridfs.txt similarity index 99% rename from source/fundamentals/gridfs.txt rename to source/crud/gridfs.txt index 514f300b6..cd7cfc4b5 100644 --- a/source/fundamentals/gridfs.txt +++ b/source/crud/gridfs.txt @@ -168,7 +168,7 @@ see the following resources: - `find() API documentation <{+api+}/classes/GridFSBucket.html#find>`__ - `FindCursor API documentation <{+api+}/classes/FindCursor.html>`__ - :doc:`Cursor Fundamentals page ` -- :doc:`Read Operations page ` +- :doc:`Query Operations page ` .. _gridfs-download-files: diff --git a/source/fundamentals/crud/write-operations/insert.txt b/source/crud/insert.txt similarity index 99% rename from source/fundamentals/crud/write-operations/insert.txt rename to source/crud/insert.txt index d6da4aa81..daf2bda5d 100644 --- a/source/fundamentals/crud/write-operations/insert.txt +++ b/source/crud/insert.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-insert-data: +.. _node-insert: ================ Insert Documents diff --git a/source/fundamentals/crud/write-operations/pkFactory.txt b/source/crud/pkFactory.txt similarity index 100% rename from source/fundamentals/crud/write-operations/pkFactory.txt rename to source/crud/pkFactory.txt diff --git a/source/crud/query.txt b/source/crud/query.txt new file mode 100644 index 000000000..b8e793575 --- /dev/null +++ b/source/crud/query.txt @@ -0,0 +1,253 @@ +.. _node-read-operations: +.. _node-query: + +================ +Query Operations +================ + +.. meta:: + :description: Learn how to use {+driver-short+} to read data from MongoDB. + :keywords: usage examples, query, find, code example +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, node.js, sample dataset + +.. toctree:: + :maxdepth: 1 + + Find Documents + Specify Documents to Return + Specify Fields to Return + Specify a Query + Count Documents + Distinct Field Values + Search Text + Access Data from a Cursor + Geospatial Queries + +.. _nodejs-driver-retrieve-data-overview: + +Overview +-------- + +You can perform find operations to retrieve data from your MongoDB database. +You can perform a find operation to match documents on a set of criteria +by calling the ``find()`` or ``findOne()`` method. + +.. tip:: Interactive Lab + + This page includes a short interactive lab that demonstrates how to + retrieve data by using the ``find()`` method. You can complete this lab + directly in your browser window without installing MongoDB or a code editor. + + To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the + top of the page. To expand the lab to a full-screen format, click the + full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane. + +You can also further specify the information that the find operation +returns by specifying optional parameters or by chaining other methods, +as shown in the following guides: + +- :ref:`node-fundamentals-sort` +- :ref:`node-fundamentals-skip` +- :ref:`node-fundamentals-limit` +- :ref:`node-fundamentals-project` + +You can also use an aggregation operation to retrieve data. This type of +operation allows you to apply an ordered pipeline of transformations to the +matched data. + +If you want to monitor the database for incoming data that matches a set of +criteria, you can use the watch operation to be notified in real-time when +matching data is inserted. + +.. include:: /includes/access-cursor-note.rst + +.. |page-topic| replace:: perform read operations +.. |link-topic-ing| replace:: performing read operations in the Atlas UI + +.. |atlas-url| replace:: :atlas:`View, Filter, and Sort Documents ` + +.. include:: /includes/fact-atlas-compatible.rst +.. include:: /includes/fact-atlas-link.rst + +Find Documents +-------------- + +You can call the ``find()`` method on a ``Collection`` object. The +method accepts a query document that describes the documents you want to +retrieve. For more information on how to specify your query document, +see the :ref:`node-fundamentals-query-document` guide. + +.. tip:: No Query Criteria + + To execute a find operation that has no query criteria, you can + pass an empty query or omit the query document in your find + method parameters. + + The following operations both return all documents in the + ``myColl`` collection: + + .. code-block:: javascript + + myColl.find(); // no query + myColl.find({}); // empty query + + If you don't pass a query or pass an empty query + to the ``findOne()`` method, the operation returns a single + document from a collection. + + You can specify options in a find operation even when you pass an + empty query. For example, the following code shows how you can + specify a projection as an option while executing a find operation + that receives an empty query parameter: + + .. code-block:: javascript + + const options = { + projection: { _id: 0, field1: 1 }, + }; + + const findResult = await myColl.findOne({}, options); + + For more information about projecting document fields, see the + :ref:`node-fundamentals-project` guide. + +The ``find()`` method returns a ``Cursor`` instance from which you can +access the matched documents. The ``findOne()`` method returns a ``Promise`` +instance, which you can resolve to access either the matching document or +a ``null`` value if there are no matches. + +.. example:: + + A pizza restaurant wants to find all pizzas ordered by Lemony Snicket + yesterday. They run the following ``find()`` query on the + ``orders`` collection: + + .. literalinclude:: /code-snippets/crud/pizza.js + :language: javascript + :start-after: start find crud example + :end-before: end find crud example + + Once the operation returns, the ``findResult`` variable references a + ``Cursor``. You can print the documents retrieved using the ``for await...of`` + syntax as shown below: + + .. code-block:: javascript + + for await (const doc of findResult) { + console.log(doc); + } + + The output might resemble the following: + + .. code-block:: javascript + :copyable: false + + [ + { name: "Lemony Snicket", type: "horseradish pizza", qty: 1, status: "delivered", date: ... }, + { name: "Lemony Snicket", type: "coal-fired oven pizza", qty: 3, status: "canceled", date: ...}, + ... + ] + +Additional Information +~~~~~~~~~~~~~~~~~~~~~~ + +For runnable code examples that demonstrate find operations, see the following +usage examples: + +- :ref:`node-usage-findone` +- :ref:`node-usage-find` + +For more information about the ``findOne()`` and ``find()`` methods, see the +following Server manual documentation: + +- :manual:`findOne() ` +- :manual:`find() ` + +Aggregate Data from Documents +----------------------------- + +If you want to run a custom processing pipeline to retrieve data from your +database, you can use the ``aggregate()`` method. This method accepts +aggregation expressions to run in sequence. These expressions let you filter, +group, and arrange the result data from a collection. + +.. example:: + + A pizza restaurant wants to run a status report on-demand to + summarize pizza orders over the past week. They run the following + ``aggregate()`` query on the ``orders`` collection to fetch the + totals for each distinct "status" field: + + .. literalinclude:: /code-snippets/crud/pizza.js + :language: javascript + :start-after: start aggregate crud example + :end-before: end aggregate crud example + + Once the operation returns, the ``aggregateResult`` variable references a + ``Cursor``. You can print the documents retrieved using the ``for await...of`` + syntax as shown below: + + .. code-block:: javascript + + for await (const doc of aggregateResult) { + console.log(doc); + } + + The output might resemble the following: + + .. code-block:: javascript + :copyable: false + + [ + { _id: 'delivering', count: 5 }, + { _id: 'delivered', count: 37 }, + { _id: 'created', count: 9 } + ] + +Additional Information +~~~~~~~~~~~~~~~~~~~~~~ + +For more information on how to construct an aggregation pipeline, see +the :ref:`node-aggregation` guide or :manual:`Aggregation Operations ` +in the Server manual. + +.. _node-fundamentals-watch: + +Monitor Data Changes +-------------------- + +You can use the ``watch()`` method to monitor a collection for changes to +a collection that match certain criteria. These changes include inserted, +updated, replaced, and deleted documents. You can pass this method +a pipeline of aggregation commands that sequentially runs on the changed +data whenever write operations are executed on the collection. + +.. example:: + + A pizza restaurant wants to receive a notification whenever a new pizza + order comes in. To accomplish this, they create an aggregation pipeline + to filter on insert operations and return specific fields. They pass + this pipeline to the ``watch()`` method called on the ``orders`` + collection as shown below: + + .. literalinclude:: /code-snippets/crud/pizza.js + :language: javascript + :start-after: start watch crud example + :end-before: end watch crud example + +Additional Information +~~~~~~~~~~~~~~~~~~~~~~ + +For a runnable example of the ``watch()`` method, see the +:ref:`Watch for Changes ` usage example. + +.. _node-retrieve-instruqt-lab: + +.. instruqt:: /mongodb-docs/tracks/find-node?token=em_OVNHWCPNPMLwNOCm + :title: find() Lesson + :drawer: \ No newline at end of file diff --git a/source/usage-examples/count.txt b/source/crud/query/count.txt similarity index 99% rename from source/usage-examples/count.txt rename to source/crud/query/count.txt index d995917fd..e272af18d 100644 --- a/source/usage-examples/count.txt +++ b/source/crud/query/count.txt @@ -1,4 +1,5 @@ .. _node-usage-count: +.. _node-count: =============== Count Documents diff --git a/source/fundamentals/crud/read-operations/cursor.txt b/source/crud/query/cursor.txt similarity index 99% rename from source/fundamentals/crud/read-operations/cursor.txt rename to source/crud/query/cursor.txt index d3360c592..bbe4212fa 100644 --- a/source/fundamentals/crud/read-operations/cursor.txt +++ b/source/crud/query/cursor.txt @@ -1,4 +1,5 @@ .. _node-access-cursor: +.. _node-cursor: ========================= Access Data From a Cursor diff --git a/source/fundamentals/crud/read-operations/distinct.txt b/source/crud/query/distinct.txt similarity index 99% rename from source/fundamentals/crud/read-operations/distinct.txt rename to source/crud/query/distinct.txt index 6280fdb4d..96aa5ca06 100644 --- a/source/fundamentals/crud/read-operations/distinct.txt +++ b/source/crud/query/distinct.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-distinct: +.. _node-distinct: ======================== Retrieve Distinct Values diff --git a/source/fundamentals/crud/read-operations/geo.txt b/source/crud/query/geo.txt similarity index 98% rename from source/fundamentals/crud/read-operations/geo.txt rename to source/crud/query/geo.txt index 8c5a29a6c..856df7290 100644 --- a/source/fundamentals/crud/read-operations/geo.txt +++ b/source/crud/query/geo.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-geospatial: +.. _node-geospatial: =================== Search Geospatially @@ -110,7 +111,7 @@ Examples -------- The following examples use the MongoDB Atlas sample dataset. You can learn how to set up your own free-tier Atlas cluster and how to load the sample dataset in our -:doc:`quick start guide `. +:doc:`get started guide `. The examples use the ``theaters`` collection in the ``sample_mflix`` database from the sample dataset. The ``theaters`` collection contains a ``2dsphere`` index diff --git a/source/fundamentals/crud/read-operations/project.txt b/source/crud/query/project.txt similarity index 99% rename from source/fundamentals/crud/read-operations/project.txt rename to source/crud/query/project.txt index 1f23bbc39..1581a8cf1 100644 --- a/source/fundamentals/crud/read-operations/project.txt +++ b/source/crud/query/project.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-project: +.. _node-project: ============================== Specify Which Fields to Return diff --git a/source/fundamentals/crud/query-document.txt b/source/crud/query/query-document.txt similarity index 99% rename from source/fundamentals/crud/query-document.txt rename to source/crud/query/query-document.txt index c5ce1852e..d9835dcdc 100644 --- a/source/fundamentals/crud/query-document.txt +++ b/source/crud/query/query-document.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-query-document: +.. _node-query-document: =============== Specify a Query diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/crud/query/retrieve.txt similarity index 98% rename from source/fundamentals/crud/read-operations/retrieve.txt rename to source/crud/query/retrieve.txt index 59cfcf8c6..585d920b6 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -1,8 +1,9 @@ .. _node-fundamentals-retrieve-data: +.. _node-find: -============= -Retrieve Data -============= +============== +Find Documents +============== .. facet:: :name: genre @@ -64,8 +65,8 @@ matching data is inserted. .. include:: /includes/fact-atlas-compatible.rst .. include:: /includes/fact-atlas-link.rst -Find Documents --------------- +Finding Documents +----------------- You can call the ``find()`` method on a ``Collection`` object. The method accepts a query document that describes the documents you want to diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt new file mode 100644 index 000000000..508f266ea --- /dev/null +++ b/source/crud/query/specify-documents-to-return.txt @@ -0,0 +1,28 @@ +.. _node-specify-documents-to-return: + +=========================== +Specify Documents to Return +=========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, paginate, pagination, order, code example + +Overview +-------- + +In this guide, you can learn how to specify which documents to return from a read +operation by using the following methods: + +- ``limit``: Specifies the maximum number of documents to return from a query. +- ``sort``: Specifies the sort order for the returned documents. +- ``skip``: Specifies the number of documents to skip before returning query results. \ No newline at end of file diff --git a/source/fundamentals/crud/read-operations/text.txt b/source/crud/query/text.txt similarity index 99% rename from source/fundamentals/crud/read-operations/text.txt rename to source/crud/query/text.txt index 2eb869b33..ae3d65200 100644 --- a/source/fundamentals/crud/read-operations/text.txt +++ b/source/crud/query/text.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-text: +.. _node-search-text: =========== Search Text diff --git a/source/fundamentals/crud/read-write-pref.txt b/source/crud/read-write-pref.txt similarity index 100% rename from source/fundamentals/crud/read-write-pref.txt rename to source/crud/read-write-pref.txt diff --git a/source/fundamentals/transactions.txt b/source/crud/transactions.txt similarity index 99% rename from source/fundamentals/transactions.txt rename to source/crud/transactions.txt index 41e3c9214..cc983373d 100644 --- a/source/fundamentals/transactions.txt +++ b/source/crud/transactions.txt @@ -1,4 +1,5 @@ .. _nodejs-transactions: +.. _node-transactions: ============ Transactions diff --git a/source/fundamentals/crud/write-operations/upsert.txt b/source/crud/update.txt similarity index 93% rename from source/fundamentals/crud/write-operations/upsert.txt rename to source/crud/update.txt index ad400ded8..fbf2dd272 100644 --- a/source/fundamentals/crud/write-operations/upsert.txt +++ b/source/crud/update.txt @@ -1,8 +1,9 @@ .. _node-fundamentals-upsert: +.. _node-update: -====================================== -Insert or Update in a Single Operation -====================================== +================ +Update Documents +================ .. facet:: :name: genre @@ -18,6 +19,14 @@ Insert or Update in a Single Operation :depth: 1 :class: singlecol +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Modify Documents + Replace + Update Arrays + Overview -------- diff --git a/source/fundamentals/crud/write-operations/embedded-arrays.txt b/source/crud/update/embedded-arrays.txt similarity index 99% rename from source/fundamentals/crud/write-operations/embedded-arrays.txt rename to source/crud/update/embedded-arrays.txt index 668944b9e..2917e3e6f 100644 --- a/source/fundamentals/crud/write-operations/embedded-arrays.txt +++ b/source/crud/update/embedded-arrays.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-update-array: +.. _node-update-arrays: =========================== Update Arrays in a Document diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/crud/update/modify.txt similarity index 95% rename from source/fundamentals/crud/write-operations/modify.txt rename to source/crud/update/modify.txt index 06624209d..b4bef4ad8 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/crud/update/modify.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-change-a-document: +.. _node-modify: ================ Modify Documents @@ -133,11 +134,10 @@ the ``quantity`` field and all other values unchanged: quantity: 5, } -If an update operation fails to match any documents in a collection, it -does not make any changes. Update operations can be configured to perform -an :doc:`upsert ` which -attempts to perform an update, but if no documents are matched, inserts -a new document with the specified fields and values. +If an update operation fails to match any documents in a collection, it does not +make any changes. Update operations can be configured to perform an :doc:`upsert +` which attempts to perform an update, but if no documents are +matched, inserts a new document with the specified fields and values. You cannot modify the ``_id`` field of a document nor change a field to a value that violates a unique index constraint. See the {+mdb-server+} manual @@ -216,7 +216,7 @@ and the immutable ``_id`` field as follows: If a replace operation fails to match any documents in a collection, it does not make any changes. Replace operations can be configured to perform -an :doc:`upsert ` which +an :doc:`upsert ` which attempts to perform the replacement, but if no documents are matched, it inserts a new document with the specified fields and values. diff --git a/source/crud/update/replace.txt b/source/crud/update/replace.txt new file mode 100644 index 000000000..741b2a854 --- /dev/null +++ b/source/crud/update/replace.txt @@ -0,0 +1,21 @@ +.. _node-replace: + +================= +Replace Documents +================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, node.js, write, add data, change + +Overview +-------- + +In this guide, you can learn how to use {+driver-short+} to perform a replace +operation on a document in a MongoDB collection. A replace operation performs +differently than an update operation. An update operation +modifies only the specified fields in a target document. A replace operation removes *all* fields +in the target document and replaces them with new ones. \ No newline at end of file diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 000000000..4a0c516fd --- /dev/null +++ b/source/data-formats.txt @@ -0,0 +1,35 @@ +.. _node-data-formats: + +======================== +Specialized Data Formats +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: bson, uuid, date, time + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + BSON + Time Series Data + +Overview +-------- + +You can use several types of specialized data formats in your {+driver-short+} +application. To learn how to work with these data formats, see the following +sections: + +- Learn how to work with BSON documents in the :ref:`node-bson` guide +- Learn how to work with time series data in the :ref:`node-time-series` guide \ No newline at end of file diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt new file mode 100644 index 000000000..2e76a802b --- /dev/null +++ b/source/data-formats/bson.txt @@ -0,0 +1,25 @@ +.. _node-bson-control: +.. _node-bson: + +==== +BSON +==== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to create BSON documents, read BSON from a file, +and write BSON to a file by using {+driver-short+}. + +**BSON**, or Binary JSON, is the data format that MongoDB uses to organize +and store data. This data format includes all JSON data structure types and +adds support for types including dates, different size integers, ObjectIds, and +binary data. \ No newline at end of file diff --git a/source/fundamentals/time-series.txt b/source/data-formats/time-series.txt similarity index 95% rename from source/fundamentals/time-series.txt rename to source/data-formats/time-series.txt index db1789766..6668a7d77 100644 --- a/source/fundamentals/time-series.txt +++ b/source/data-formats/time-series.txt @@ -1,3 +1,5 @@ +.. _node-time-series: + =========== Time Series =========== @@ -39,7 +41,7 @@ querying time series data. For more information on querying data in the MongoDB Node.js driver, see the following resources: -- :ref:`Guide On Read Operations ` +- :ref:`Guide On Read Operations ` - :ref:`Guide On Aggregation ` .. note:: Window Functions diff --git a/source/fundamentals/bson.txt b/source/fundamentals/bson.txt deleted file mode 100644 index 145f875b4..000000000 --- a/source/fundamentals/bson.txt +++ /dev/null @@ -1,31 +0,0 @@ -.. _node-bson-control: - -============= -BSON Settings -============= - -.. meta:: - :description: Configure BSON serialization settings in your application with the MongoDB Node.js Driver, including handling undefined values and UTF-8 validation. - -.. toctree:: - :caption: BSON settings - - Undefined Values - UTF-8 Validation - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -Overview --------- - -Learn how to configure your application's BSON serialization settings. -The guides in this section describe the following topics: - -- :ref:`Undefined Values `: Control how the - driver serializes undefined values -- :ref:`UTF-8 Validation `: Enable or disable - the UTF-8 validation feature diff --git a/source/fundamentals/crud.txt b/source/fundamentals/crud.txt deleted file mode 100644 index daa80f8aa..000000000 --- a/source/fundamentals/crud.txt +++ /dev/null @@ -1,57 +0,0 @@ -.. _node-crud-landing: - -=============== -CRUD Operations -=============== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :description: Learn how to perform create, read, update, and delete (CRUD) operations to work with the data stored in MongoDB by using the Node.js driver. - :keywords: node.js - -.. toctree:: - :caption: CRUD Operations - - Read - Write - Query - Compound Operations - Operations on Replica Sets - -CRUD (Create, Read, Update, Delete) operations allow you to work with -the data stored in MongoDB. - -The CRUD operation documentation is categorized in two sections: - -- :doc:`Read Operations ` find and return - documents stored within your MongoDB database. -- :doc:`Write Operations ` insert, modify, - or delete documents in your MongoDB database. - -Some operations combine aspects of read and write operations. See our -guide on :doc:`compound operations ` -to learn more about these hybrid methods. - -Compatibility -------------- - -.. |page-topic| replace:: perform CRUD operations -.. |link-topic-ing| replace:: performing CRUD operations in the Atlas UI - -.. |atlas-url| replace:: :atlas:`Create, View, Update, and Delete Documents ` - -.. include:: /includes/fact-atlas-compatible.rst -.. include:: /includes/fact-atlas-link.rst - -.. note:: - - To learn more about performing CRUD operations, see the following posts on the `MongoDB - Developer Hub `__: - - - Learn how to apply `CRUD Operations `__ - with an example scenario. - - Analyze data in MongoDB Atlas using the `Aggregation Pipeline `__. - diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt deleted file mode 100644 index 749c06a20..000000000 --- a/source/fundamentals/crud/read-operations.txt +++ /dev/null @@ -1,38 +0,0 @@ -.. _node-read-operations: - -=============== -Read Operations -=============== - -.. meta:: - :description: Learn about the commands for running MongoDB read operations by using the {+driver-long+}. - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, node.js, sample dataset - -.. toctree:: - :caption: Read Operations - - Retrieve Data - Access Data from a Cursor - Distinct Values - Sort Results - Skip Returned Results - Limit Returned Results - Specify Fields to Return - Search Geospatially - Search Text - -- :doc:`/fundamentals/crud/read-operations/retrieve` -- :doc:`/fundamentals/crud/read-operations/cursor` -- :doc:`/fundamentals/crud/read-operations/distinct` -- :doc:`/fundamentals/crud/read-operations/sort` -- :doc:`/fundamentals/crud/read-operations/skip` -- :doc:`/fundamentals/crud/read-operations/limit` -- :doc:`/fundamentals/crud/read-operations/project` -- :doc:`/fundamentals/crud/read-operations/geo` -- :doc:`/fundamentals/crud/read-operations/text` diff --git a/source/fundamentals/crud/write-operations.txt b/source/fundamentals/crud/write-operations.txt index 018d07b71..18b3fd807 100644 --- a/source/fundamentals/crud/write-operations.txt +++ b/source/fundamentals/crud/write-operations.txt @@ -17,7 +17,6 @@ Write Operations Upsert Bulk Operations -- :doc:`/fundamentals/crud/write-operations/insert` - :doc:`/fundamentals/crud/write-operations/pkFactory` - :doc:`/fundamentals/crud/write-operations/delete` - :doc:`/fundamentals/crud/write-operations/modify` diff --git a/source/get-started.txt b/source/get-started.txt new file mode 100644 index 000000000..c9de8be9a --- /dev/null +++ b/source/get-started.txt @@ -0,0 +1,229 @@ +.. _node-get-started: + +============================ +Getting Started with Node.js +============================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :description: Learn how to create an app to connect to MongoDB deployment by using the Node.js driver. + :keywords: node.js + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +This guide shows you how to create an application that uses the +{+driver-long+} to connect to a MongoDB cluster hosted on MongoDB Atlas. If +you prefer to connect to MongoDB using a different driver or programming +language, see our :driver:`list of official drivers <>`. + +The {+driver-short+} is a library of functions that you can use to connect +to and communicate with MongoDB. + +MongoDB Atlas is a fully managed cloud database service that hosts your +MongoDB deployments. You can create your own free (no credit card +required) MongoDB Atlas deployment by following the steps in this guide. + +Follow the steps in this guide to connect a sample Node.js application to +a MongoDB Atlas deployment. + +.. _node-quick-start-download-and-install: +.. _node-get-started-download-and-install: + +Download and Install +-------------------- + +.. procedure:: + :style: connected + + .. step:: Install Node and npm + + Ensure you have Node.js {+min-node-version+} or later and + npm (Node Package Manager) installed in your development environment. + + For information on how to install Node.js and npm, see + `downloading and installing Node.js and npm `__. + + .. step:: Create a Project Directory + + In your shell, run the following command to create a + directory called ``node_quickstart`` for this project: + + .. code-block:: bash + + mkdir node_quickstart + + Run the following command to navigate into the project + directory: + + .. code-block:: bash + + cd node_quickstart + + Run the following command to initialize your Node.js project: + + .. code-block:: bash + + npm init -y + + When this command successfully completes, you have a ``package.json`` + file in your ``node_quickstart`` directory. + + + .. step:: Install the Node.js Driver + + Run the following command in your shell to install + the driver in your project directory: + + .. code-block:: bash + + npm install mongodb@{+version+} + + This command performs the following actions: + + - Downloads the ``mongodb`` package and the dependencies it requires + - Saves the package in the ``node_modules`` directory + - Records the dependency information in the ``package.json`` file + +After you complete these steps, you have Node.js and npm installed +and a new project directory with the driver dependencies installed. + +.. include:: /includes/quick-start/troubleshoot.rst + +.. _node-quick-start-create-deployment: +.. _node-get-started-create-deployment: + +Create a MongoDB Deployment +--------------------------- + +You can create a free tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a Free MongoDB deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and load sample data into a new free + tier MongoDB deployment. + + .. step:: Save your Credentials + + After you create your database user, save that user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +in your database. + +.. include:: /includes/quick-start/troubleshoot.rst + +.. _node-quick-start-connect-to-mongodb: +.. _node-get-started-connect-to-mongodb: + +Connect to MongoDB +------------------ + +.. procedure:: + :style: connected + + .. step:: Create your Node.js Application + + Create a file to contain your application called ``index.js`` in your + ``node_quickstart`` project directory. + + Copy and paste the following code into the ``index.js`` file: + + .. code-block:: js + + const { MongoClient } = require("mongodb"); + + // Replace the uri string with your connection string. + const uri = ""; + + const client = new MongoClient(uri); + + async function run() { + try { + const database = client.db('sample_mflix'); + const movies = database.collection('movies'); + + // Query for a movie that has the title 'Back to the Future' + const query = { title: 'Back to the Future' }; + const movie = await movies.findOne(query); + + console.log(movie); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } + } + run().catch(console.dir); + + .. step:: Assign the Connection String + + Replace the ```` placeholder with the + connection string that you copied from the :ref:`node-quick-start-connection-string` + step of this guide. + + .. step:: Run your Node.js Application + + In your shell, run the following command to start this application: + + .. code-block:: none + + node index.js + + The output includes details of the retrieved movie document: + + .. code-block:: none + + { + _id: ..., + plot: 'A young man is accidentally sent 30 years into the past...', + genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], + ... + title: 'Back to the Future', + ... + } + + If you encounter an error or see no output, check whether you specified the + proper connection string in the ``index.js`` file, and that you loaded the + sample data. + +After you complete these steps, you have a working application that +uses the driver to connect to your MongoDB deployment, runs a query on +the sample data, and prints out the result. + +.. include:: /includes/quick-start/troubleshoot.rst + +.. _node-quick-start-next-steps: +.. _node-get-started-next-steps: + +Next Steps +---------- + +Congratulations on completing the quick start tutorial! + +In this tutorial, you created a Node.js application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +Learn more about the {+driver-long+} from the following resources: + +- Discover how to perform read and write operations in the + :ref:`CRUD Operations ` section. + +- See examples of frequently-used operations in the + :ref:`Usage Examples ` section. \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 7cc4d3878..ae549854d 100644 --- a/source/index.txt +++ b/source/index.txt @@ -16,19 +16,19 @@ MongoDB Node Driver :titlesonly: :maxdepth: 1 - Quick Start - Quick Reference - What's New - Usage Examples - Fundamentals - Aggregation Tutorials + Get Started + Connect + CRUD Operations + Aggregation + Data Formats + Indexes + Run a Database Command + Monitoring and Logging + Security + Reference + Typescript API Documentation <{+api+}> - FAQ - Connection Troubleshooting Issues & Help - Compatibility - Upgrade - Release Notes View the Source Introduction @@ -38,88 +38,83 @@ Welcome to the documentation site for the official {+driver-long+}. You can add the driver to your application to work with MongoDB in JavaScript or TypeScript. For more information about downloading and installing the {+driver-short+}, see -:ref:`Download and Install ` in the -Quick Start guide. +:ref:`Download and Install ` in the +Get Started guide. You can connect using the {+driver-short+} for deployments hosted in the following environments: .. include:: /includes/fact-environments.rst -Quick Start +Get Started ----------- Learn how to establish a connection to MongoDB Atlas and begin -working with data in the step-by-step :doc:`Quick Start `. +working with data in the step-by-step :doc:`Get Started ` tutorial. -Quick Reference ---------------- +Connect to MongoDB +------------------ -See driver syntax examples for common MongoDB commands in the -:ref:`Quick Reference ` section. +Learn how to create and configure a connection to a MongoDB deployment in the +:ref:`` section. -What's New ----------- +Read and Write Data +------------------- -For a list of new features and changes in each version, see the -:ref:`What's New ` section. +Learn how to find, update, and delete data in the :ref:`` section. -Usage Examples --------------- +Transform Your Data with Aggregation +------------------------------------- -For fully runnable code snippets and explanations for common -methods, see the :doc:`Usage Examples ` section. +Learn how to use the {+driver-short+} to perform aggregation operations in the +:ref:`` section. -Fundamentals +Data Formats ------------ -.. include:: /includes/fundamentals-sections.rst +Learn how to work with BSON and other data formats in the +:ref:`` section. -Aggregation Tutorials ---------------------- +Optimize Queries with Indexes +----------------------------- -For step-by-step explanations of common -aggregation tasks, see the :ref:`node-aggregation-tutorials-landing` -section. +Learn how to work with common types of indexes in the :ref:`` section. -API ---- +Run a Database Command +---------------------- -For detailed information about classes and methods in the MongoDB -Node.js driver, see the `{+driver-long+} API documentation -<{+api+}>`__. +Learn how to run a database command in the :ref:`` section. -FAQ ---- +Monitoring and Logging +---------------------- -For answers to commonly asked questions about the MongoDB -Node.js Driver, see the :doc:`Frequently Asked Questions (FAQ) ` -section. +Learn how to monitor changes to your application and write them to logs in the +:ref:`` section. -Connection Troubleshooting --------------------------- +Secure Your Data +---------------- -For solutions to issues you might encounter when using the driver to connect to -a MongoDB deployment, see the :ref:`node-connection-troubleshooting` section. +Learn about ways you can authenticate your application and encrypt your data in +the :ref:`` section. -Issues & Help -------------- +Reference +--------- -Learn how to report bugs, contribute to the driver, and to find help in the -:doc:`Issues & Help ` section. +Find more information about {+driver-short+} versions, compatibility, and third-party tools in the +:doc:`Reference ` section. -Compatibility -------------- +API Documentation +----------------- -For the compatibility tables that show the recommended {+driver-short+} -version for each {+mdb-server+} version, see the -:doc:`Compatibility ` section. +For detailed information about classes and methods in the MongoDB +Node.js driver, see the `{+driver-long+} API documentation +<{+api+}>`__. -Upgrade Driver Versions ------------------------ +Issues & Help +------------- -Learn what changes you must make to your application to upgrade -driver versions in the :ref:`` section. +Learn how to report bugs, contribute to the driver, and to find help in the +:doc:`Issues & Help ` section. Related Tools and Libraries --------------------------- diff --git a/source/fundamentals/indexes.txt b/source/indexes.txt similarity index 99% rename from source/fundamentals/indexes.txt rename to source/indexes.txt index a01303115..fe9762ee1 100644 --- a/source/fundamentals/indexes.txt +++ b/source/indexes.txt @@ -1,4 +1,5 @@ .. _node-fundamentals-indexes: +.. _node-indexes: ======= Indexes @@ -259,7 +260,7 @@ MongoDB supports queries of geospatial coordinate data using **2dsphere indexes**. With a 2dsphere index, you can query the geospatial data for inclusion, intersection, and proximity. For more information on querying geospatial data with the MongoDB Node.js driver, read our -:doc:`Search Geospatial ` guide. +:doc:`Search Geospatial ` guide. To create a 2dsphere index, you must specify a field that contains only **GeoJSON objects**. For more details on this type, see the MongoDB diff --git a/source/monitoring-and-logging.txt b/source/monitoring-and-logging.txt new file mode 100644 index 000000000..f3e5e66cc --- /dev/null +++ b/source/monitoring-and-logging.txt @@ -0,0 +1,24 @@ +.. _node-monitoring-logging: + +====================== +Monitoring and Logging +====================== + +.. facet:: + :name: programming_language + :values: python + +.. meta:: + :keywords: event + +.. toctree:: + + Monitoring + Logging + Change Streams + +Overview +-------- + +On this page, you can see copyable code examples that show common +methods you can use to monitor and log events with {+driver-short+}. \ No newline at end of file diff --git a/source/usage-examples/changeStream.txt b/source/monitoring-and-logging/change-streams.txt similarity index 93% rename from source/usage-examples/changeStream.txt rename to source/monitoring-and-logging/change-streams.txt index 7d72a9479..e16fd4226 100644 --- a/source/usage-examples/changeStream.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -1,14 +1,36 @@ .. _node-usage-watch: +.. _node-change-streams: -================= -Watch for Changes -================= +==================== +Monitor Data Changes +==================== .. meta:: :description: Monitor changes in MongoDB using the watch() method in the MongoDB Node.js Driver on collections, databases, or clients to open change streams and handle change events. .. default-domain:: mongodb +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: watch, code example + +Overview +-------- + +In this guide, you can learn how to use a **change stream** to monitor real-time +changes to your database. A change stream is a {+mdb-server+} feature that +allows your application to subscribe to data changes on a collection, database, +or deployment. + Open a Change Stream -------------------- diff --git a/source/fundamentals/logging.txt b/source/monitoring-and-logging/logging.txt similarity index 100% rename from source/fundamentals/logging.txt rename to source/monitoring-and-logging/logging.txt diff --git a/source/fundamentals/monitoring.txt b/source/monitoring-and-logging/monitoring.txt similarity index 97% rename from source/fundamentals/monitoring.txt rename to source/monitoring-and-logging/monitoring.txt index cd132fa24..3d329071c 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/monitoring-and-logging/monitoring.txt @@ -1,3 +1,5 @@ +.. _node-monitoring: + ========== Monitoring ========== diff --git a/source/quick-start.txt b/source/quick-start.txt deleted file mode 100644 index 0ebfed6a7..000000000 --- a/source/quick-start.txt +++ /dev/null @@ -1,45 +0,0 @@ -.. _node-quickstart: - -======================= -Node Driver Quick Start -======================= - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :description: Learn how to create an app to connect to MongoDB deployment by using the Node.js driver. - :keywords: node.js - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. toctree:: - - Download & Install - Create a Deployment - Create a Connection String - Connect to MongoDB - Next Steps - -Overview --------- - -This guide shows you how to create an application that uses the -{+driver-long+} to connect to a MongoDB cluster hosted on MongoDB Atlas. If -you prefer to connect to MongoDB using a different driver or programming -language, see our :driver:`list of official drivers <>`. - -The {+driver-short+} is a library of functions that you can use to connect -to and communicate with MongoDB. - -MongoDB Atlas is a fully managed cloud database service that hosts your -MongoDB deployments. You can create your own free (no credit card -required) MongoDB Atlas deployment by following the steps in this guide. - -Follow the steps in this guide to connect a sample Node.js application to -a MongoDB Atlas deployment. diff --git a/source/reference.txt b/source/reference.txt new file mode 100644 index 000000000..937e7fe88 --- /dev/null +++ b/source/reference.txt @@ -0,0 +1,14 @@ +.. _node-reference: + +========== +Reference +========== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Release Notes + Compatibility + Upgrade Guides + Quick Reference diff --git a/source/compatibility.txt b/source/reference/compatibility.txt similarity index 100% rename from source/compatibility.txt rename to source/reference/compatibility.txt diff --git a/source/quick-reference.txt b/source/reference/quick-reference.txt similarity index 99% rename from source/quick-reference.txt rename to source/reference/quick-reference.txt index 000b93190..6cb1c5c21 100644 --- a/source/quick-reference.txt +++ b/source/reference/quick-reference.txt @@ -39,7 +39,7 @@ Compatibility | | `API Documentation <{+api+}/classes/Collection.html#findOne>`__ | :ref:`Usage Example ` - | :ref:`Fundamentals ` + | :ref:`Query Operations ` - .. io-code-block:: :copyable: true diff --git a/source/whats-new.txt b/source/reference/release-notes.txt similarity index 99% rename from source/whats-new.txt rename to source/reference/release-notes.txt index fa6215295..1701e138c 100644 --- a/source/whats-new.txt +++ b/source/reference/release-notes.txt @@ -1,8 +1,9 @@ .. _node-whats-new: +.. _node-release-notes: -========== -What's New -========== +============= +Release Notes +============= .. contents:: On this page :local: diff --git a/source/upgrade.txt b/source/reference/upgrade.txt similarity index 100% rename from source/upgrade.txt rename to source/reference/upgrade.txt diff --git a/source/fundamentals/run-command.txt b/source/run-command.txt similarity index 100% rename from source/fundamentals/run-command.txt rename to source/run-command.txt diff --git a/source/security.txt b/source/security.txt new file mode 100644 index 000000000..ec4c2872c --- /dev/null +++ b/source/security.txt @@ -0,0 +1,34 @@ +.. _node-security: + +========= +Security +========= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: ldap, encryption, principal, tls, authorize, boto, ecs, aws + :description: Learn how to use {+driver-short+} to secure your data. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Authentication + In-Use Encryption + TLS Security Protocol + SOCKS Proxy + +Overview +-------- + +MongoDB supports multiple mechanisms that you can use to authenticate your application. +This page contains code examples that show each of these mechanisms. \ No newline at end of file diff --git a/source/fundamentals/authentication.txt b/source/security/authentication.txt similarity index 76% rename from source/fundamentals/authentication.txt rename to source/security/authentication.txt index 2a6c3ef6f..0ec2bd2c9 100644 --- a/source/fundamentals/authentication.txt +++ b/source/security/authentication.txt @@ -1,4 +1,5 @@ .. _node-authentication-mechanisms: +.. _node-authentication: ============== Authentication @@ -11,8 +12,8 @@ Authentication .. toctree:: - Authentication - Enterprise Authentication + Authentication + Enterprise Authentication Overview -------- @@ -20,7 +21,7 @@ Overview These guides show you how to authenticate to a MongoDB instance using the Node.js driver. -The :doc:`Authentication Mechanisms ` guide contains +The :doc:`Authentication Mechanisms ` guide contains sample connection code using each authentication mechanism supported in the MongoDB Community Edition which includes: @@ -32,7 +33,7 @@ MongoDB Community Edition which includes: - ``X.509`` The :doc:`Enterprise Authentication Mechanisms -` guide contains sample +` guide contains sample connection code using authentication mechanisms available only in MongoDB Enterprise Edition which includes: diff --git a/source/fundamentals/authentication/enterprise-mechanisms.txt b/source/security/authentication/enterprise-mechanisms.txt similarity index 100% rename from source/fundamentals/authentication/enterprise-mechanisms.txt rename to source/security/authentication/enterprise-mechanisms.txt diff --git a/source/fundamentals/authentication/mechanisms.txt b/source/security/authentication/mechanisms.txt similarity index 100% rename from source/fundamentals/authentication/mechanisms.txt rename to source/security/authentication/mechanisms.txt diff --git a/source/fundamentals/encrypt-fields.txt b/source/security/encrypt-fields.txt similarity index 100% rename from source/fundamentals/encrypt-fields.txt rename to source/security/encrypt-fields.txt diff --git a/source/fundamentals/connection/socks.txt b/source/security/socks.txt similarity index 99% rename from source/fundamentals/connection/socks.txt rename to source/security/socks.txt index 44b650a1b..ce3623dde 100644 --- a/source/fundamentals/connection/socks.txt +++ b/source/security/socks.txt @@ -1,4 +1,5 @@ .. _node-connect-socks: +.. _node-socks: =========================== Enable SOCKS5 Proxy Support diff --git a/source/fundamentals/connection/tls.txt b/source/security/tls.txt similarity index 99% rename from source/fundamentals/connection/tls.txt rename to source/security/tls.txt index 0a922e0de..e80eaff1e 100644 --- a/source/fundamentals/connection/tls.txt +++ b/source/security/tls.txt @@ -1,4 +1,5 @@ .. _node-connect-tls: +.. _node-tls: ========================== Enable TLS on a Connection diff --git a/source/fundamentals/typescript.txt b/source/typescript.txt similarity index 99% rename from source/fundamentals/typescript.txt rename to source/typescript.txt index 872c23de9..e40f58b0b 100644 --- a/source/fundamentals/typescript.txt +++ b/source/typescript.txt @@ -1,4 +1,5 @@ -.. node-fundamentals-typescript: +.. _node-fundamentals-typescript: +.. _node-typescript: ========== TypeScript @@ -204,7 +205,7 @@ To learn more about the limitations of dot notation in the :ref:`` section. -.. typescript-working-with-id: +.. _node-typescript-working-with-id: Working with the _id Field -------------------------- diff --git a/source/usage-examples.txt b/source/usage-examples.txt index 7b44da38d..f3c6d6e6b 100644 --- a/source/usage-examples.txt +++ b/source/usage-examples.txt @@ -59,7 +59,7 @@ can :guides:`import the sample dataset into a local MongoDB instance Once you have imported the dataset, you can copy and paste a usage example into your development environment of choice. You can follow the -:doc:`quick start guide ` to learn more about getting +:doc:`get started guide ` to learn more about getting started with Node.js, npm, and the Node.js driver. Once you've copied a usage example, you must edit one line to get the example running with your instance of MongoDB: @@ -121,9 +121,10 @@ Available Usage Examples - :doc:`Insert Operations ` - :doc:`Update Operations ` - :doc:`Delete Operations ` -- :doc:`Count Documents ` - :doc:`Retrieve Distinct Values of a Field ` - :doc:`Run a Command ` -- :doc:`Watch for Changes ` - :doc:`Perform Bulk Operations ` - :doc:`Perform a Transaction ` + +.. - :doc:`Count Documents ` +.. - :doc:`Watch for Changes ` From 1f9e8f5f9c0b509d60f979897fb7ac9e99ab127f Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 19 Mar 2025 17:17:58 -0400 Subject: [PATCH 02/26] DOCSP-48376: Get Started edits (#1039) * DOCSP-48376: Get Started edits * edits * RR feedback --- source/get-started.txt | 156 +++++++++++------- .../atlas_connection_connect_cluster.png | Bin 0 -> 81158 bytes .../atlas_connection_copy_uri_node.png | Bin 0 -> 136330 bytes 3 files changed, 99 insertions(+), 57 deletions(-) create mode 100644 source/includes/figures/atlas_connection_connect_cluster.png create mode 100644 source/includes/figures/atlas_connection_copy_uri_node.png diff --git a/source/get-started.txt b/source/get-started.txt index c9de8be9a..9aa18ee8a 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -1,8 +1,8 @@ .. _node-get-started: -============================ -Getting Started with Node.js -============================ +======================================= +Getting Started with the Node.js Driver +======================================= .. facet:: :name: genre @@ -22,19 +22,19 @@ Overview -------- This guide shows you how to create an application that uses the -{+driver-long+} to connect to a MongoDB cluster hosted on MongoDB Atlas. If -you prefer to connect to MongoDB using a different driver or programming -language, see our :driver:`list of official drivers <>`. - +{+driver-long+} to connect to a MongoDB cluster hosted on MongoDB Atlas. The {+driver-short+} is a library of functions that you can use to connect to and communicate with MongoDB. -MongoDB Atlas is a fully managed cloud database service that hosts your -MongoDB deployments. You can create your own free (no credit card -required) MongoDB Atlas deployment by following the steps in this guide. +.. tip:: + + MongoDB Atlas is a fully managed cloud database service that hosts your + MongoDB deployments. You can create your own free (no credit card + required) MongoDB Atlas deployment by following the steps in this guide. Follow the steps in this guide to connect a sample Node.js application to -a MongoDB Atlas deployment. +a MongoDB Atlas deployment. If you prefer to connect to MongoDB using a different +driver or programming language, see our :driver:`list of official drivers <>`. .. _node-quick-start-download-and-install: .. _node-get-started-download-and-install: @@ -45,15 +45,19 @@ Download and Install .. procedure:: :style: connected - .. step:: Install Node and npm + .. step:: Install dependencies - Ensure you have Node.js {+min-node-version+} or later and - npm (Node Package Manager) installed in your development environment. + Ensure you have the following dependencies installed in + your development environment: + + - Node.js {+min-node-version+} or later + - npm (Node Package Manager) - For information on how to install Node.js and npm, see - `downloading and installing Node.js and npm `__. + To learn how to install Node.js and npm, see + `Downloading and installing Node.js and npm `__ + in the npm documentation. - .. step:: Create a Project Directory + .. step:: Create a project directory In your shell, run the following command to create a directory called ``node_quickstart`` for this project: @@ -62,27 +66,21 @@ Download and Install mkdir node_quickstart - Run the following command to navigate into the project - directory: + Then, run the following commands to navigate into the + directory and initialize your Node.js project: .. code-block:: bash cd node_quickstart - - Run the following command to initialize your Node.js project: - - .. code-block:: bash - npm init -y - - When this command successfully completes, you have a ``package.json`` + + When the initialization command successfully completes, you have a ``package.json`` file in your ``node_quickstart`` directory. - .. step:: Install the Node.js Driver - Run the following command in your shell to install - the driver in your project directory: + Run the following command from your project directory to install + the driver: .. code-block:: bash @@ -94,10 +92,8 @@ Download and Install - Saves the package in the ``node_modules`` directory - Records the dependency information in the ``package.json`` file -After you complete these steps, you have Node.js and npm installed -and a new project directory with the driver dependencies installed. - -.. include:: /includes/quick-start/troubleshoot.rst +After you complete these steps, you have a new project directory with +the driver dependencies installed. .. _node-quick-start-create-deployment: .. _node-get-started-create-deployment: @@ -112,13 +108,13 @@ your MongoDB database in the cloud. .. procedure:: :style: connected - .. step:: Create a Free MongoDB deployment on Atlas + .. step:: Create a free MongoDB deployment on Atlas Complete the :atlas:`Get Started with Atlas ` guide to set up a new Atlas account and load sample data into a new free tier MongoDB deployment. - .. step:: Save your Credentials + .. 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. @@ -127,7 +123,53 @@ After you complete these steps, you have a new free tier MongoDB deployment on Atlas, database user credentials, and sample data loaded in your database. -.. include:: /includes/quick-start/troubleshoot.rst +.. _node-quick-start-connection-string: +.. _node-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 section `, + log into your Atlas account and navigate to the + :guilabel:`Clusters` section and click the :guilabel:`Connect` button + for your new deployment. + + .. figure:: /includes/figures/atlas_connection_connect_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + .. 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_node.png + :alt: The connection string copy button in the Atlas UI + + .. step:: Update the placeholders + + Paste your connection string into a file in your preferred text editor + and replace the ``username`` and ```` placeholders with your + database user's username and password. + + Save this file to a safe location for use in the next section. + +After completing these steps, you have a connection string that +contains your database username and password. .. _node-quick-start-connect-to-mongodb: .. _node-get-started-connect-to-mongodb: @@ -138,10 +180,10 @@ Connect to MongoDB .. procedure:: :style: connected - .. step:: Create your Node.js Application + .. step:: Create your Node.js application - Create a file to contain your application called ``index.js`` in your - ``node_quickstart`` project directory. + In your ``node_quickstart`` directory, create a file called + ``index.js`` for your application. Copy and paste the following code into the ``index.js`` file: @@ -149,7 +191,7 @@ Connect to MongoDB const { MongoClient } = require("mongodb"); - // Replace the uri string with your connection string. + // Replace the uri string with your connection string const uri = ""; const client = new MongoClient(uri); @@ -159,33 +201,33 @@ Connect to MongoDB const database = client.db('sample_mflix'); const movies = database.collection('movies'); - // Query for a movie that has the title 'Back to the Future' + // Queries for a movie that has a title value of 'Back to the Future' const query = { title: 'Back to the Future' }; const movie = await movies.findOne(query); console.log(movie); } finally { - // Ensures that the client will close when you finish/error await client.close(); } } run().catch(console.dir); - .. step:: Assign the Connection String + .. step:: Assign the connection string Replace the ```` placeholder with the connection string that you copied from the :ref:`node-quick-start-connection-string` step of this guide. - .. step:: Run your Node.js Application + .. step:: Run your Node.js application - In your shell, run the following command to start this application: + From your project directory, run the following command to start + the application: .. code-block:: none node index.js - The output includes details of the retrieved movie document: + The output includes details about the retrieved movie document: .. code-block:: none @@ -198,15 +240,13 @@ Connect to MongoDB ... } - If you encounter an error or see no output, check whether you specified the - proper connection string in the ``index.js`` file, and that you loaded the + If you encounter an error or see no output, verify that you specified the + proper connection string in the ``index.js`` file and that you loaded the sample data. After you complete these steps, you have a working application that -uses the driver to connect to your MongoDB deployment, runs a query on -the sample data, and prints out the result. - -.. include:: /includes/quick-start/troubleshoot.rst +uses the driver to connect to your MongoDB deployment, query +the sample data, and print out the result. .. _node-quick-start-next-steps: .. _node-get-started-next-steps: @@ -216,14 +256,16 @@ Next Steps Congratulations on completing the quick start tutorial! +.. include:: /includes/quick-start/troubleshoot.rst + In this tutorial, you created a Node.js application that connects to a MongoDB deployment hosted on MongoDB Atlas and retrieves a document that matches a query. -Learn more about the {+driver-long+} from the following resources: +Learn more about the {+driver-short+} from the following resources: -- Discover how to perform read and write operations in the - :ref:`CRUD Operations ` section. +- Discover how to configure your MongoDB connection in the + :ref:`Connect to MongoDB ` section. -- See examples of frequently-used operations in the - :ref:`Usage Examples ` section. \ No newline at end of file +- Discover how to perform read and write operations in the + :ref:`CRUD Operations ` section. \ No newline at end of file diff --git a/source/includes/figures/atlas_connection_connect_cluster.png b/source/includes/figures/atlas_connection_connect_cluster.png new file mode 100644 index 0000000000000000000000000000000000000000..eba1fbc15649fd32e00dad0760a251c010a97715 GIT binary patch literal 81158 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›MC-?jF-&y>ryB54@)mtt{V+rCL{g#vO1nh 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 literal 0 HcmV?d00001 diff --git a/source/includes/figures/atlas_connection_copy_uri_node.png b/source/includes/figures/atlas_connection_copy_uri_node.png new file mode 100644 index 0000000000000000000000000000000000000000..55975c7cd20cd98927b00d38577f82df11c39386 GIT binary patch literal 136330 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 Date: Thu, 20 Mar 2025 13:08:28 -0400 Subject: [PATCH 03/26] DOCSP-48384: Atlas search (#1041) * DOCSP-48384: Atlas search * edits * tech feedback --- source/atlas-search.txt | 113 ++++++++++++++++++++++++++++++++ source/includes/atlas-search.js | 41 ++++++++++++ source/index.txt | 6 ++ 3 files changed, 160 insertions(+) create mode 100644 source/atlas-search.txt create mode 100644 source/includes/atlas-search.js diff --git a/source/atlas-search.txt b/source/atlas-search.txt new file mode 100644 index 000000000..b0241ac2b --- /dev/null +++ b/source/atlas-search.txt @@ -0,0 +1,113 @@ +.. _node-atlas-search: + +============ +Atlas Search +============ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene + :description: Learn about how to use Atlas Search in the {+driver-long+}. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to +run :atlas:`Atlas Search ` queries on a collection. +Atlas Search enables you to perform full-text searches on collections +hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of the +search and which fields to index. + +Sample Data +~~~~~~~~~~~ + +The example in this guide uses the ``movies`` collection in the ``sample_mflix`` +database from the :atlas:`Atlas sample datasets `. To learn how to +create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Run an Atlas Search Query +------------------------- + +This section shows how to create an aggregation pipeline to run an +Atlas Search query on a collection. In your array of pipeline stages, +add the ``$search`` stage to specify the search criteria. Then, call +the ``aggregate()`` method and pass your pipeline array as a parameter. + +.. tip:: + + To learn more about aggregation operations, see the :ref:`node-aggregation` + guide. + +Before running an Atlas Search query, you must create an Atlas Search index +on your collection. To learn how to programmatically create an Atlas Search +index, see the :ref:`node-indexes-search` section of the Indexes guide. + +Atlas Search Example +~~~~~~~~~~~~~~~~~~~~ + +This example runs an Atlas Search query by performing the +following actions: + +- Creates a ``$search`` stage that instructs the driver + to query for documents in which the ``title`` field contains + the word ``"Alabama"`` + +- Creates a ``$project`` stage that instructs the driver to + include the ``title`` field in the query results + +- Passes the pipeline stages to the ``aggregate()`` method and + prints the results + +.. io-code-block:: + :copyable: + + .. input:: /includes/atlas-search.js + :start-after: begin-atlas-search + :end-before: end-atlas-search + :language: java + :dedent: + + .. output:: + :language: console + :visible: false + + { + _id: new ObjectId('...'), + title: 'Alabama Moon' + } + { + _id: new ObjectId('...'), + title: 'Crazy in Alabama' + } + { + _id: new ObjectId('...'), + title: 'Sweet Home Alabama' + } + +.. tip:: Node.js Driver Atlas Search Examples + + To view more examples that use the {+driver-short+} to perform Atlas + Search queries, see :atlas:`Atlas Search Tutorials ` + in the Atlas documentation. + +Additional Information +---------------------- + +To learn more about Atlas Search, see :atlas:`Atlas Search ` +in the Atlas documentation. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``aggregate()`` method, see the +`API documentation <{+api+}/classes/Collection.html#aggregate>`__. \ No newline at end of file diff --git a/source/includes/atlas-search.js b/source/includes/atlas-search.js new file mode 100644 index 000000000..49e679331 --- /dev/null +++ b/source/includes/atlas-search.js @@ -0,0 +1,41 @@ +const { MongoClient } = require("mongodb"); + +// Replace the placeholder with your connection string. +const uri = ""; +const client = new MongoClient(uri); + +async function run() { + try { + const database = client.db("sample_mflix"); + const collection = database.collection("movies"); + + // Queries for documents that have a "title" value containing the word "Alabama" + // begin-atlas-search + const pipeline = [ + { + $search: { + index: "default", // Replace with your search index name + text: { + query: "Alabama", + path: "title" + } + } + }, + { + $project: { + title: 1 + } + } + ]; + + const cursor = collection.aggregate(pipeline); + for await (const document of cursor) { + console.log(document); + } + // end-atlas-search + } finally { + await client.close(); + } +} + +run().catch(console.dir); \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index ae549854d..e587ee4b0 100644 --- a/source/index.txt +++ b/source/index.txt @@ -23,6 +23,7 @@ MongoDB Node Driver Data Formats Indexes Run a Database Command + Atlas Search Monitoring and Logging Security Reference @@ -85,6 +86,11 @@ Run a Database Command Learn how to run a database command in the :ref:`` section. +Atlas Search +------------ + +Learn how to run Atlas Search queries in the :ref:`` section. + Monitoring and Logging ---------------------- From 058071d12b49791e51d7236513c97d380d9760ab Mon Sep 17 00:00:00 2001 From: shuangela Date: Fri, 21 Mar 2025 15:19:05 -0400 Subject: [PATCH 04/26] DOCSP-48378 make mongoclient page (#1038) * make mongoclient page * fix link: * fix link * add anchor to page to avoid broken link * nr feedback * nb feedback * monospace --- source/connect/mongoclient.txt | 153 +++++++++++++-------------------- 1 file changed, 60 insertions(+), 93 deletions(-) diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index a0176ab71..ab63a2245 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -18,54 +18,71 @@ Create a MongoClient :depth: 2 :class: singlecol -This guide shows you how to connect to a -`MongoDB Atlas deployment `__, -a MongoDB instance, or a replica set using the Node.js driver. +Overview +-------- + +To connect to a MongoDB deployment, you need two things: + +- **Connection URI**, also known as a *connection string*, which tells the + {+driver-short+} which MongoDB deployment to connect to. +- **MongoClient** object, which creates the connection to and performs + operations on the MongoDB deployment. + +You can also use ``MongoClientOptions`` to customize the way the {+driver-short+} behaves +while connected to MongoDB. + +This guide shows you how to create a connection string and use a ``MongoClient`` object +to connect to MongoDB. .. _node-connection-uri: Connection URI -------------- -The **connection URI** is the set of instructions that the driver uses to connect to a -MongoDB deployment. It tells the driver how to connect to MongoDB and how to behave -while connected. The following example shows each part of the connection URI: +A standard connection string includes the following components: -.. figure:: /includes/figures/dns_seedlist_connection_string_parts.png - :alt: Each part of the connection string +.. list-table:: + :widths: 20 80 + :header-rows: 1 -In this example, we connect to an Atlas MongoDB deployment that has a -DNS SRV record. For more details, see the -:manual:`DNS Seed List Connection Format -` -documentation. This format offers flexibility in deployment and the -ability to change the servers in rotation without reconfiguring clients. + * - Component + - Description -.. note:: + * - ``mongodb://`` + + - Required. A prefix that identifies this as a string in the + standard connection format. - To learn how to retrieve your connection string in Atlas, see the - :atlas:`Atlas driver connection guide `. + * - ``username:password`` -If you are connecting to an instance or replica set that does not have a -DNS SRV address, you must use ``mongodb`` for the protocol, which specifies -the :manual:`Standard Connection String Format -`. + - Optional. Authentication credentials. If you include these, the client + authenticates the user against the database specified in ``authSource``. + For more information about the ``authSource`` connection option, + see :ref:`node-troubleshooting-connection-admin` in the Connection Troubleshooting guide. -After the protocol, the next part of the connection string contains credentials -if you are using password-based authentication. Replace the value of ``user`` -with your username and ``pass`` with your password. If you are using an -authentication mechanism that does not require a username and password, omit -this part of the connection URI. + * - ``host[:port]`` -The next part of the connection string specifies the hostname or IP address of -your MongoDB instance, followed by the port number. In the example above, we use -``sample.host`` as the hostname and ``27017`` as the port. Replace these values -to point to your MongoDB instance. + - Required. The host and optional port number where MongoDB is running. If you don't + include the port number, the driver uses the default port, ``27017``. -The last part of the connection string contains connection and authentication -options as parameters. In the example above, we set two connection options: -``maxPoolSize=20`` and ``w=majority``. For more information on connection -options, skip to the :ref:`node-connection-options` section. + * - ``/defaultauthdb`` + + - Optional. The authentication database to use if the + connection string includes ``username:password@`` + authentication credentials but not the ``authSource`` option. + When you call ``client.db()`` with no argument, this is the database that is used. If you don't include + this component, the client authenticates the user against the ``admin`` database. + + * - ``?`` + + - Optional. A query string that specifies connection-specific + options as ``=`` pairs. See + :ref:`node-connection-options` for a full description of + these options. + +For more information about creating a connection string, see +:manual:`Connection Strings ` in the +MongoDB Server documentation. .. _connect-sample-node-driver: @@ -81,8 +98,8 @@ URI and a ``MongoClientOptions`` object. As each ``MongoClient`` represents a pool of connections to the database, most applications only require a single instance of a ``MongoClient``, even across multiple requests. To learn more about - how connection pools work in the driver, see the :ref:`FAQ page - `. + how connection pools work in the driver, see the :ref:`Connection Pools page + `. Use the ``serverApi`` option in your ``MongoClientOptions`` object to enable the {+stable-api+} feature, which forces the server to run operations @@ -102,63 +119,13 @@ verify that the connection is successful: Call the ``MongoClient.connect()`` method explicitly if you want to verify that the connection is successful. -To learn more about the Stable -API feature, see the :ref:`{+stable-api+} page `. - -.. _node-other-ways-to-connect: - -Other Ways to Connect to MongoDB --------------------------------- - -If you are connecting to a single {+mdb-server+} instance or replica set -that is not hosted on Atlas, see the following sections to find out how to -connect. - -Connect to a {+mdb-server+} on Your Local Machine -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: /includes/localhost-connection.rst - -To test whether you can connect to your server, replace the connection -string in the :ref:`Connect to MongoDB ` code -example and run it. - -Connect to a Replica Set -^^^^^^^^^^^^^^^^^^^^^^^^ - -A MongoDB replica set deployment is a group of connected instances that -store the same set of data. This configuration of instances provides data -redundancy and high data availability. - -To connect to a replica set deployment, specify the hostname and port numbers -of each instance, separated by a comma, and the replica set name as the value -of the ``replicaSet`` parameter in the connection string. - -.. code-block:: none - - mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRs - -When making a connection, the driver takes the following actions by default: - -- Discovers all replica set members when given the address of any one member. -- Dispatches operations to the appropriate member, such as write against the **primary**. - -.. tip:: Specify all hosts - - To ensure connectivity if one host is unavailable, provide the full - list of hosts when connecting to a replica set. +To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page `. -Direct Connection -^^^^^^^^^^^^^^^^^ +API Documentation +----------------- -To force your operations to run on the host specified in your connection -URI, you can specify the ``directConnection`` connection option. If you -specify this option, you must use the standard connection URI format. The -driver does not accept the DNS seedlist connection format (SRV) when you -specify this option. +For more information about creating a ``MongoClient`` object with the +{+driver-short+}, see the following API documentation: -When you specify ``directConnection`` and connect to a secondary member of the -replica set, your write operations fail because the client isn't -connected to the primary member. To perform read operations, you must -enable secondary reads. See the :manual:`read preference options ` -for more information. +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ \ No newline at end of file From 68bd42318e63d02fe9b5bacb50cacc10d0257bae Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 24 Mar 2025 17:21:41 -0400 Subject: [PATCH 05/26] DOCSP-48383 document bson (#1044) * make bson page * edit code * fix spacing * capitalization * change copy * nb edits --- snooty.toml | 1 + source/data-formats/bson.txt | 126 +++++++++++++++++++++++++++++++++-- 2 files changed, 122 insertions(+), 5 deletions(-) diff --git a/snooty.toml b/snooty.toml index 4789d56ae..c89262e9d 100644 --- a/snooty.toml +++ b/snooty.toml @@ -31,3 +31,4 @@ driver-short = "Node.js driver" mdb-server = "MongoDB Server" min-node-version = "v16.20.1" stable-api = "Stable API" +language = "JavaScript" diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 2e76a802b..25fd0f948 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -1,9 +1,9 @@ .. _node-bson-control: .. _node-bson: -==== -BSON -==== +============== +Work with BSON +============== .. default-domain:: mongodb @@ -17,9 +17,125 @@ Overview -------- In this guide, you can learn how to create BSON documents, read BSON from a file, -and write BSON to a file by using {+driver-short+}. +and write BSON to a file by using the {+driver-short+}. **BSON**, or Binary JSON, is the data format that MongoDB uses to organize and store data. This data format includes all JSON data structure types and adds support for types including dates, different size integers, ObjectIds, and -binary data. \ No newline at end of file +binary data. You can use BSON documents in your {+language+} application by importing the +BSON package. For a complete list of supported types, see the +:manual:`BSON Types ` server manual page. + +The code samples in this guide use the following BSON document as an example: + +.. code-block:: none + + { + "address" : { + "street" : "Pizza St", + "zipcode" : "10003" + }, + "coord" : [-73.982419, 41.579505], + "cuisine" : "Pizza", + "name" : "Mongo's Pizza" + } + +Create a BSON Document +---------------------- + +You can create a BSON document by using the same notation you use to create an +object in {+language+}. The {+driver-short+} automatically converts {+language+} objects +into BSON documents when inserting them into a collection. + +The following example creates a BSON document that +represents the preceding sample BSON document: + +.. code-block:: javascript + + const document = { + "address": { + "street": "Pizza St", + "zipcode": "10003", + }, + "coord": [-73.982419, 41.579505], + "cuisine": "Pizza", + "name": "Mongo's Pizza", + } + +Change a BSON Document +---------------------- + +You can modify the contents of a BSON document by using the same notation you use to modify +an object in {+language+}. The following example makes three changes to the previous +BSON document: + +1. Adds a new field, ``restaurant_id``, with the value ``12345`` +#. Removes the ``cuisine`` field +#. Sets the value of the ``name`` field to ``"Mongo's Pizza Place"`` + +.. code-block:: javascript + + document.restaurant_id = "12345"; + delete document.cuisine; + document.name = "Mongo's Pizza Place"; + +Write BSON to a File +-------------------- + +To write BSON data to a file, import the file system module and open the output file. +Then, write each document to the output file. Ensure that documents are encoded in BSON +format by using the ``BSON.serialize()`` method. + +The following example writes the sample BSON document to ``file.bson``: + +.. code-block:: javascript + + import fs from 'fs/promises'; // Import the file system module + import { BSON } from 'bson'; // Import the BSON package + + // Create a BSON object + const bsonData = BSON.serialize(result); + + // Write the BSON data to a file + await fs.writeFile('file.bson', bsonData); + console.log('BSON data written to file.bson'); + +Read BSON from a File +--------------------- + +To read BSON documents from a file, open a file in read mode. Then, decode the documents +from BSON format as you read them by using the ``BSON.deserialize()`` method. + +The following example reads the sample BSON document from ``file.bson``: + +.. io-code-block:: + :copyable: true + + .. input:: + :language: javascript + + import fs from 'fs/promises'; // Import the file system module + import { BSON } from 'bson'; // Import the BSON package + + // Read the BSON data from a file + const data = await fs.readFile('file.bson'); + const document = BSON.deserialize(data); + console.log(document); + + .. output:: + :visible: false + + { + _id: new ObjectId('67e1823d0d63bfdf87e8928e'), + address: { street: 'Pizza St', zipcode: '10003' }, + coord: [ -73.982419, 41.579505 ], + cuisine: 'Pizza', + name: "Mongo's Pizza" + } + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the `BSON <{+api+}/modules/BSON.html>`__ API documentation. + From 4a7e3f0c8c27eacda3580568187def9d71c370e5 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Tue, 25 Mar 2025 16:35:01 -0400 Subject: [PATCH 06/26] DOCSP-48493: Databases & collections (#1045) * DOCSP-48493: Databases & collections * edits * SA feedback * typo --- source/databases-collections.txt | 193 +++++++++++++++++++++++ source/includes/databases-collections.js | 50 ++++++ source/index.txt | 7 + 3 files changed, 250 insertions(+) create mode 100644 source/databases-collections.txt create mode 100644 source/includes/databases-collections.js diff --git a/source/databases-collections.txt b/source/databases-collections.txt new file mode 100644 index 000000000..a1ab63e97 --- /dev/null +++ b/source/databases-collections.txt @@ -0,0 +1,193 @@ +.. _node-databases-collections: + +========================= +Databases and Collections +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: table, row, organize, storage, code example + +Overview +-------- + +In this guide, you can learn how to interact with MongoDB databases and +collections by using the {+driver-short+}. + +MongoDB organizes data into a hierarchy of the following levels: + +- **Databases**: Top-level data structures in a MongoDB deployment that store collections. +- **Collections**: Groups of MongoDB documents. They are analogous to tables in relational databases. +- **Documents**: Units that store literal data such as strings, numbers, dates, and other embedded documents. + For more information about document field types and structure, see the + :manual:`Documents ` entry in the {+mdb-server+} manual. + +Access a Database +----------------- + +You can access a database by calling the ``db()`` method on a +``MongoClient`` instance. + +The following example accesses a database named ``"test_database"``: + +.. literalinclude:: /includes/databases-collections.js + :start-after: start-access-database + :end-before: end-access-database + :language: javascript + :copyable: + :dedent: + +Access a Collection +------------------- + +You can access a collection by calling the ``collection()`` method on a ``Db`` +instance. + +The following example accesses a collection named ``"test_collection"``: + +.. literalinclude:: /includes/databases-collections.js + :start-after: start-access-collection + :end-before: end-access-collection + :language: javascript + :copyable: + :dedent: + +.. tip:: + + If the provided collection name does not already exist in the database, + MongoDB implicitly creates the collection when you first insert data + into it. + +Create a Collection +------------------- + +To explicitly create a collection, call the ``createCollection()`` method on +a ``Db`` instance. + +The following example creates a collection named ``"example_collection"``: + +.. literalinclude:: /includes/databases-collections.js + :start-after: start-create-collection + :end-before: end-create-collection + :language: javascript + :copyable: + :dedent: + +You can specify collection options, such as maximum size and document +validation rules, by passing a ``CreateCollectionOptions`` instance to the +``createCollection()`` method. For a full list of +optional parameters, see the :manual:`create command ` +entry in the {+mdb-server+} manual. + +Get a List of Collections +------------------------- + +You can query for a list of collections in a database by calling the +``listCollections()`` method on a ``Db`` instance. + +The following example lists all collections in a database: + +.. io-code-block:: + :copyable: + + .. input:: /includes/databases-collections.js + :language: javascript + :start-after: start-find-collections + :end-before: end-find-collections + :dedent: + + .. output:: + :language: console + :visible: false + + { + name: 'example_collection', + type: 'collection', + options: {}, + info: { + readOnly: false, + uuid: new UUID('...') + }, + idIndex: { v: 2, key: { _id: 1 }, name: '_id_' } + } + { + name: 'test_collection', + type: 'collection', + options: {}, + info: { + readOnly: false, + uuid: new UUID('...') + }, + idIndex: { v: 2, key: { _id: 1 }, name: '_id_' } + } + +To query for only the names of the collections in the database, pass +the ``nameOnly`` option to the ``listCollections()`` method and set its +value to ``true``, as shown in the following code: + +.. io-code-block:: + :copyable: + + .. input:: /includes/databases-collections.js + :language: javascript + :start-after: start-find-collection-names + :end-before: end-find-collection-names + :dedent: + + .. output:: + :language: console + :visible: false + + { name: 'example_collection', type: 'collection' } + { name: 'test_collection', type: 'collection' } + +.. tip:: + + For more information about iterating over a cursor, see the :ref:`node-cursor` + guide. + +Delete a Collection +------------------- + +You can delete a collection by calling the ``drop()`` method on a +``Collection`` instance. + +The following example deletes the ``"test_collection"`` collection: + +.. literalinclude:: /includes/databases-collections.js + :start-after: start-delete-collection + :end-before: end-delete-collection + :language: javascript + :copyable: + :dedent: + +.. warning:: Dropping a Collection Deletes All Data in the Collection + + Dropping a collection from your database permanently deletes all + documents and all indexes within that collection. + + Drop a collection only if the data in it is no longer needed. + +API Documentation +----------------- + +To learn more about any of the types or methods discussed in this +guide, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `db() <{+api+}/classes/MongoClient.html#db>`__ +- `collection() <{+api+}/classes/Db.html#collection>`__ +- `createCollection() <{+api+}/classes/Db.html#createCollection>`__ +- `listCollections() <{+api+}/classes/Db.html#listCollections>`__ +- `dropCollection() <{+api+}/classes/Db.html#dropCollection>`__ \ No newline at end of file diff --git a/source/includes/databases-collections.js b/source/includes/databases-collections.js new file mode 100644 index 000000000..888c56c57 --- /dev/null +++ b/source/includes/databases-collections.js @@ -0,0 +1,50 @@ +const { MongoClient } = require("mongodb"); + +// Replace the placeholder with your connection string. +const uri = ""; +const client = new MongoClient(uri); + +async function run() { + try { + // Accesses the test_database database + // start-access-database + const database = client.db("test_database"); + // end-access-database + + // Accesses the test_collection collection + // start-access-collection + const collection = database.collection("test_collection"); + // end-access-collection + + // Explicitly creates a collection in the database + // start-create-collection + const createColl = await database.createCollection("example_collection"); + // end-create-collection + + // Retrieves information about each collection in the database + // start-find-collections + const colls = database.listCollections(); + for await (const doc of colls) { + console.log(doc) + } + // end-find-collections + + // Retrieves the name of each collection in the database + // start-find-collection-names + const names = database.listCollections({}, { nameOnly: true }); + for await (const doc of names) { + console.log(doc) + } + // end-find-collection-names + + // Deletes the test_collection collection + // start-delete-collection + const collectionToDelete = database.collection("test_collection"); + await collectionToDelete.drop(); + // end-delete-collection + } finally { + await client.close(); + } +} + +run().catch(console.dir); \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index e587ee4b0..e7b38a092 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,6 +18,7 @@ MongoDB Node Driver Get Started Connect + Databases & Collections CRUD Operations Aggregation Data Formats @@ -59,6 +60,12 @@ Connect to MongoDB Learn how to create and configure a connection to a MongoDB deployment in the :ref:`` section. +Databases and Collections +------------------------- + +Learn how to interact wth MongoDB databases and collections in the +:ref:`` section. + Read and Write Data ------------------- From 3e98a3e01c6c1ef23aa985e85137adb2760ce5eb Mon Sep 17 00:00:00 2001 From: shuangela Date: Wed, 26 Mar 2025 13:24:18 -0400 Subject: [PATCH 07/26] DOCSP-48385 Make Atlas Vector Search page (#1042) * make page * fix vale * remove extra space * add to index * fix link * fix link * fix quotes * fix quotes * lm feedback * fix spacing * remove extra code * fix spacing * fix link * fix link title * change copy * lm review * change spacing * lm edits * remove extra words * nb edits * remove extra quotes * fix quotes * add quote * change quote * nb feedback --- snooty.toml | 3 +- source/atlas-vector-search.txt | 178 ++++++++++++++++++ .../atlas-vector-search-example.js | 51 +++++ source/index.txt | 6 + 4 files changed, 237 insertions(+), 1 deletion(-) create mode 100644 source/atlas-vector-search.txt create mode 100644 source/includes/aggregation/atlas-vector-search-example.js diff --git a/snooty.toml b/snooty.toml index c89262e9d..0a1898d0f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -31,4 +31,5 @@ driver-short = "Node.js driver" mdb-server = "MongoDB Server" min-node-version = "v16.20.1" stable-api = "Stable API" -language = "JavaScript" +vector-search = "Atlas Vector Search" +language = "JavaScript" \ No newline at end of file diff --git a/source/atlas-vector-search.txt b/source/atlas-vector-search.txt new file mode 100644 index 000000000..1c5bd2c44 --- /dev/null +++ b/source/atlas-vector-search.txt @@ -0,0 +1,178 @@ +.. _node-atlas-vector-search: + +================================ +Run an Atlas Vector Search Query +================================ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, semantic, nearest + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the Atlas Vector Search feature +in the {+driver-short+}. + +You can use {+vector-search+} to perform a vector search on your data stored in +Atlas. Vector search allows you to query your data based on semantic meaning +rather than just keyword matches, which helps you retrieve more relevant search +results. It enables your AI-powered applications to support use cases such as +semantic search, hybrid search, and generative search, including +Retrieval-Augmented Generation (RAG). + +To learn more about {+vector-search+}, see the :atlas:`{+vector-search+} +` guides in the MongoDB Atlas +documentation. + +.. important:: Feature Compatibility + + To learn what versions of MongoDB Atlas support this feature, see + :atlas:`Limitations ` + in the MongoDB Atlas documentation. + +Perform a Vector Search +----------------------- + +To use this feature, you must create a vector search index and index your +vector embeddings. To learn about how to programmatically create a +vector search index, see the :atlas:`Create an Atlas Vector Search Index +` section in the +Atlas documentation. To learn more about vector embeddings, see +:atlas:`How to Create Vector Embeddings +` in the Atlas documentation. + +After you create a vector search index on your vector embeddings, you +can reference this index in your pipeline stage, as shown in the +following example. + +Sample Data +~~~~~~~~~~~ + +The example on this page shows how to build an aggregation pipeline that uses the +``$vectorSearch`` stage to perform a vector search on the +``sample_mflix.embedded_movies`` collection in the :atlas:`Atlas sample datasets +`. + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Vector Search Example +~~~~~~~~~~~~~~~~~~~~~ + +You can perform a vector search query by using the ``$vectorSearch`` stage +in an :ref:`aggregation pipeline `. To perform a vector +search on a collection, you must first have a collection with a field that contains +vector embeddings and a vector search index that covers that field. + +In the following example, the aggregation pipeline searches the ``plot`` field of each +document in the collection for text semantically related to the term "time travel". The +``queryVector`` field in the ``$vectorSearch`` pipeline is the vector representation of +your query. + +.. io-code-block:: + :copyable: true + + .. input:: /includes/aggregation/atlas-vector-search-example.js + :language: javascript + :dedent: + + .. output:: + :language: javascript + :visible: false + + { + plot: 'A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.', + title: 'Thrill Seekers', + score: 0.9259490966796875 + } + { + plot: 'At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.', + title: 'About Time', + score: 0.9253997802734375 + } + { + plot: 'An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.', + title: 'Timecop', + score: 0.922332763671875 + } + { + plot: "After using his mother's newly built time machine, Dolf gets stuck + involuntary in the year 1212. He ends up in a children's crusade where he confronts + his new friends with modern techniques...", + title: 'Crusade in Jeans', + score: 0.92205810546875 + } + { + plot: 'Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.', + title: 'The Time Machine', + score: 0.921875 + } + { + plot: 'A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...', + title: 'A.P.E.X.', + score: 0.9202728271484375 + } + { + plot: "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", + title: 'Men in Black 3', + score: 0.9198150634765625 + } + { + plot: 'Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.', + title: 'Tomorrowland', + score: 0.91961669921875 + } + { + plot: 'A romantic drama about a Chicago librarian with a gene that causes him to involuntarily time travel, and the complications it creates for his marriage.', + title: "The Time Traveler's Wife", + score: 0.9174346923828125 + } + { + plot: 'With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.', + title: 'Love Story 2050', + score: 0.9165191650390625 + } + +This query uses the ``$vectorSearch`` stage to: + +- Perform an Approximate Nearest Neighbor (ANN) vector search + +- Search for the specified term in the ``plot_embedding`` field + +- Set the number of nearest neighbors used in the search to 150 by using the + ``numCandidates`` option + +- Return a maximum of 10 documents from the query using the ``limit`` option + +It uses the ``$project`` stage to: + +- Only include the movie ``plot`` and ``title`` fields in the results + +- Add a ``score`` field to show the relevance of each result to the search term + +Additional Information +---------------------- + +To see more Atlas Vector Search tutorials for the {+driver-short+}, see the :atlas:`Atlas +Vector Search tutorials ` in the Atlas documentation. + +To learn more about the syntax of the ``$vectorSearch`` pipeline stage, +see the Syntax and Fields sections of the +:atlas:`Create and Run Queries ` +guide in the Atlas Vector Search section of the Atlas documentation. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``aggregate()`` method, see `aggregate() +<{+api+}/classes/Collection.html#aggregate>`__ in the API documentation. diff --git a/source/includes/aggregation/atlas-vector-search-example.js b/source/includes/aggregation/atlas-vector-search-example.js new file mode 100644 index 000000000..b666e30ad --- /dev/null +++ b/source/includes/aggregation/atlas-vector-search-example.js @@ -0,0 +1,51 @@ +const { MongoClient } = require("mongodb"); + +// Replace with the connection string to your Atlas cluster to connect +const uri = ""; + +const client = new MongoClient(uri); + +async function run() { + try { + await client.connect(); + + // Sets the namespace + const database = client.db("sample_mflix"); + const coll = database.collection("embedded_movies"); + + // Defines the pipeline + const agg = [ + { + '$vectorSearch': { + 'index': 'vector_index', + 'path': 'plot_embedding', + 'queryVector': Binary.fromFloat32Array(Float32Array.from([ + -0.0016261312, -0.028070757, -0.011342932, -0.012775794, -0.0027440966, 0.008683807, -0.02575152, -0.02020668, -0.010283281, -0.0041719596, 0.021392956, 0.028657231, -0.006634482, 0.007490867, 0.018593878, 0.0038187427, 0.029590257, -0.01451522, 0.016061379, 0.00008528442, -0.008943722, 0.01627464, 0.024311995, -0.025911469, 0.00022596726, -0.008863748, 0.008823762, -0.034921836, 0.007910728, -0.01515501, 0.035801545, -0.0035688248, -0.020299982, -0.03145631, -0.032256044, -0.028763862, -0.0071576433, -0.012769129, 0.012322609, -0.006621153, 0.010583182, 0.024085402, -0.001623632, 0.007864078, -0.021406285, 0.002554159, 0.012229307, -0.011762793, 0.0051682983, 0.0048484034, 0.018087378, 0.024325324, -0.037694257, -0.026537929, -0.008803768, -0.017767483, -0.012642504, -0.0062712682, 0.0009771782, -0.010409906, 0.017754154, -0.004671795, -0.030469967, 0.008477209, -0.005218282, -0.0058480743, -0.020153364, -0.0032805866, 0.004248601, 0.0051449724, 0.006791097, 0.007650814, 0.003458861, -0.0031223053, -0.01932697, -0.033615597, 0.00745088, 0.006321252, -0.0038154104, 0.014555207, 0.027697546, -0.02828402, 0.0066711367, 0.0077107945, 0.01794076, 0.011349596, -0.0052715978, 0.014755142, -0.019753495, -0.011156326, 0.011202978, 0.022126047, 0.00846388, 0.030549942, -0.0041386373, 0.018847128, -0.00033655585, 0.024925126, -0.003555496, -0.019300312, 0.010749794, 0.0075308536, -0.018287312, -0.016567878, -0.012869096, -0.015528221, 0.0078107617, -0.011156326, 0.013522214, -0.020646535, -0.01211601, 0.055928253, 0.011596181, -0.017247654, 0.0005939711, -0.026977783, -0.003942035, -0.009583511, -0.0055248477, -0.028737204, 0.023179034, 0.003995351, 0.0219661, -0.008470545, 0.023392297, 0.010469886, -0.015874773, 0.007890735, -0.009690142, -0.00024970944, 0.012775794, 0.0114762215, 0.013422247, 0.010429899, -0.03686786, -0.006717788, -0.027484283, 0.011556195, -0.036068123, -0.013915418, -0.0016327957, 0.0151016945, -0.020473259, 0.004671795, -0.012555866, 0.0209531, 0.01982014, 0.024485271, 0.0105431955, -0.005178295, 0.033162415, -0.013795458, 0.007150979, 0.010243294, 0.005644808, 0.017260984, -0.0045618312, 0.0024725192, 0.004305249, -0.008197301, 0.0014203656, 0.0018460588, 0.005015015, -0.011142998, 0.01439526, 0.022965772, 0.02552493, 0.007757446, -0.0019726837, 0.009503538, -0.032042783, 0.008403899, -0.04609149, 0.013808787, 0.011749465, 0.036388017, 0.016314628, 0.021939443, -0.0250051, -0.017354285, -0.012962398, 0.00006107364, 0.019113706, 0.03081652, -0.018114036, -0.0084572155, 0.009643491, -0.0034721901, 0.0072642746, -0.0090636825, 0.01642126, 0.013428912, 0.027724205, 0.0071243206, -0.6858542, -0.031029783, -0.014595194, -0.011449563, 0.017514233, 0.01743426, 0.009950057, 0.0029706885, -0.015714826, -0.001806072, 0.011856096, 0.026444625, -0.0010663156, -0.006474535, 0.0016161345, -0.020313311, 0.0148351155, -0.0018393943, 0.0057347785, 0.018300641, -0.018647194, 0.03345565, -0.008070676, 0.0071443142, 0.014301958, 0.0044818576, 0.003838736, -0.007350913, -0.024525259, -0.001142124, -0.018620536, 0.017247654, 0.007037683, 0.010236629, 0.06046009, 0.0138887605, -0.012122675, 0.037694257, 0.0055081863, 0.042492677, 0.00021784494, -0.011656162, 0.010276617, 0.022325981, 0.005984696, -0.009496873, 0.013382261, -0.0010563189, 0.0026507939, -0.041639622, 0.008637156, 0.026471283, -0.008403899, 0.024858482, -0.00066686375, -0.0016252982, 0.027590916, 0.0051449724, 0.0058647357, -0.008743787, -0.014968405, 0.027724205, -0.011596181, 0.0047650975, -0.015381602, 0.0043718936, 0.002159289, 0.035908177, -0.008243952, -0.030443309, 0.027564257, 0.042625964, -0.0033688906, 0.01843393, 0.019087048, 0.024578573, 0.03268257, -0.015608194, -0.014128681, -0.0033538956, -0.0028757197, -0.004121976, -0.032389335, 0.0034322033, 0.058807302, 0.010943064, -0.030523283, 0.008903735, 0.017500903, 0.00871713, -0.0029406983, 0.013995391, -0.03132302, -0.019660193, -0.00770413, -0.0038853872, 0.0015894766, -0.0015294964, -0.006251275, -0.021099718, -0.010256623, -0.008863748, 0.028550599, 0.02020668, -0.0012962399, -0.003415542, -0.0022509254, 0.0119360695, 0.027590916, -0.046971202, -0.0015194997, -0.022405956, 0.0016677842, -0.00018535563, -0.015421589, -0.031802863, 0.03814744, 0.0065411795, 0.016567878, -0.015621523, 0.022899127, -0.011076353, 0.02841731, -0.002679118, -0.002342562, 0.015341615, 0.01804739, -0.020566562, -0.012989056, -0.002990682, 0.01643459, 0.00042527664, 0.008243952, -0.013715484, -0.004835075, -0.009803439, 0.03129636, -0.021432944, 0.0012087687, -0.015741484, -0.0052016205, 0.00080890034, -0.01755422, 0.004811749, -0.017967418, -0.026684547, -0.014128681, 0.0041386373, -0.013742141, -0.010056688, -0.013268964, -0.0110630235, -0.028337335, 0.015981404, -0.00997005, -0.02424535, -0.013968734, -0.028310679, -0.027750863, -0.020699851, 0.02235264, 0.001057985, 0.00081639783, -0.0099367285, 0.013522214, -0.012016043, -0.00086471526, 0.013568865, 0.0019376953, -0.019020405, 0.017460918, -0.023045745, 0.008503866, 0.0064678704, -0.011509543, 0.018727167, -0.003372223, -0.0028690554, -0.0027024434, -0.011902748, -0.012182655, -0.015714826, -0.0098634185, 0.00593138, 0.018753825, 0.0010146659, 0.013029044, 0.0003521757, -0.017620865, 0.04102649, 0.00552818, 0.024485271, -0.009630162, -0.015608194, 0.0006718621, -0.0008418062, 0.012395918, 0.0057980907, 0.016221326, 0.010616505, 0.004838407, -0.012402583, 0.019900113, -0.0034521967, 0.000247002, -0.03153628, 0.0011038032, -0.020819811, 0.016234655, -0.00330058, -0.0032289368, 0.00078973995, -0.021952773, -0.022459272, 0.03118973, 0.03673457, -0.021472929, 0.0072109587, -0.015075036, 0.004855068, -0.0008151483, 0.0069643734, 0.010023367, -0.010276617, -0.023019087, 0.0068244194, -0.0012520878, -0.0015086699, 0.022046074, -0.034148756, -0.0022192693, 0.002427534, -0.0027124402, 0.0060346797, 0.015461575, 0.0137554705, 0.009230294, -0.009583511, 0.032629255, 0.015994733, -0.019167023, -0.009203636, 0.03393549, -0.017274313, -0.012042701, -0.0009930064, 0.026777849, -0.013582194, -0.0027590916, -0.017594207, -0.026804507, -0.0014236979, -0.022032745, 0.0091236625, -0.0042419364, -0.00858384, -0.0033905501, -0.020739838, 0.016821127, 0.022539245, 0.015381602, 0.015141681, 0.028817179, -0.019726837, -0.0051283115, -0.011489551, -0.013208984, -0.0047017853, -0.0072309524, 0.01767418, 0.0025658219, -0.010323267, 0.012609182, -0.028097415, 0.026871152, -0.010276617, 0.021912785, 0.0022542577, 0.005124979, -0.0019710176, 0.004518512, -0.040360045, 0.010969722, -0.0031539614, -0.020366628, -0.025778178, -0.0110030435, -0.016221326, 0.0036587953, 0.016207997, 0.003007343, -0.0032555948, 0.0044052163, -0.022046074, -0.0008822095, -0.009363583, 0.028230704, -0.024538586, 0.0029840174, 0.0016044717, -0.014181997, 0.031349678, -0.014381931, -0.027750863, 0.02613806, 0.0004136138, -0.005748107, -0.01868718, -0.0010138329, 0.0054348772, 0.010703143, -0.003682121, 0.0030856507, -0.004275259, -0.010403241, 0.021113047, -0.022685863, -0.023032416, 0.031429652, 0.001792743, -0.005644808, -0.011842767, -0.04078657, -0.0026874484, 0.06915057, -0.00056939584, -0.013995391, 0.010703143, -0.013728813, -0.022939114, -0.015261642, -0.022485929, 0.016807798, 0.007964044, 0.0144219175, 0.016821127, 0.0076241563, 0.005461535, -0.013248971, 0.015301628, 0.0085171955, -0.004318578, 0.011136333, -0.0059047225, -0.010249958, -0.018207338, 0.024645219, 0.021752838, 0.0007614159, -0.013648839, 0.01111634, -0.010503208, -0.0038487327, -0.008203966, -0.00397869, 0.0029740208, 0.008530525, 0.005261601, 0.01642126, -0.0038753906, -0.013222313, 0.026537929, 0.024671877, -0.043505676, 0.014195326, 0.024778508, 0.0056914594, -0.025951454, 0.017620865, -0.0021359634, 0.008643821, 0.021299653, 0.0041686273, -0.009017031, 0.04044002, 0.024378639, -0.027777521, -0.014208655, 0.0028623908, 0.042119466, 0.005801423, -0.028124074, -0.03129636, 0.022139376, -0.022179363, -0.04067994, 0.013688826, 0.013328944, 0.0046184794, -0.02828402, -0.0063412455, -0.0046184794, -0.011756129, -0.010383247, -0.0018543894, -0.0018593877, -0.00052024535, 0.004815081, 0.014781799, 0.018007403, 0.01306903, -0.020433271, 0.009043689, 0.033189073, -0.006844413, -0.019766824, -0.018767154, 0.00533491, -0.0024575242, 0.018727167, 0.0058080875, -0.013835444, 0.0040719924, 0.004881726, 0.012029372, 0.005664801, 0.03193615, 0.0058047553, 0.002695779, 0.009290274, 0.02361889, 0.017834127, 0.0049017193, -0.0036388019, 0.010776452, -0.019793482, 0.0067777685, -0.014208655, -0.024911797, 0.002385881, 0.0034988478, 0.020899786, -0.0025858153, -0.011849431, 0.033189073, -0.021312982, 0.024965113, -0.014635181, 0.014048708, -0.0035921505, -0.003347231, 0.030869836, -0.0017161017, -0.0061346465, 0.009203636, -0.025165047, 0.0068510775, 0.021499587, 0.013782129, -0.0024475274, -0.0051149824, -0.024445284, 0.006167969, 0.0068844, -0.00076183246, 0.030150073, -0.0055948244, -0.011162991, -0.02057989, -0.009703471, -0.020646535, 0.008004031, 0.0066378145, -0.019900113, -0.012169327, -0.01439526, 0.0044252095, -0.004018677, 0.014621852, -0.025085073, -0.013715484, -0.017980747, 0.0071043274, 0.011456228, -0.01010334, -0.0035321703, -0.03801415, -0.012036037, -0.0028990454, -0.05419549, -0.024058744, -0.024272008, 0.015221654, 0.027964126, 0.03182952, -0.015354944, 0.004855068, 0.011522872, 0.004771762, 0.0027874154, 0.023405626, 0.0004242353, -0.03132302, 0.007057676, 0.008763781, -0.0027057757, 0.023005757, -0.0071176565, -0.005238275, 0.029110415, -0.010989714, 0.013728813, -0.009630162, -0.029137073, -0.0049317093, -0.0008630492, -0.015248313, 0.0043219104, -0.0055681667, -0.013175662, 0.029723546, 0.025098402, 0.012849103, -0.0009996708, 0.03118973, -0.0021709518, 0.0260181, -0.020526575, 0.028097415, -0.016141351, 0.010509873, -0.022965772, 0.002865723, 0.0020493253, 0.0020509914, -0.0041419696, -0.00039695262, 0.017287642, 0.0038987163, 0.014795128, -0.014661839, -0.008950386, 0.004431874, -0.009383577, 0.0012604183, -0.023019087, 0.0029273694, -0.033135757, 0.009176978, -0.011023037, -0.002102641, 0.02663123, -0.03849399, -0.0044152127, 0.0004527676, -0.0026924468, 0.02828402, 0.017727496, 0.035135098, 0.02728435, -0.005348239, -0.001467017, -0.019766824, 0.014715155, 0.011982721, 0.0045651635, 0.023458943, -0.0010046692, -0.0031373003, -0.0006972704, 0.0019043729, -0.018967088, -0.024311995, 0.0011546199, 0.007977373, -0.004755101, -0.010016702, -0.02780418, -0.004688456, 0.013022379, -0.005484861, 0.0017227661, -0.015394931, -0.028763862, -0.026684547, 0.0030589928, -0.018513903, 0.028363993, 0.0044818576, -0.009270281, 0.038920518, -0.016008062, 0.0093902415, 0.004815081, -0.021059733, 0.01451522, -0.0051583014, 0.023765508, -0.017874114, -0.016821127, -0.012522544, -0.0028390652, 0.0040886537, 0.020259995, -0.031216389, -0.014115352, -0.009176978, 0.010303274, 0.020313311, 0.0064112223, -0.02235264, -0.022872468, 0.0052449396, 0.0005723116, 0.0037321046, 0.016807798, -0.018527232, -0.009303603, 0.0024858483, -0.0012662497, -0.007110992, 0.011976057, -0.007790768, -0.042999174, -0.006727785, -0.011829439, 0.007024354, 0.005278262, -0.017740825, -0.0041519664, 0.0085905045, 0.027750863, -0.038387362, 0.024391968, 0.00087721116, 0.010509873, -0.00038508154, -0.006857742, 0.0183273, -0.0037054466, 0.015461575, 0.0017394272, -0.0017944091, 0.014181997, -0.0052682655, 0.009023695, 0.00719763, -0.013522214, 0.0034422, 0.014941746, -0.0016711164, -0.025298337, -0.017634194, 0.0058714002, -0.005321581, 0.017834127, 0.0110630235, -0.03369557, 0.029190388, -0.008943722, 0.009363583, -0.0034222065, -0.026111402, -0.007037683, -0.006561173, 0.02473852, -0.007084334, -0.010110005, -0.008577175, 0.0030439978, -0.022712521, 0.0054582027, -0.0012620845, -0.0011954397, -0.015741484, 0.0129557345, -0.00042111133, 0.00846388, 0.008930393, 0.016487904, 0.010469886, -0.007917393, -0.011762793, -0.0214596, 0.000917198, 0.021672864, 0.010269952, -0.007737452, -0.010243294, -0.0067244526, -0.015488233, -0.021552904, 0.017127695, 0.011109675, 0.038067464, 0.00871713, -0.0025591573, 0.021312982, -0.006237946, 0.034628596, -0.0045251767, 0.008357248, 0.020686522, 0.0010696478, 0.0076708077, 0.03772091, -0.018700508, -0.0020676525, -0.008923728, -0.023298996, 0.018233996, -0.010256623, 0.0017860786, 0.009796774, -0.00897038, -0.01269582, -0.018527232, 0.009190307, -0.02372552, -0.042119466, 0.008097334, -0.0066778013, -0.021046404, 0.0019593548, 0.011083017, -0.0016028056, 0.012662497, -0.000059095124, 0.0071043274, -0.014675168, 0.024831824, -0.053582355, 0.038387362, 0.0005698124, 0.015954746, 0.021552904, 0.031589597, -0.009230294, -0.0006147976, 0.002625802, -0.011749465, -0.034362018, -0.0067844326, -0.018793812, 0.011442899, -0.008743787, 0.017474247, -0.021619547, 0.01831397, -0.009037024, -0.0057247817, -0.02728435, 0.010363255, 0.034415334, -0.024032086, -0.0020126705, -0.0045518344, -0.019353628, -0.018340627, -0.03129636, -0.0034038792, -0.006321252, -0.0016161345, 0.033642255, -0.000056075285, -0.005005019, 0.004571828, -0.0024075406, -0.00010215386, 0.0098634185, 0.1980148, -0.003825407, -0.025191706, 0.035161756, 0.005358236, 0.025111731, 0.023485601, 0.0023342315, -0.011882754, 0.018287312, -0.0068910643, 0.003912045, 0.009243623, -0.001355387, -0.028603915, -0.012802451, -0.030150073, -0.014795128, -0.028630573, -0.0013487226, 0.002667455, 0.00985009, -0.0033972147, -0.021486258, 0.009503538, -0.017847456, 0.013062365, -0.014341944, 0.005078328, 0.025165047, -0.015594865, -0.025924796, -0.0018177348, 0.010996379, -0.02993681, 0.007324255, 0.014475234, -0.028577257, 0.005494857, 0.00011725306, -0.013315615, 0.015941417, 0.009376912, 0.0025158382, 0.008743787, 0.023832154, -0.008084005, -0.014195326, -0.008823762, 0.0033455652, -0.032362677, -0.021552904, -0.0056081535, 0.023298996, -0.025444955, 0.0097301295, 0.009736794, 0.015274971, -0.0012937407, -0.018087378, -0.0039387033, 0.008637156, -0.011189649, -0.00023846315, -0.011582852, 0.0066411467, -0.018220667, 0.0060846633, 0.0376676, -0.002709108, 0.0072776037, 0.0034188742, -0.010249958, -0.0007747449, -0.00795738, -0.022192692, 0.03910712, 0.032122757, 0.023898797, 0.0076241563, -0.007397564, -0.003655463, 0.011442899, -0.014115352, -0.00505167, -0.031163072, 0.030336678, -0.006857742, -0.022259338, 0.004048667, 0.02072651, 0.0030156737, -0.0042119464, 0.00041861215, -0.005731446, 0.011103011, 0.013822115, 0.021512916, 0.009216965, -0.006537847, -0.027057758, -0.04054665, 0.010403241, -0.0056281467, -0.005701456, -0.002709108, -0.00745088, -0.0024841821, 0.009356919, -0.022659205, 0.004061996, -0.013175662, 0.017074378, -0.006141311, -0.014541878, 0.02993681, -0.00028448965, -0.025271678, 0.011689484, -0.014528549, 0.004398552, -0.017274313, 0.0045751603, 0.012455898, 0.004121976, -0.025458284, -0.006744446, 0.011822774, -0.015035049, -0.03257594, 0.014675168, -0.0039187097, 0.019726837, -0.0047251107, 0.0022825818, 0.011829439, 0.005391558, -0.016781142, -0.0058747325, 0.010309938, -0.013049036, 0.01186276, -0.0011246296, 0.0062112883, 0.0028190718, -0.021739509, 0.009883412, -0.0073175905, -0.012715813, -0.017181009, -0.016607866, -0.042492677, -0.0014478565, -0.01794076, 0.012302616, -0.015194997, -0.04433207, -0.020606548, 0.009696807, 0.010303274, -0.01694109, -0.004018677, 0.019353628, -0.001991011, 0.000058938927, 0.010536531, -0.17274313, 0.010143327, 0.014235313, -0.024152048, 0.025684876, -0.0012504216, 0.036601283, -0.003698782, 0.0007310093, 0.004165295, -0.0029157067, 0.017101036, -0.046891227, -0.017460918, 0.022965772, 0.020233337, -0.024072073, 0.017220996, 0.009370248, 0.0010363255, 0.0194336, -0.019606877, 0.01818068, -0.020819811, 0.007410893, 0.0019326969, 0.017887443, 0.006651143, 0.00067394477, -0.011889419, -0.025058415, -0.008543854, 0.021579562, 0.0047484366, 0.014062037, 0.0075508473, -0.009510202, -0.009143656, 0.0046817916, 0.013982063, -0.0027990784, 0.011782787, 0.014541878, -0.015701497, -0.029350337, 0.021979429, 0.01332228, -0.026244693, -0.0123492675, -0.003895384, 0.0071576433, -0.035454992, -0.00046984528, 0.0033522295, 0.039347045, 0.0005119148, 0.00476843, -0.012995721, 0.0024042083, -0.006931051, -0.014461905, -0.0127558, 0.0034555288, -0.0074842023, -0.030256703, -0.007057676, -0.00807734, 0.007804097, -0.006957709, 0.017181009, -0.034575284, -0.008603834, -0.005008351, -0.015834786, 0.02943031, 0.016861115, -0.0050849924, 0.014235313, 0.0051449724, 0.0025924798, -0.0025741523, 0.04289254, -0.002104307, 0.012969063, -0.008310596, 0.00423194, 0.0074975314, 0.0018810473, -0.014248641, -0.024725191, 0.0151016945, -0.017527562, 0.0018727167, 0.0002830318, 0.015168339, 0.0144219175, -0.004048667, -0.004358565, 0.011836103, -0.010343261, -0.005911387, 0.0022825818, 0.0073175905, 0.00403867, 0.013188991, 0.03334902, 0.006111321, 0.008597169, 0.030123414, -0.015474904, 0.0017877447, -0.024551915, 0.013155668, 0.023525586, -0.0255116, 0.017220996, 0.004358565, -0.00934359, 0.0099967085, 0.011162991, 0.03092315, -0.021046404, -0.015514892, 0.0011946067, -0.01816735, 0.010876419, -0.10124666, -0.03550831, 0.0056348112, 0.013942076, 0.005951374, 0.020419942, -0.006857742, -0.020873128, -0.021259667, 0.0137554705, 0.0057880944, -0.029163731, -0.018767154, -0.021392956, 0.030896494, -0.005494857, -0.0027307675, -0.006801094, -0.014821786, 0.021392956, -0.0018110704, -0.0018843795, -0.012362596, -0.0072176233, -0.017194338, -0.018713837, -0.024272008, 0.03801415, 0.00015880188, 0.0044951867, -0.028630573, -0.0014070367, -0.00916365, -0.026537929, -0.009576847, -0.013995391, -0.0077107945, 0.0050016865, 0.00578143, -0.04467862, 0.008363913, 0.010136662, -0.0006268769, -0.006591163, 0.015341615, -0.027377652, -0.00093136, 0.029243704, -0.020886457, -0.01041657, -0.02424535, 0.005291591, -0.02980352, -0.009190307, 0.019460259, -0.0041286405, 0.004801752, 0.0011787785, -0.001257086, -0.011216307, -0.013395589, 0.00088137644, -0.0051616337, 0.03876057, -0.0033455652, 0.00075850025, -0.006951045, -0.0062112883, 0.018140694, -0.006351242, -0.008263946, 0.018154023, -0.012189319, 0.0075508473, -0.044358727, -0.0040153447, 0.0093302615, -0.010636497, 0.032789204, -0.005264933, -0.014235313, -0.018393943, 0.007297597, -0.016114693, 0.015021721, 0.020033404, 0.0137688, 0.0011046362, 0.010616505, -0.0039453674, 0.012109346, 0.021099718, -0.0072842683, -0.019153694, -0.003768759, 0.039320387, -0.006747778, -0.0016852784, 0.018154023, 0.0010963057, -0.015035049, -0.021033075, -0.04345236, 0.017287642, 0.016341286, -0.008610498, 0.00236922, 0.009290274, 0.028950468, -0.014475234, -0.0035654926, 0.015434918, -0.03372223, 0.004501851, -0.012929076, -0.008483873, -0.0044685286, -0.0102233, 0.01615468, 0.0022792495, 0.010876419, -0.0059647025, 0.01895376, -0.0069976957, -0.0042952523, 0.017207667, -0.00036133936, 0.0085905045, 0.008084005, 0.03129636, -0.016994404, -0.014915089, 0.020100048, -0.012009379, -0.006684466, 0.01306903, 0.00015765642, -0.00530492, 0.0005277429, 0.015421589, 0.015528221, 0.032202728, -0.003485519, -0.0014286962, 0.033908837, 0.001367883, 0.010509873, 0.025271678, -0.020993087, 0.019846799, 0.006897729, -0.010216636, -0.00725761, 0.01818068, -0.028443968, -0.011242964, -0.014435247, -0.013688826, 0.006101324, -0.0022509254, 0.013848773, -0.0019077052, 0.017181009, 0.03422873, 0.005324913, -0.0035188415, 0.014128681, -0.004898387, 0.005038341, 0.0012320944, -0.005561502, -0.017847456, 0.0008538855, -0.0047884234, 0.011849431, 0.015421589, -0.013942076, 0.0029790192, -0.013702155, 0.0001199605, -0.024431955, 0.019926772, 0.022179363, -0.016487904, -0.03964028, 0.0050849924, 0.017487574, 0.022792496, 0.0012504216, 0.004048667, -0.00997005, 0.0076041627, -0.014328616, -0.020259995, 0.0005598157, -0.010469886, 0.0016852784, 0.01716768, -0.008990373, -0.001987679, 0.026417969, 0.023792166, 0.0046917885, -0.0071909656, -0.00032051947, -0.023259008, -0.009170313, 0.02071318, -0.03156294, -0.030869836, -0.006324584, 0.013795458, -0.00047151142, 0.016874444, 0.00947688, 0.00985009, -0.029883493, 0.024205362, -0.013522214, -0.015075036, -0.030603256, 0.029270362, 0.010503208, 0.021539574, 0.01743426, -0.023898797, 0.022019416, -0.0068777353, 0.027857494, -0.021259667, 0.0025758184, 0.006197959, 0.006447877, -0.00025200035, -0.004941706, -0.021246338, -0.005504854, -0.008390571, -0.0097301295, 0.027244363, -0.04446536, 0.05216949, 0.010243294, -0.016008062, 0.0122493, -0.0199401, 0.009077012, 0.019753495, 0.006431216, -0.037960835, -0.027377652, 0.016381273, -0.0038620618, 0.022512587, -0.010996379, -0.0015211658, -0.0102233, 0.007071005, 0.008230623, -0.009490209, -0.010083347, 0.024431955, 0.002427534, 0.02828402, 0.0035721571, -0.022192692, -0.011882754, 0.010056688, 0.0011904413, -0.01426197, -0.017500903, -0.00010985966, 0.005591492, -0.0077707744, -0.012049366, 0.011869425, 0.00858384, -0.024698535, -0.030283362, 0.020140035, 0.011949399, -0.013968734, 0.042732596, -0.011649498, -0.011982721, -0.016967745, -0.0060913274, -0.007130985, -0.013109017, -0.009710136 + ])), + 'numCandidates': 150, + 'limit': 10 + } + }, { + '$project': { + '_id': 0, + 'plot': 1, + 'title': 1, + 'score': { + '$meta': 'vectorSearchScore' + } + } + } + ]; + // Runs pipeline + const result = coll.aggregate(agg); + + // Prints results + for await (const doc of result) { + console.log(doc); + } + } finally { + await client.close(); + } +} +run().catch(console.dir); + diff --git a/source/index.txt b/source/index.txt index e7b38a092..35236341b 100644 --- a/source/index.txt +++ b/source/index.txt @@ -25,6 +25,7 @@ MongoDB Node Driver Indexes Run a Database Command Atlas Search + Atlas Vector Search Monitoring and Logging Security Reference @@ -98,6 +99,11 @@ Atlas Search Learn how to run Atlas Search queries in the :ref:`` section. +Atlas Vector Search +------------------- + +Learn how to run Atlas Vector Search queries in the :ref:`` section. + Monitoring and Logging ---------------------- From b082ff98bc5dfe9631ba2845c78c96723f1cea71 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Wed, 26 Mar 2025 18:00:04 -0400 Subject: [PATCH 08/26] DOCSP-48377 Authentication Reorg (#1040) * DOCSP-48377 Authentication Reorg * start building TOC * full draft * edits * edits * SA comments * SA update redirect * Edit table --- config/redirects | 2 + .../authentication/aws-env-variable.js | 2 +- source/code-snippets/authentication/aws.js | 2 +- source/code-snippets/authentication/cr.js | 2 +- .../code-snippets/authentication/default.js | 2 +- source/code-snippets/authentication/sha1.js | 2 +- source/code-snippets/authentication/sha256.js | 2 +- source/code-snippets/authentication/x509.js | 4 +- source/connect.txt | 3 +- source/connect/connection-options.txt | 2 +- source/reference/release-notes.txt | 5 +- source/security/authentication.txt | 90 +++-- source/security/authentication/aws-iam.txt | 186 +++++++++ source/security/authentication/kerberos.txt | 114 ++++++ source/security/authentication/ldap.txt | 87 +++++ source/security/authentication/mechanisms.txt | 369 ------------------ .../{enterprise-mechanisms.txt => oidc.txt} | 174 ++------- source/security/authentication/scram.txt | 141 +++++++ source/security/authentication/x509.txt | 122 ++++++ 19 files changed, 750 insertions(+), 561 deletions(-) create mode 100644 source/security/authentication/aws-iam.txt create mode 100644 source/security/authentication/kerberos.txt create mode 100644 source/security/authentication/ldap.txt delete mode 100644 source/security/authentication/mechanisms.txt rename source/security/authentication/{enterprise-mechanisms.txt => oidc.txt} (56%) create mode 100644 source/security/authentication/scram.txt create mode 100644 source/security/authentication/x509.txt diff --git a/config/redirects b/config/redirects index 73b0fb329..01eef4fe5 100644 --- a/config/redirects +++ b/config/redirects @@ -83,3 +83,5 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/crud/update/embedded-arrays/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/pkFactory/ -> ${base}/crud/pkFactory/ +# Comprehensive Coverage Redirects +[*-master]: ${prefix}/${version}/security/authentication/enterprise-mechanisms/ -> ${base}/security/authentication diff --git a/source/code-snippets/authentication/aws-env-variable.js b/source/code-snippets/authentication/aws-env-variable.js index 3533a04fc..f8e93fd31 100644 --- a/source/code-snippets/authentication/aws-env-variable.js +++ b/source/code-snippets/authentication/aws-env-variable.js @@ -1,7 +1,7 @@ const { MongoClient } = require("mongodb"); // Remember to specify your AWS credentials in environment variables. -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "MONGODB-AWS"; let uri = diff --git a/source/code-snippets/authentication/aws.js b/source/code-snippets/authentication/aws.js index da158e5b4..2033c009d 100644 --- a/source/code-snippets/authentication/aws.js +++ b/source/code-snippets/authentication/aws.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const accessKeyId = encodeURIComponent(""); const secretAccessKey = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "MONGODB-AWS"; diff --git a/source/code-snippets/authentication/cr.js b/source/code-snippets/authentication/cr.js index 0c8605c13..109a871f6 100644 --- a/source/code-snippets/authentication/cr.js +++ b/source/code-snippets/authentication/cr.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; // Replace the following with your MongoDB deployment's connection string. const uri = diff --git a/source/code-snippets/authentication/default.js b/source/code-snippets/authentication/default.js index b8c60c882..30f18a2f5 100644 --- a/source/code-snippets/authentication/default.js +++ b/source/code-snippets/authentication/default.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "DEFAULT"; diff --git a/source/code-snippets/authentication/sha1.js b/source/code-snippets/authentication/sha1.js index 32dc9fd33..7b932bc79 100644 --- a/source/code-snippets/authentication/sha1.js +++ b/source/code-snippets/authentication/sha1.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "SCRAM-SHA-1"; diff --git a/source/code-snippets/authentication/sha256.js b/source/code-snippets/authentication/sha256.js index 86dfbb499..e44ea9046 100644 --- a/source/code-snippets/authentication/sha256.js +++ b/source/code-snippets/authentication/sha256.js @@ -3,7 +3,7 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. const username = encodeURIComponent(""); const password = encodeURIComponent(""); -const clusterUrl = ""; +const clusterUrl = ""; const authMechanism = "SCRAM-SHA-256"; diff --git a/source/code-snippets/authentication/x509.js b/source/code-snippets/authentication/x509.js index fffe07529..224a865b5 100644 --- a/source/code-snippets/authentication/x509.js +++ b/source/code-snippets/authentication/x509.js @@ -1,8 +1,8 @@ const { MongoClient } = require("mongodb"); // Replace the following with values for your environment. -const clusterUrl = ""; -const clientPEMFile = encodeURIComponent(""); +const clusterUrl = ""; +const clientPEMFile = encodeURIComponent(""); const authMechanism = "MONGODB-X509"; diff --git a/source/connect.txt b/source/connect.txt index 55526a6ec..7ef488cca 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -57,5 +57,4 @@ Compatibility .. include:: /includes/fact-atlas-link.rst For information about authenticating to MongoDB, -see :ref:`node-authentication-mechanisms` and -:ref:`node-enterprise-authentication-mechanisms`. +see the :ref:`Authentication Mechanisms ` section. diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index a5afce3c0..bf0a7d130 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -53,7 +53,7 @@ string, see :manual:`Connection Strings ` in the - Specifies the authentication mechanism method to use for connection to the server. If you do not specify a value, the driver uses the default mechanism, either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256`` depending on the server version. See - :ref:`authentication mechanism ` for available + the :ref:`Authentication Mechanisms ` section for available authentication mechanisms. * - **authMechanismProperties** diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index 1701e138c..31e8c0454 100644 --- a/source/reference/release-notes.txt +++ b/source/reference/release-notes.txt @@ -209,8 +209,7 @@ The {+driver-short+} v6.11 release includes the following features: releases. - Adds OIDC authentication support for Kubernetes environments. To learn - more about this feature, see the :ref:`node-enterprise-auth-oidc` - section of the Enterprise Authentication Mechanisms guide. + more about this feature, see the :ref:`node-authentication-oidc` guide. To use OIDC to authenticate from a Kubernetes environment, set the ``authMechanismProperties`` connection option to ``ENVIRONMENT:k8s`` @@ -683,7 +682,7 @@ The {+driver-short+} v6.1 release includes the following features: To learn how to set region settings when using the ``MONGODB-AWS`` authentication mechanism, see the :guilabel:`Web Identity Token` tab in the - :ref:`MONGODB-AWS ` section of the Authentication Mechanisms guide. + :ref:`AWS IAM Authentication Mechanism ` guide. - Fixes a memory leak issue caused by recursive calls to the ``next()`` method of the ``ChangeStream`` type. diff --git a/source/security/authentication.txt b/source/security/authentication.txt index 0ec2bd2c9..f6906c2fa 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -1,9 +1,9 @@ .. _node-authentication-mechanisms: .. _node-authentication: -============== -Authentication -============== +========================= +Authentication Mechanisms +========================= .. meta:: :description: Authenticate using the MongoDB Node.js Driver with various supported authentication mechanisms. @@ -12,36 +12,62 @@ Authentication .. toctree:: - Authentication - Enterprise Authentication + SCRAM + X.509 + AWS IAM + OIDC + LDAP (PLAIN) + Kerberos (GSSAPI) Overview -------- -These guides show you how to authenticate to a MongoDB instance using the -Node.js driver. - -The :doc:`Authentication Mechanisms ` guide contains -sample connection code using each authentication mechanism supported in the -MongoDB Community Edition which includes: - -- ``DEFAULT`` -- ``SCRAM-SHA-256`` -- ``SCRAM-SHA-1`` -- ``MONGODB-CR`` -- ``MONGODB-AWS`` -- ``X.509`` - -The :doc:`Enterprise Authentication Mechanisms -` guide contains sample -connection code using authentication mechanisms available only in MongoDB -Enterprise Edition which includes: - -- ``Kerberos (GSSAPI/SSPI)`` -- ``LDAP (PLAIN)`` -- ``MONGODB-OIDC`` - -.. note:: - For instructions on MongoDB driver installation and deployment setup, see - our :guides:`Connect to MongoDB guide `. Select your - MongoDB deployment type and the Node.js client. +In this guide, you can learn how to authenticate to MongoDB by using the +**authentication mechanisms** available in {+mdb-server+}. +Authentication mechanisms are processes by which the driver and server confirm +the identity of a client to ensure security before connecting. + +.. tip:: Connecting to MongoDB + + To learn how to establish a connection to your MongoDB deployment, see the + :ref:`node-connect` guide. + +MongoDB Edition Compatibility +----------------------------- + +The following table lists the authentication mechanisms supported by MongoDB and +the {+mdb-server+} editions that each mechanism is compatible with. Click the name of +a mechanism to learn more about how to use it with your application. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - Authentication Mechanism + - Atlas + - Enterprise Advanced + - Community + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - Yes + - Yes + * - :ref:`` + - Yes + - No + - No + * - :ref:`` + - Yes + - Yes + - No + * - :ref:`` + - Yes + - Yes + - No + * - :ref:`` + - No + - Yes + - No diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt new file mode 100644 index 000000000..0288200c6 --- /dev/null +++ b/source/security/authentication/aws-iam.txt @@ -0,0 +1,186 @@ +.. _node-authentication-aws: + +================================ +AWS IAM Authentication Mechanism +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: atlas, amazon web services, code example + +Overview +-------- + +The ``MONGODB-AWS`` authentication mechanism uses Amazon Web Services +Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB. +You can use this mechanism only when authenticating to MongoDB Atlas. + +.. tip:: Configure Atlas for AWS IAM Authentication + + To learn more about configuring MongoDB Atlas for AWS IAM authentication, see + :atlas:`Set Up Authentication with AWS IAM ` in + the Atlas documentation. + +Specify MONGODB-AWS Authentication +---------------------------------- + +The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services +Identity and Access Management (AWS IAM) credentials to authenticate your +user. If you do not already have the `AWS signature library +`__, use the following +``npm`` command to install it: + +.. code-block:: bash + + npm install aws4 + +To connect to a MongoDB instance with ``MONGODB-AWS`` authentication +enabled, specify the ``MONGODB-AWS`` authentication mechanism. + +The driver checks for your credentials in the following sources in order: + +1. Connection string +#. Environment variables +#. Web identity token file +#. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`` +#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks + `_. + +.. important:: + + The driver only reads the credentials from the first method that it detects + in the order as given by the preceding list. For example, if you specify + your AWS credentials in the connection string, the driver ignores any + credentials that you specified in environment variables. + +.. tabs:: + + .. tab:: Connection String + :tabid: connection string + + To connect to your MongoDB instance with a connection string, pass + your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` + credentials to the driver when you attempt to connect. If your AWS + login requires a session token, include your ``AWS_SESSION_TOKEN`` as well. + + The following code shows an example of specifying the ``MONGODB-AWS`` + authentication mechanism and credentials with a connection string: + + .. important:: + + Always **URI encode** the username and certificate file path using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + + .. literalinclude:: /code-snippets/authentication/aws.js + :language: javascript + + .. tab:: Environment Variables + :tabid: environment variables + + To authenticate to your MongoDB instance using AWS credentials stored in + environment variables, set the following variables by using + a shell: + + .. code-block:: bash + + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + export AWS_SESSION_TOKEN= + + .. note:: + + Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS + session token for that role. + + After you've set the preceding environment variables, specify the ``MONGODB-AWS`` + authentication mechanism in your connection string as shown in the following example: + + .. literalinclude:: /code-snippets/authentication/aws-env-variable.js + :language: javascript + + .. tab:: Web Identity Token File + :tabid: web-identity-token-file + + You can use the OpenID Connect (OIDC) token obtained from a web identity + provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or + other services. + + To authenticate with your OIDC token you must first install + `@aws-sdk/credential-providers + `__. You can + install this dependency using the following ``npm`` command: + + .. code-block:: bash + + npm install @aws-sdk/credential-providers + + Next, create a file that contains your OIDC token. Then + set the absolute path to this file in an environment variable by using + a shell as shown in the following example: + + .. code-block:: bash + + export AWS_WEB_IDENTITY_TOKEN_FILE= + + AWS recommends using regional AWS STS endpoints instead of global + endpoints to reduce latency, build-in redundancy, and increase session token validity. + To set the AWS region, set `AWS_REGION `__ + and `AWS_STS_REGIONAL_ENDPOINTS `__ + as environment variables, as shown in the following example: + + .. code-block:: bash + + export AWS_STS_REGIONAL_ENDPOINTS=regional // Enables regional endpoints + export AWS_REGION=us-east-1 // Sets your AWS region + + If both these environment variables aren't set, the default region is + ``us-east-1``. For a list of available AWS regions, see the + `Regional Endpoints `__ + section of the AWS Service Endpoints reference in the AWS documentation. + + .. warning:: Consult your SDK's Documentation for Setting an AWS Region + + You cannot set your AWS region with environment variables for all SDKs, + as in the above example. See your SDK's specific documentation for + configuring an AWS region. + + After you've set the preceding environment variables, specify the ``MONGODB-AWS`` + authentication mechanism in your connection string as shown in the following example: + + .. literalinclude:: /code-snippets/authentication/aws-env-variable.js + :language: javascript + +.. important:: Retrieval of AWS Credentials + + Starting in MongoDB version 4.11, when you install the optional + ``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK + to retrieve credentials from the environment. As a result, if you + have a shared AWS credentials file or config file, the driver will + use those credentials by default. + + You can override this behavior by performing one of the following + actions: + + - Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point + to your credentials file. + - Set the equivalent environment variable in your application to point + to your credentials file. + - Create an AWS profile for your MongoDB credentials and set the + ``AWS_PROFILE`` environment variable to that profile name. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/kerberos.txt b/source/security/authentication/kerberos.txt new file mode 100644 index 000000000..3b7c98f27 --- /dev/null +++ b/source/security/authentication/kerberos.txt @@ -0,0 +1,114 @@ +.. _node-authentication-kerberos: + +========================================== +Kerberos (GSSAPI) Authentication Mechanism +========================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example + +Overview +-------- + +The Generic Security Services API (GSSAPI) authentication mechanism allows you to +use your principal name to authenticate to a Kerberos service. +You can use this mechanism only when authenticating to MongoDB Enterprise Advanced. + +Specify Kerberos (GSSAPI) Authentication +---------------------------------------- + +.. note:: + The Node.js driver supports Kerberos on UNIX using the MIT Kerberos library + and on Windows using the SSPI API. + +The ``GSSAPI`` authentication mechanism uses your user principal to +authenticate to a Kerberos service. + +You can specify this authentication mechanism by performing the +following actions while specifying options on your +:manual:`connection string `: + +- Set the ``authMechanism`` parameter to ``GSSAPI``. +- Set the ``SERVICE_NAME`` value in the ``authMechanismProperties`` + parameter if using a value other than ``mongodb``. +- Specify a ``SERVICE_REALM`` value in the ``authMechanismProperties`` + parameter if a custom service realm is required. +- Specify a ``CANONICALIZE_HOST_NAME`` value in the ``authMechanismProperties`` + parameter if canonicalization of the hostname is required. This property accepts + the following values: + + - ``none``: (Default) Does not perform hostname canonicalization + - ``forward``: Performs a forward DNS lookup to canonicalize the hostname + - ``forwardAndReverse``: Performs a forward DNS lookup and then a + reverse lookup on that value to canonicalize the hostname + +.. important:: + + The ``gssapiServiceName`` parameter is deprecated and may be removed + in future versions of the driver. Use + ``authMechanismProperties=SERVICE_NAME:`` in the + connection URI instead. + To learn more about the authentication options for a connection string, see the + :manual:`Authentication Options ` + section of the Connection String Options reference in the Server Manual. + +The following code example authenticates to Kerberos for UNIX using ``GSSAPI``. + +.. important:: + Always **URI encode** the principal using the ``encodeURIComponent`` method + to ensure it is correctly parsed. + +.. code-block:: js + + const { MongoClient } = require("mongodb"); + + // Replace the placeholder values with the values for your environment in the following lines + const clusterUrl = ""; + const principal = encodeURIComponent(""); + const serviceRealm = ""; + const canonicalizationSetting = ""; + const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`; + + const authMechanism = "GSSAPI"; + + // Connection URI + const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`; + + const client = new MongoClient(uri); + + // Function to connect to the server + async function run() { + try { + // Establish and verify connection + await client.db("admin").command({ ping: 1 }); + console.log("Connected successfully to server"); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } + } + run().catch(console.dir); + +.. note:: + The method refers to the ``GSSAPI`` authentication mechanism instead + of ``Kerberos`` because the driver authenticates through + `GSSAPI RFC-4652 `_, the SASL + mechanism. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/ldap.txt b/source/security/authentication/ldap.txt new file mode 100644 index 000000000..8d2ec793e --- /dev/null +++ b/source/security/authentication/ldap.txt @@ -0,0 +1,87 @@ +.. _node-authentication-ldap: + +===================================== +LDAP (PLAIN) Authentication Mechanism +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example + +Overview +-------- + +The ``PLAIN`` authentication mechanism allows you to use your Lightweight Directory +Access Protocol (LDAP) username and password to authenticate to MongoDB. LDAP +authentication uses the PLAIN Simple Authentication and Security Layer (SASL) +defined in `RFC-4616 `__. + +You can use this mechanism only when authenticating to MongoDB Atlas or MongoDB +Enterprise Advanced. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: Your LDAP username. +- ````: Your LDAP password. +- ````: The network address of your MongoDB deployment. + +To use the code examples, replace these placeholders with your own values. + +LDAP (PLAIN) +------------ + +The ``PLAIN`` authentication mechanism uses your username and password to +authenticate to an LDAP server. + +You can specify this authentication mechanism by setting the ``authMechanism`` +parameter to ``PLAIN`` and including your LDAP username and password in the +:manual:`connection string ` as shown +in the following sample code. + +.. code-block:: js + + const { MongoClient } = require("mongodb"); + + // specify the placeholder values for your environment in the following lines + const clusterUrl = ""; + const ldapUsername = ""; + const ldapPassword = ""; + const authMechanism = "PLAIN"; + + // Connection URI + const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`; + + const client = new MongoClient(uri); + + // Function to connect to the server + async function run() { + try { + // Establish and verify connection + await client.db("admin").command({ ping: 1 }); + console.log("Connected successfully to server"); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } + } + run().catch(console.dir); + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/mechanisms.txt b/source/security/authentication/mechanisms.txt deleted file mode 100644 index 5ba01f5f1..000000000 --- a/source/security/authentication/mechanisms.txt +++ /dev/null @@ -1,369 +0,0 @@ -.. _node-community-authentication-mechanisms: - -========================= -Authentication Mechanisms -========================= - -.. meta:: - :description: Explore sample code for connecting to MongoDB using various authentication mechanisms with the MongoDB Node.js Driver, including `SCRAM-SHA-256`, `SCRAM-SHA-1`, `MONGODB-CR`, `MONGODB-AWS`, and `X.509`. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -In this guide, you can find sample code for connection to MongoDB with each -authentication mechanism available in the MongoDB Community Edition: -``DEFAULT``, ``SCRAM-SHA-256``, ``SCRAM-SHA-1``, ``MONGODB-CR``, -``MONGODB-AWS``, and ``X.509``. - -``DEFAULT`` ------------ - -The ``DEFAULT`` authentication mechanism is a fallback setting that instructs -the driver to negotiate the first authentication mechanism supported by the -server in the following order of preference: - -#. ``SCRAM-SHA-256`` -#. ``SCRAM-SHA-1`` -#. ``MONGODB-CR`` - -If the ``DEFAULT`` option is specified, the driver first attempts to -authenticate using ``SCRAM-SHA-256``. If the version of the MongoDB instance -does not support that mechanism, the driver attempts to authenticate using -``SCRAM-SHA-1``. If the instance does not support that mechanism either, -the driver attempts to authenticate using ``MONGODB-CR``. - -You can specify this authentication mechanism by setting the ``authMechanism`` -parameter to ``DEFAULT`` in the -:manual:`connection string `, or by omitting -the parameter since it is the default value. Also include your username and -password as shown in the code below. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/default.js - :language: javascript - -For more information on the challenge-response (CR) and salted -challenge-response authentication mechanisms (SCRAM) that MongoDB supports, -see the :manual:`SCRAM ` section of the manual. - -``SCRAM-SHA-256`` ------------------ - -.. note:: - - ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting - in version 4.0 - -``SCRAM-SHA-256`` is a salted challenge-response authentication mechanism -(SCRAM) that uses your username and password, encrypted with the ``SHA-256`` -algorithm to authenticate your user. - -You can specify this authentication mechanism by setting the ``authMechanism`` -to the value ``SCRAM-SHA-256`` in the -:manual:`connection string ` as shown in the -following sample code. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/sha256.js - :language: javascript - -``SCRAM-SHA-1`` ---------------- - -.. note:: - ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions - 3.0, 3.2, 3.4, and 3.6. - -``SCRAM-SHA-1`` is a salted challenge-response mechanism (SCRAM) that uses your -username and password, encrypted with the ``SHA-1`` algorithm to authenticate -your user. - -You can specify this authentication mechanism by setting the ``authMechanism`` -parameter to the value ``SCRAM-SHA-1`` in the -:manual:`connection string ` as shown -in the following sample code. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/sha1.js - :language: javascript - -``MONGODB-CR`` --------------- - -.. warning:: - MONGODB-CR was deprecated starting in MongoDB 3.6, and is no longer supported as of MongoDB 4.0 - -``MONGODB-CR`` is a challenge-response authentication mechanism that uses your -username and password to authenticate your user. - -You can specify this option by setting the ``authMechanism`` parameter to value -``MONGODB-CR`` in the -:manual:`connection string ` as shown -in the following sample code. - -.. important:: - Always **URI encode** the username and password using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - -.. literalinclude:: /code-snippets/authentication/cr.js - :language: javascript - -.. important:: - If you have upgraded the authentication schema from MONGODB-CR to SCRAM, - any ``MONGODB-CR`` user authentication requests fail. - -.. _mongodb-aws: - -``MONGODB-AWS`` ---------------- - -.. note:: - The MONGODB-AWS authentication mechanism is available only in MongoDB - versions 4.4 and later. - -The ``MONGODB-AWS`` authentication mechanism uses your Amazon Web Services -Identity and Access Management (AWS IAM) credentials to authenticate your -user. If you do not already have the `AWS signature library -`__, use the following -``npm`` command to install it: - -.. code-block:: bash - - npm install aws4 - -To connect to a MongoDB instance with ``MONGODB-AWS`` authentication -enabled, specify the ``MONGODB-AWS`` authentication mechanism. - -The driver checks for your credentials in the following sources in order: - -1. Connection string -#. Environment variables -#. Web identity token file -#. AWS ECS endpoint specified in ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`` -#. AWS EC2 endpoint. For more information, see `IAM Roles for Tasks - `_. - -.. important:: - - The driver only reads the credentials from the first method that it detects - in the order as given by the preceding list. For example, if you specify - your AWS credentials in the connection string, the driver ignores any - credentials that you specified in environment variables. - -.. tabs:: - - .. tab:: Connection String - :tabid: connection string - - To connect to your MongoDB instance with a connection string, pass - your ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` - credentials to the driver when you attempt to connect. If your AWS - login requires a session token, include your ``AWS_SESSION_TOKEN`` as well. - - The following code shows an example of specifying the ``MONGODB-AWS`` - authentication mechanism and credentials with a connection string: - - .. important:: - - Always **URI encode** the username and certificate file path using the - ``encodeURIComponent`` method to ensure they are correctly parsed. - - .. literalinclude:: /code-snippets/authentication/aws.js - :language: javascript - - .. tab:: Environment Variables - :tabid: environment variables - - To authenticate to your MongoDB instance using AWS credentials stored in - environment variables, set the following variables by using - a shell: - - .. code-block:: bash - - export AWS_ACCESS_KEY_ID= - export AWS_SECRET_ACCESS_KEY= - export AWS_SESSION_TOKEN= - - .. note:: - - Omit the line containing ``AWS_SESSION_TOKEN`` if you don't need an AWS - session token for that role. - - After you've set the preceding environment variables, specify the ``MONGODB-AWS`` - authentication mechanism in your connection string as shown in the following example: - - .. literalinclude:: /code-snippets/authentication/aws-env-variable.js - :language: javascript - - .. tab:: Web Identity Token File - :tabid: web-identity-token-file - - You can use the OpenID Connect (OIDC) token obtained from a web identity - provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or - other services. - - To authenticate with your OIDC token you must first install - `@aws-sdk/credential-providers - `__. You can - install this dependency using the following ``npm`` command: - - .. code-block:: bash - - npm install @aws-sdk/credential-providers - - Next, create a file that contains your OIDC token. Then - set the absolute path to this file in an environment variable by using - a shell as shown in the following example: - - .. code-block:: bash - - export AWS_WEB_IDENTITY_TOKEN_FILE= - - AWS recommends using regional AWS STS endpoints instead of global - endpoints to reduce latency, build-in redundancy, and increase session token validity. - To set the AWS region, set `AWS_REGION `__ - and `AWS_STS_REGIONAL_ENDPOINTS `__ - as environment variables, as shown in the following example: - - .. code-block:: bash - - export AWS_STS_REGIONAL_ENDPOINTS=regional // Enables regional endpoints - export AWS_REGION=us-east-1 // Sets your AWS region - - If both these environment variables aren't set, the default region is - ``us-east-1``. For a list of available AWS regions, see the - `Regional Endpoints `__ - section of the AWS Service Endpoints reference in the AWS documentation. - - .. warning:: Consult your SDK's Documentation for Setting an AWS Region - - You cannot set your AWS region with environment variables for all SDKs, - as in the above example. See your SDK's specific documentation for - configuring an AWS region. - - After you've set the preceding environment variables, specify the ``MONGODB-AWS`` - authentication mechanism in your connection string as shown in the following example: - - .. literalinclude:: /code-snippets/authentication/aws-env-variable.js - :language: javascript - -.. important:: Retrieval of AWS Credentials - - Starting in version 4.11, when you install the optional - ``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK - to retrieve credentials from the environment. As a result, if you - have a shared AWS credentials file or config file, the driver will - use those credentials by default. - - You can override this behavior by performing one of the following - actions: - - - Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point - to your credentials file. - - Set the equivalent environment variable in your application to point - to your credentials file. - - Create an AWS profile for your MongoDB credentials and set the - ``AWS_PROFILE`` environment variable to that profile name. - -``X.509`` ---------- - -.. note:: - The X.509 authentication mechanism is only available in MongoDB versions - 2.6 and later. - -The ``X.509`` authentication mechanism uses -:wikipedia:`TLS ` with X.509 certificates to -authenticate by retrieving the distinguished name (DN) from the -client certificate. - -You can specify this authentication mechanism by setting the following -parameters of your :manual:`connection string `: - -- Set the ``authMechanism`` parameter to ``MONGODB-X509`` -- Set the ``tls`` parameter to ``true`` - -Pass the location of your client certificate file as the value of -``tlsCertificateKeyFile`` as a parameter of the connection URI. - -.. important:: - Always **URI encode** the certificate file path using the - ``encodeURIComponent`` method to ensure it is parsed correctly. - -.. literalinclude:: /code-snippets/authentication/x509.js - :language: javascript - -.. tip:: - - To learn more about enabling TLS on a connection, see - :ref:`node-connect-tls`. - -TLS Options -~~~~~~~~~~~ - -The following table describes the TLS options that you can set in a -connection URI. - -.. list-table:: - :widths: 35 12 10 43 - :header-rows: 1 - - * - Parameter Name - - Type - - Default Value - - Description - - * - ``tls`` - - boolean - - ``false`` - - Specifies whether to enable TLS on the connection. - - * - ``tlsInsecure`` - - boolean - - ``false`` - - Specifies whether to allow invalid certificates and mismatched - hostnames. When set to ``true``, this is equivalent to setting - ``tlsAllowInvalidCertificates`` and ``tlsAllowInvalidHostnames`` to - ``true``. - - * - ``tlsCAFile`` - - string - - - - Path to file that contains a single or bundle of trusted certificate - authorities used in a TLS connection. - - * - ``tlsCertificateKeyFile`` - - string - - - - Path to the client certificate file or the client private key file. If - both are required, the two must be concatenated into a single file. - - * - ``tlsCertificateKeyFilePassword`` - - buffer or string - - - - String or buffer that contains the password to decrypt the client - private key. - - * - ``tlsAllowInvalidCertificates`` - - boolean - - ``false`` - - Specifies whether the driver permits an invalid certificate to be used - to connect. - - * - ``tlsAllowInvalidHostnames`` - - boolean - - ``false`` - - Specifies whether the driver raises an error when there is a mismatch between the - server hostname and TLS certificate hostname. diff --git a/source/security/authentication/enterprise-mechanisms.txt b/source/security/authentication/oidc.txt similarity index 56% rename from source/security/authentication/enterprise-mechanisms.txt rename to source/security/authentication/oidc.txt index a233a857d..23f991912 100644 --- a/source/security/authentication/enterprise-mechanisms.txt +++ b/source/security/authentication/oidc.txt @@ -1,8 +1,8 @@ -.. _node-enterprise-authentication-mechanisms: +.. _node-authentication-oidc: -==================================== -Enterprise Authentication Mechanisms -==================================== +============================= +OIDC Authentication Mechanism +============================= .. contents:: On this page :local: @@ -13,157 +13,39 @@ Enterprise Authentication Mechanisms .. facet:: :name: genre :values: reference - + .. meta:: :keywords: ldap, encryption, principal, tls :description: Explore sample code for connecting to MongoDB using enterprise authentication mechanisms like Kerberos, LDAP, and MONGODB-OIDC with the MongoDB Node.js Driver. -In this guide, you can find sample code for connection to MongoDB with each -authentication mechanism available in the MongoDB Enterprise Edition: -``Kerberos (GSSAPI/SSPI)``, ``LDAP (PLAIN)``, and ``MONGODB-OIDC``. - -Kerberos (GSSAPI/SSPI) ----------------------- - -.. note:: - The Node.js driver supports Kerberos on UNIX using the MIT Kerberos library - and on Windows using the SSPI API. +Overview +-------- -The ``GSSAPI`` authentication mechanism uses your user principal to -authenticate to a Kerberos service. +The OpenID Connect (OIDC) authentication mechanism allows you to authenticate to +MongoDB by using a third-party identity provider, such as Azure or Google Cloud +Platform (GCP). -You can specify this authentication mechanism by performing the -following actions while specifying options on your -:manual:`connection string `: +The MONGODB-OIDC authentication mechanism requires {+mdb-server+} v7.0 or later running +on a Linux platform. You can use this mechanism only when authenticating to MongoDB Atlas +or MongoDB Enterprise Advanced. -- Set the ``authMechanism`` parameter to ``GSSAPI``. -- Set the ``SERVICE_NAME`` value in the ``authMechanismProperties`` - parameter if using a value other than ``mongodb``. -- Specify a ``SERVICE_REALM`` value in the ``authMechanismProperties`` - parameter if a custom service realm is required. -- Specify a ``CANONICALIZE_HOST_NAME`` value in the ``authMechanismProperties`` - parameter if canonicalization of the hostname is required. This property can take - the following values: +.. tip:: Learn More about OIDC Authentication - - ``none``: (Default) Does not perform hostname canonicalization - - ``forward``: Performs a forward DNS lookup to canonicalize the hostname - - ``forwardAndReverse``: Performs a forward DNS lookup and then a - reverse lookup on that value to canonicalize the hostname - -.. important:: + To learn more about configuring MongoDB Atlas for OIDC authentication, see + :atlas:`Set up Workforce Identity Federation with OIDC ` + in the Atlas documentation. - The ``gssapiServiceName`` parameter is deprecated and may be removed - in future versions of the driver. Use - ``authMechanismProperties=SERVICE_NAME:`` in the - connection URI instead. - See the - :manual:`authMechanismProperties ` - parameter documentation for more information. - -The following code sample authenticates to Kerberos for UNIX using ``GSSAPI``. - -.. important:: - Always **URI encode** the principal using the ``encodeURIComponent`` method - to ensure it is correctly parsed. - -.. code-block:: js - - const { MongoClient } = require("mongodb"); - - // specify the placeholder values for your environment in the following lines - const clusterUrl = ""; - const principal = encodeURIComponent(""); - const serviceRealm = ""; - const canonicalizationSetting = ""; - const authMechanismProperties = `SERVICE_REALM:${serviceRealm},CANONICALIZE_HOST_NAME:${canonicalizationSetting}`; - - const authMechanism = "GSSAPI"; - - // Connection URI - const uri = `mongodb+srv://${principal}@${clusterUrl}/?authMechanism=${authMechanism}&authMechanismProperties=${authMechanismProperties}`; - - const client = new MongoClient(uri); - - // Function to connect to the server - async function run() { - try { - // Establish and verify connection - await client.db("admin").command({ ping: 1 }); - console.log("Connected successfully to server"); - } finally { - // Ensures that the client will close when you finish/error - await client.close(); - } - } - run().catch(console.dir); - -.. note:: - The method refers to the ``GSSAPI`` authentication mechanism instead - of ``Kerberos`` because the driver authenticates through - `GSSAPI RFC-4652 `_, the SASL - mechanism. - -LDAP (PLAIN) ------------- - -The ``PLAIN`` authentication mechanism uses your username and password to -authenticate to a Lightweight Directory Access Protocol (LDAP) server. - -You can specify this authentication mechanism by setting the ``authMechanism`` -parameter to ``PLAIN`` and including your LDAP username and password in the -:manual:`connection string ` as shown -in the following sample code. - -.. code-block:: js - - const { MongoClient } = require("mongodb"); - - // specify the placeholder values for your environment in the following lines - const clusterUrl = ""; - const ldapUsername = ""; - const ldapPassword = ""; - const authMechanism = "PLAIN"; - - // Connection URI - const uri = `mongodb+srv://${ldapUsername}:${ldapPassword}@${clusterUrl}/?authMechanism=${authMechanism}`; - - const client = new MongoClient(uri); - - // Function to connect to the server - async function run() { - try { - // Establish and verify connection - await client.db("admin").command({ ping: 1 }); - console.log("Connected successfully to server"); - } finally { - // Ensures that the client will close when you finish/error - await client.close(); - } - } - run().catch(console.dir); - -.. note:: - The authentication mechanism is named ``PLAIN`` instead of ``LDAP`` since it - authenticates using the `PLAIN Simple Authentication and Security Layer - (SASL) defined in RFC-4616 `_. - -.. _node-enterprise-auth-oidc: - -MONGODB-OIDC ------------- - -.. important:: + To learn more about using OIDC authentication with MongoDB, see + :manual:`Authentication and Authorization with OIDC/OAuth 2.0 ` and + :manual:`oidcIdentityProviders ` + in the {+mdb-server+} manual. - The MONGODB-OIDC authentication mechanism requires {+mdb-server+} v7.0 or later running - on a Linux platform. -The following sections describe how to use the MONGODB-OIDC authentication mechanism to -authenticate from various platforms. +Specify OIDC Authentication +--------------------------- -For more information about the MONGODB-OIDC authentication mechanism, see -:manual:`OpenID Connect Authentication ` and -:manual:`MongoDB Server Parameters ` -in the {+mdb-server+} manual. +The following sections describe how to use the ``MONGODB-OIDC`` authentication +mechanism to authenticate from various platforms. .. _node-mongodb-oidc-azure-imds: @@ -197,9 +79,9 @@ The following code example shows how to set the preceding connection options: const uri = "mongodb+srv://@:/?authMechanism=MONGODB-OIDC" + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:"; - const client = new MongoClient(uri); + const client = new MongoClient(uri); -.. _node-mongodb-oidc-gcp-imds: +.. _node-mongodb-oidc-gcp-imds: GCP IMDS ~~~~~~~~ @@ -376,4 +258,4 @@ guide, see the following API documentation: - `MongoClient <{+api+}/classes/MongoClient.html>`__ - `OIDCCallbackParams <{+api+}/interfaces/OIDCCallbackParams.html>`__ -- `OIDCResponse <{+api+}/interfaces/OIDCResponse.html>`__ \ No newline at end of file +- `OIDCResponse <{+api+}/interfaces/OIDCResponse.html>`__ diff --git a/source/security/authentication/scram.txt b/source/security/authentication/scram.txt new file mode 100644 index 000000000..d11fed75b --- /dev/null +++ b/source/security/authentication/scram.txt @@ -0,0 +1,141 @@ +.. _node-authentication-scram: + +=============================== +SCRAM Authentication Mechanisms +=============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: salt, default, code example + +Overview +-------- + +**Salted Challenge Response Authentication Mechanism (SCRAM)** is a family of +authentication mechanisms that use a challenge-response mechanism to authenticate +the user. SCRAM-SHA-256, which uses the SHA-256 algorithm to hash your password, is the +default authentication mechanism in {+mdb-server+} version 4.0 +and later. SCRAM-SHA-1, which uses the SHA-1 algorithm instead, is the default +authentication mechanism in {+mdb-server+} versions earlier than 4.0. + +You can use SCRAM to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: SCRAM Mechanisms + + To learn more about the SCRAM family of authentication mechanisms, see + `RFC 5802 `__ and + :wikipedia:`Salted Challenge Response Authentication Mechanism ` + on Wikipedia. + + For more information about the MongoDB implementation of SCRAM, see + :manual:`SCRAM ` in the {+mdb-server+} manual. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: The MongoDB username of the user to authenticate. +- ````: The MongoDB password of the user to authenticate. +- ````: The network address of your MongoDB deployment. + +To use the code examples, replace these placeholders with your own values. + +Default Authentication Mechanism +-------------------------------- + +The ``DEFAULT`` authentication mechanism is a fallback setting that instructs +the driver to negotiate the first authentication mechanism supported by the +server in the following order of preference: + +#. ``SCRAM-SHA-256`` +#. ``SCRAM-SHA-1`` +#. ``MONGODB-CR`` + +If the ``DEFAULT`` option is specified, the driver first attempts to +authenticate using ``SCRAM-SHA-256``. If the version of the MongoDB instance +does not support that mechanism, the driver attempts to authenticate using +``SCRAM-SHA-1``. If the instance does not support that mechanism either, +the driver attempts to authenticate using ``MONGODB-CR``. + +You can specify the default authentication mechanism by setting the +``authMechanism`` parameter to ``DEFAULT`` in the connection string, or by +omitting the parameter since it is the default value. + +The following example shows how to set the authentication mechanism to the +default by setting ``authMechanism`` to ``DEFAULT`` in the connection string: + +.. important:: + Always **URI encode** the username and password using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + +.. literalinclude:: /code-snippets/authentication/default.js + :language: javascript + +To learn more about the SCRAM version that MongoDB supports, +see the :manual:`SCRAM ` section of the {+mdb-server+} +manual. + +SCRAM-SHA-256 +------------- + +.. note:: + + ``SCRAM-SHA-256`` is the default authentication method for MongoDB starting + in version 4.0 + +``SCRAM-SHA-256`` is a SCRAM version that uses your username and password, +encrypted with the ``SHA-256`` algorithm to authenticate your user. + +You can specify this authentication mechanism by setting the ``authMechanism`` +to the value ``SCRAM-SHA-256`` in the +:manual:`connection string ` as shown in the +following sample code. + +.. important:: + Always **URI encode** the username and password using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + +.. literalinclude:: /code-snippets/authentication/sha256.js + :language: javascript + +``SCRAM-SHA-1`` +--------------- + +.. note:: + ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions + 3.0, 3.2, 3.4, and 3.6. + +``SCRAM-SHA-1`` is a SCRAM version that uses your +username and password, encrypted with the ``SHA-1`` algorithm to authenticate +your user. + +You can specify this authentication mechanism by setting the ``authMechanism`` +parameter to the value ``SCRAM-SHA-1`` in the +:manual:`connection string ` as shown +in the following sample code. + +.. important:: + Always **URI encode** the username and password using the + ``encodeURIComponent`` method to ensure they are correctly parsed. + +.. literalinclude:: /code-snippets/authentication/sha1.js + :language: javascript + +API Documentation +----------------- + +To learn more about any of the methods or types discussed on this +page, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ diff --git a/source/security/authentication/x509.txt b/source/security/authentication/x509.txt new file mode 100644 index 000000000..3595f9082 --- /dev/null +++ b/source/security/authentication/x509.txt @@ -0,0 +1,122 @@ +.. _node-authentication-x509: + +============================== +X.509 Authentication Mechanism +============================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: certificate, code example + +Overview +-------- + +In the **X.509** authentication mechanism, the server and client use the +:wikipedia:`TLS ` protocol to exchange X.509 public-key +certificates. You can use this mechanism to authenticate to MongoDB Atlas, MongoDB +Enterprise Advanced, and MongoDB Community Edition. + +.. tip:: X.509 Mechanism + + To learn how to use TLS/SSL with the {+driver-short+}, + see the :ref:`node-tls` guide. + + For more information about X.509 certificates, see + :manual:`Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments + ` in the {+mdb-server+} manual. + +Code Placeholders +~~~~~~~~~~~~~~~~~ + +The code examples on this page use the following placeholders: + +- ````: The network address of your MongoDB deployment. +- ````: The path to your client PEM certificate file. + +To use the code examples, replace these placeholders with your own values. + +Specify X.509 Authentication +---------------------------- + +You can specify this authentication mechanism by setting the following +parameters of your :manual:`connection string `: + +- Set the ``authMechanism`` parameter to ``MONGODB-X509`` +- Set the ``tls`` parameter to ``true`` + +Pass the location of your client certificate file as the value of +``tlsCertificateKeyFile`` as a parameter of the connection URI. + +.. important:: + Always **URI encode** the certificate file path using the + ``encodeURIComponent`` method to ensure it is parsed correctly. + +.. literalinclude:: /code-snippets/authentication/x509.js + :language: javascript + +TLS Options +~~~~~~~~~~~ + +The following table describes the TLS options that you can set in a +connection URI. + +.. list-table:: + :widths: 35 12 10 43 + :header-rows: 1 + + * - Parameter Name + - Type + - Default Value + - Description + + * - ``tls`` + - boolean + - ``false`` + - Specifies whether to enable TLS on the connection. + + * - ``tlsInsecure`` + - boolean + - ``false`` + - Specifies whether to allow invalid certificates and mismatched + hostnames. When set to ``true``, this is equivalent to setting + ``tlsAllowInvalidCertificates`` and ``tlsAllowInvalidHostnames`` to + ``true``. + + * - ``tlsCAFile`` + - string + - + - Path to file that contains a single or bundle of trusted certificate + authorities used in a TLS connection. + + * - ``tlsCertificateKeyFile`` + - string + - + - Path to the client certificate file or the client private key file. If + both are required, the two must be concatenated into a single file. + + * - ``tlsCertificateKeyFilePassword`` + - buffer or string + - + - String or buffer that contains the password to decrypt the client + private key. + + * - ``tlsAllowInvalidCertificates`` + - boolean + - ``false`` + - Specifies whether the driver permits an invalid certificate to be used + to connect. + + * - ``tlsAllowInvalidHostnames`` + - boolean + - ``false`` + - Specifies whether the driver raises an error when there is a mismatch between the + server hostname and TLS certificate hostname. From 84f9b547a76c408871e21e281cc0e7ae41624c00 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Wed, 26 Mar 2025 19:23:13 -0400 Subject: [PATCH 09/26] DOCSP-48379 Connection Targets (#1043) * DOCSP-48379 Connection Targets * edits * edits * last edits * one more * ignoring vale check * eol for file * NR review * vale check --- source/connect/connection-targets.txt | 93 ++++++++++++++++++- source/includes/connect/connection-targets.js | 43 +++++++++ 2 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 source/includes/connect/connection-targets.js diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index df72aba8a..e4f2ead4d 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -15,4 +15,95 @@ Choose a Connection Target :local: :backlinks: none :depth: 2 - :class: singlecol \ No newline at end of file + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use a connection string and a ``MongoClient`` +object to connect to different types of MongoDB deployments. + +.. tip:: + + To learn more about how to retrieve your connection string, see + the :atlas:`Connect via Drivers ` guide in + the Atlas documentation. + +Atlas +----- + +To connect to a MongoDB deployment on Atlas, include the following elements +in your connection string: + +- URL of your Atlas cluster +- MongoDB username +- MongoDB password + +Then, pass your connection string to the ``MongoClient`` constructor. + +When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid +breaking changes when Atlas upgrades to a new version of {+mdb-server+}. +To learn more about the {+stable-api+} feature, see the :ref:`` +guide. + +The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The +code also uses the ``server_api`` field to specify a {+stable-api+} version. + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-connection-target-atlas + :end-before: end-connection-target-atlas + :dedent: + +Local Deployments +----------------- + +To connect to a local standalone MongoDB deployment, specify the host of the +server. Optionally, specify the port of the server. If no port is specified, +the default port is ``27017``. + +You can specify the host and port to connect to by using a +connection string, as shown in the following code: + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-local-connection-uri + :end-before: end-local-connection-uri + :dedent: + +You can also specify your host as ``localhost``. The following code example +connects to ``localhost`` on the specified port: + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-localhost + :end-before: end-localhost + :dedent: + +Replica Sets +------------ + +To connect to a replica set, we recommend that you specify all nodes that are +part of the replica set. If one or more nodes becomes unavailable, +specifying all nodes allows the driver to still connect to the replica set +if one node is available. + +However, it is sufficient to pass the address of any one node in the replica set +to the driver. The node does not need to be the primary, and it may be a hidden node. +The driver will then automatically discover the remaining nodes. + +The following example shows how to connect to the replica set by using a connection +string and how to verify the replica set name on connection by using the +``replicaSet`` connection string option: + +.. literalinclude:: /includes/connect/connection-targets.js + :language: javascript + :start-after: start-replica-set-option + :end-before: end-replica-set-option + :dedent: + +API Documentation +----------------- + +To learn more about creating a ``MongoClient`` object with the {+driver-short+}, +see the API documentation for `MongoClient <{+api+}/classes/MongoClient.html>`__ . diff --git a/source/includes/connect/connection-targets.js b/source/includes/connect/connection-targets.js new file mode 100644 index 000000000..c71cd9935 --- /dev/null +++ b/source/includes/connect/connection-targets.js @@ -0,0 +1,43 @@ +// start-connection-target-atlas +const { MongoClient, ServerApiVersion } = require("mongodb"); + +// Replace the placeholder with your Atlas connection string +const uri = ""; + +// Creates a MongoClient with a MongoClientOptions object to set the Stable API version +const client = new MongoClient(uri, { + serverApi: { + version: ServerApiVersion.v1, + strict: true, + deprecationErrors: true, + } + } +); + +async function run() { + try { + // Connects the client to the server (optional starting in v4.7) + await client.connect(); + + // Sends a ping to confirm a successful connection + await client.db("admin").command({ ping: 1 }); + console.log("Pinged your deployment. You successfully connected to MongoDB!"); + } finally { + // Ensures that the client will close when you finish/error + await client.close(); + } +} +run().catch(console.dir); +// end-connection-target-atlas + +// start-local-connection-uri +const client = new MongoClient("mongodb://host1:27017"); +// end-local-connection-uri + +// start-localhost +const client = new MongoClient("mongodb://localhost:27017"); +// end-localhost + +// start-replica-set-option +const client = new MongoClient("mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRs"); +// end-replica-set-option From 44f67d6ac2d4d7f93955df4cbb47eb5a8a7afe45 Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 31 Mar 2025 10:59:36 -0400 Subject: [PATCH 10/26] DOCSP-48381 make specify docs page (#1037) * make specify docs page * fix includes link * fix link * fix highlighting and links * remove passive * nr feedback * final edits * fix typo * nr feedback * tech review * fix wording * Fix spacing * spacing change * Update connection-targets.txt * Update access-cursor-note.rst * Update access-cursor-note.rst --- source/connect/connection-targets.txt | 2 + .../query/specify-documents-to-return.txt | 311 +++++++++++++++++- source/includes/access-cursor-note.rst | 2 +- 3 files changed, 311 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index e4f2ead4d..20e3d09e2 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -16,6 +16,8 @@ Choose a Connection Target :backlinks: none :depth: 2 :class: singlecol + +.. _node-other-ways-to-connect: Overview -------- diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 508f266ea..b1f225c15 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -23,6 +23,311 @@ Overview In this guide, you can learn how to specify which documents to return from a read operation by using the following methods: -- ``limit``: Specifies the maximum number of documents to return from a query. -- ``sort``: Specifies the sort order for the returned documents. -- ``skip``: Specifies the number of documents to skip before returning query results. \ No newline at end of file +- ``sort()``: Specifies the sort order for the returned documents. +- ``limit()``: Specifies the maximum number of documents to return from a query. +- ``skip()``: Specifies the number of documents to skip before returning query results. + +You can use these methods either by chaining them to your read operation or by specifying them in an +``options`` object in your call to your read operation. + +.. note:: + + If you chain ``sort()``, ``limit()``, or ``skip()`` to a read operation, you must + specify all methods before iterating the cursor. If you specify a method after + iterating the cursor, the method you specified does not apply to the operation. + +Sample Data for Examples +~~~~~~~~~~~~~~~~~~~~~~~~ + +To run the examples in this guide, use the following code snippet to insert documents +that describe books into the ``myDB.books`` collection: + +.. code-block:: javascript + + const myDB = client.db("myDB"); + const myColl = myDB.collection("books"); + + await myColl.insertMany([ + { "_id": 1, "name": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }, + { "_id": 2, "name": "Les Misérables", "author": "Hugo", "length": 1462 }, + { "_id": 3, "name": "Atlas Shrugged", "author": "Rand", "length": 1088 }, + { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, + { "_id": 5, "name": "Cryptonomicon", "author": "Stephenson", "length": 918 }, + { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 }, + ]); + +.. include:: /includes/access-cursor-note.rst + +.. _node-fundamentals-sort: + +Sort +---- + +Use the ``sort()`` method to change the order in which read operations return +documents. This method tells MongoDB to order returned documents by the +values of one or more fields in a certain direction. To sort returned +documents by a field in ascending (lowest first) order, use a value of +``1``. To sort in descending (greatest first) order instead, use ``-1``. +If you do not specify a sort, MongoDB does not guarantee the order of +query results. + +The following example passes the sort document to a read operation to ensure that the +operation returns books with longer lengths before books with shorter +lengths: + +.. code-block:: javascript + :emphasize-lines: 4 + + // define an empty query document + const query = {}; + // sort in descending (-1) order by length + const sort = { length: -1 }; + const cursor = myColl.find(query).sort(sort); + for await (const doc of cursor) { + console.dir(doc); + } + +In this case, the number ``-1`` tells the read operation to sort the +books in descending order by length. ``find()`` returns the following +documents when this sort is used with an empty query: + +.. code-block:: json + :copyable: false + + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + { "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 } + { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } + { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } + { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } + +Sometimes, the order of two or more documents is ambiguous using a specified sort. In the +preceding example, the documents that have ``title`` values of ``"A Dance with Dragons"`` and +``"Infinite Jest"`` both have a ``length`` of ``1104``, so the order in which they are +returned is not guaranteed. To resolve ties in your sorted results in a repeatable way, +add more fields to the sort document: + +.. code-block:: javascript + :emphasize-lines: 4 + + // define an empty query document + const query = {}; + // sort in ascending (1) order by length + const sort = { length: 1, author: 1 }; + const cursor = myColl.find(query).sort(sort); + for await (const doc of cursor) { + console.dir(doc); + } + +With the addition of the ``author`` field to the sort document, the read operation sorts +matching documents first by ``length`` then, if there is a tie, by ``author``. Matched +document fields are compared in the same order as fields are specified in the sort +document. ``find()`` returns the following ordering of documents when this sort is used on +the documents matching the query: + +.. code-block:: json + :copyable: false + + { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } + { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } + { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } + { "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + +.. _node-fundamentals-limit: + +Limit +----- + +Use the ``limit()`` method to cap the number of documents that can be returned from a read +operation. This method specifies the maximum number of documents that the operation can +return, but the operation can return a smaller number of documents if there are not enough +documents present to reach the limit. If ``limit()`` is used with the :ref:`skip() +` method, the skip applies first and the limit only applies to the +documents left over after the skip. + +This example performs the following actions: + +- Uses an empty query filter to match all documents in the collection +- Calls the ``sort()`` method to apply a descending sort on the ``length`` field to the results +- Calls the ``limit()`` method to return only the first ``3`` results + +.. code-block:: javascript + :emphasize-lines: 5 + + // define an empty query document + const query = {}; + // sort in descending (-1) order by length + const sort = { length: -1 }; + const limit = 3; + const cursor = myColl.find(query).sort(sort).limit(limit); + for await (const doc of cursor) { + console.dir(doc); + } + +The code example above outputs the following three documents, sorted by +length: + +.. code-block:: json + :copyable: false + + { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } + { "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 } + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + +.. note:: + + The order in which you call ``limit()`` and ``sort()`` does not matter because the + driver reorders the calls to apply the sort first. The following two calls are + equivalent: + + .. code-block:: javascript + + myColl.find(query).sort({ length: -1 }).limit(3); + myColl.find(query).limit(3).sort({ length: -1 }); + +You can also apply ``sort()`` and ``limit()`` by specifying them in an +``options`` object in your call to the ``find()`` method. The following two +calls are equivalent: + +.. code-block:: javascript + + myColl.find(query).sort({ length: -1 }).limit(3); + myColl.find(query, { sort: { length: -1 }, limit: 3 }); + +For more information on the ``options`` settings for the ``find()`` +method, see the +`API documentation on find() <{+api+}/classes/Collection.html#find>`__. + +.. _node-fundamentals-skip: + +Skip +---- + +Use the ``skip()`` method to omit documents from the beginning of the read operation +results. You can combine ``skip()`` with +:ref:`sort() ` to omit the top +(for descending order) or bottom (for ascending order) results for a +given query. Since the :manual:`order of documents returned +` is not guaranteed in +the absence of a sort, using ``skip()`` without using ``sort()`` omits +arbitrary documents. + +If the value of ``skip()`` exceeds the number of matched documents for +a query, then that query returns no documents. + +This example queries the collection for the books with the fifth and sixth highest lengths +by performing the following actions: + +- Uses an empty query filter to match all documents in the collection +- Calls the ``sort()`` method to apply a descending sort to the ``length`` field, which returns longer books before shorter books +- Calls the ``skip()`` method to omit the first four matching documents from the result + +.. code-block:: javascript + + // define an empty query document + const query = {}; + const sort = { length: -1 }; + const skip = 4; + const cursor = myColl.find(query).sort(sort).skip(skip); + for await (const doc of cursor) { + console.dir(doc); + } + +Since the query skips the first four matching documents, the preceding code snippet prints +the fifth and sixth highest length documents: + +.. code-block:: json + :copyable: false + + { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } + { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } + +You can also apply ``skip()`` and ``sort()`` by specifying them in an +``options`` object in your call to the ``find()`` method. The following two +calls are equivalent: + +.. code-block:: javascript + + myColl.find(query).sort({ length: -1 }).skip(4); + myColl.find(query, { sort: { length: -1 }, skip: 4}); + +For more information on the ``options`` settings for the ``find()`` +method, see the +`API documentation on find() <{+api+}/classes/Collection.html#find>`__. + +.. _node-fundamentals-combine-lim-sort-skip: + +Combine Limit, Sort, and Skip +----------------------------- + +You can combine the ``limit``, ``sort``, and ``skip`` options in a single +operation. This allows you to set a maximum number of sorted documents to +return, skipping a specified number of documents before returning. + +The following example returns documents with the ``length`` value of +``"1104"``. The results are sorted in alphabetical order, skipping the first +document and includes only the first result: + +.. code-block:: javascript + + // define a query to look for length value of 1104 + const query = {length: "1104"}; + const options = { + // sort in alphabetical (1) order by title + sort : { title: 1 }, + // omit the first document + skip : 1, + // returns only the first result + limit: 1, + } + const cursor = myColl.find(query, options); + for await (const doc of cursor) { + console.dir(doc); + } + +.. code-block:: json + :copyable: false + + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + +.. note:: + + The order in which you call these methods doesn't change the documents + that are returned. The driver automatically reorders the calls to perform the + sort and skip operations first, and the limit operation afterward. + +You can also limit, sort, and skip results by chaining each method to the ``find`` method. +The following example specifies the same query as the preceding example: + +.. io-code-block:: + + .. input:: + :language: javascript + + myColl.find(query).sort({ title: 1 }).skip(1).limit(1); + + .. output:: + :language: json + :visible: false + + { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } + +Additional Information +---------------------- + +For more information about specifying a query, see :ref:`node-query`. + +For more information about retrieving documents, see :ref:`node-fundamentals-retrieve-data`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods discussed in this +guide, see the following API documentation: + +- `find() <{+api+}/classes/Collection.html#find>`__ +- `limit() <{+api+}/classes/FindCursor.html#limit>`__ +- `sort() <{+api+}/classes/FindCursor.html#sort>`__ +- `skip() <{+api+}/classes/FindCursor.html#skip>`__ \ No newline at end of file diff --git a/source/includes/access-cursor-note.rst b/source/includes/access-cursor-note.rst index c3ad63f56..c72bac066 100644 --- a/source/includes/access-cursor-note.rst +++ b/source/includes/access-cursor-note.rst @@ -3,4 +3,4 @@ Your query operation may return a reference to a cursor that contains matching documents. To learn how to examine data stored in the cursor, see the - :doc:`Cursor Fundamentals page `. \ No newline at end of file + :ref:`Access Data From a Cursor page `. From 5a5b43cb4fe5fa2ba8e8c9e450fb832b3f3b59d2 Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 31 Mar 2025 11:00:30 -0400 Subject: [PATCH 11/26] DOCSP-48388 break up faq (#1048) * break up faq * vale errors * fix vale error * wording * add redirect * remove faq * change headlines * js feedback * bp edits * bp feedback --- config/redirects | 1 + source/connect/connection-options.txt | 117 +++++- .../connection-options/connection-pools.txt | 113 +++++- source/connect/connection-troubleshooting.txt | 110 ++++-- source/connect/mongoclient.txt | 52 ++- source/faq.txt | 369 ------------------ 6 files changed, 363 insertions(+), 399 deletions(-) delete mode 100644 source/faq.txt diff --git a/config/redirects b/config/redirects index 01eef4fe5..38b67ad50 100644 --- a/config/redirects +++ b/config/redirects @@ -10,6 +10,7 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${base}/${version}/fundamentals/stable-api/ [*-master]: ${prefix}/${version}/fundamentals/connection/lambda/ -> ${base}/${version}/fundamentals/connection/ [*-master]: ${prefix}/${version}/fundamentals/csfle -> ${base}/${version}/fundamentals/encrypt-fields/ +[*-master]: ${prefix}/${version}/faq/ -> ${base}/${version}/ [*-v5.0]: ${prefix}/${version}/quick-start/connect-to-mongodb/ -> ${base}/${version}/quick-start/ [*-v5.0]: ${prefix}/${version}/quick-start/create-a-connection-string/ -> ${base}/${version}/quick-start/ diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index bf0a7d130..eb89bdf0e 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -92,9 +92,9 @@ string, see :manual:`Connection Strings ` in the * - **connectTimeoutMS** - non-negative integer - ``30000`` - - Specifies the amount of time, in milliseconds, to wait to establish a single TCP + - Specifies the amount of time in milliseconds to wait to establish a single TCP socket connection to the server before raising an error. Specifying - ``0`` disables the connection timeout. + ``0`` means your application sets an infinite socket timeout when establishing a socket. * - **directConnection** - boolean @@ -256,8 +256,9 @@ string, see :manual:`Connection Strings ` in the * - **socketTimeoutMS** - non-negative integer - ``0`` - - Specifies the amount of time, in milliseconds, spent attempting to send or receive on a - socket before timing out. Specifying ``0`` means no timeout. + - Specifies the amount of time in milliseconds spent attempting to send or receive + on a socket before timing out. Specifying ``0`` means your application sets an + infinite socket timeout when establishing a socket. * - **srvMaxHosts** - non-negative integer @@ -344,6 +345,114 @@ string, see :manual:`Connection Strings ` in the no compression, ``1`` signifies the fastest speed, and ``9`` signifies the best compression. See :ref:`node-network-compression` for more information. +Connection Time Out Options +--------------------------- + +.. list-table:: + :widths: 22 78 + :header-rows: 1 + + * - Setting + - Description + + * - **connectTimeoutMS** + - ``connectTimeoutMS`` is a :ref:`connection option + ` that sets the time, in milliseconds, + for an individual connection from your connection pool to + establish a TCP connection to the {+mdb-server+} before + timing out. To modify the allowed time for + `MongoClient.connect <{+api+}/classes/MongoClient.html#connect>`__ to establish a + connection to a {+mdb-server+}, use the ``serverSelectionTimeoutMS`` option instead. + + **Default:** 30000 + + * - **socketTimeoutMS** + - ``socketTimeoutMS`` specifies the amount of time the driver waits + for an inactive socket before closing it. The default value is to + never time out the socket. This option applies only to sockets that + have already been connected. + + * - **maxTimeMS** + - `maxTimeMS <{+api+}/classes/FindCursor.html#maxTimeMS>`__ + specifies the maximum amount of time that the server + waits for an operation to complete after it has reached the + server. If an operation runs over the specified time limit, it + returns a timeout error. You can pass ``maxTimeMS`` only to an + individual operation or to a cursor. + +To specify the optional settings for your ``MongoClient``, declare one or +more available settings in the ``options`` object of the constructor as +follows: + +.. code-block:: javascript + + const client = new MongoClient(uri, { + connectTimeoutMS: , + socketTimeoutMS: + }); + +To see all the available settings, see the +`MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +API Documentation. + +To specify ``maxTimeMS``, pass in the ``maxTimeMS`` method as an option with a timeout +specification to an operation that returns a ``Cursor``: + +.. code-block:: javascript + + const Cursor = collection.distinct('my-key', { maxTimeMS: 50 }); + +Close Sockets After Connection +------------------------------ + +If you experience unexpected network behavior or if a MongoDB process +fails with an error, you might not receive confirmation that the +driver correctly closed the corresponding socket. + +To make sure that the driver correctly closes the socket in these cases, +set the ``socketTimeoutMS`` option. When a MongoDB process times out, the driver +will close the socket. We recommend that you select a value +for ``socketTimeoutMS`` that is two to three times longer than the +expected duration of the slowest operation that your application executes. + +Prevent Long-Running Operations From Slowing Down the Server +------------------------------------------------------------ + +You can prevent long-running operations from slowing down the server by +specifying a timeout value. You can chain the ``maxTimeMS()`` method to +an operation that returns a ``Cursor`` to set a timeout on a specific action. + +The following example shows how you can chain the ``maxTimeMS()`` method +to an operation that returns a ``Cursor``: + +.. literalinclude:: /code-snippets/faq/maxTimeMS-example.js + :language: javascript + +.. _node-faq-keepalive: + +keepAlive Connection Option +--------------------------- + +The ``keepAlive`` connection option specifies whether to enable +:wikipedia:`Transmission Control Protocol (TCP) keepalives +` on a TCP socket. If you enable keepalives, +the driver checks whether the connection is active by sending periodic pings +to your MongoDB deployment. This functionality works only if your +operating system supports the ``SO_KEEPALIVE`` socket option. + +The ``keepAliveInitialDelay`` option specifies the number of +milliseconds that the driver waits before initiating a keepalive. + +The 5.3 driver version release deprecated these options. Starting in +version 6.0 of the driver, the ``keepAlive`` option is permanently set +to ``true``, and the ``keepAliveInitialDelay`` is set to 300000 +milliseconds (300 seconds). + +.. warning:: + + If your firewall ignores or drops the keepalive messages, you might + not be able to identify dropped connections. + Additional Information ---------------------- diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 2050239bf..97fa3533a 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -27,4 +27,115 @@ gets a connection from the pool, performs operations, and returns the connection to the pool for reuse. Connection pools help reduce application latency and the number of times new connections -are created by {+driver-short+}. \ No newline at end of file +are created by {+driver-short+}. + +.. _node-faq-connection-pool: + +Connection Pool Overview +------------------------- + +Every ``MongoClient`` instance has a built-in connection pool for each server +in your MongoDB topology. Connection pools open sockets on demand to +support concurrent requests to MongoDB in your application. + +The maximum size of each connection pool is set by the ``maxPoolSize`` option, which +defaults to ``100``. If the number of in-use connections to a server reaches +the value of ``maxPoolSize``, the next request to that server will wait +until a connection becomes available. + +In addition to the sockets needed to support your application's requests, +each ``MongoClient`` instance opens two more sockets per server +in your MongoDB topology for monitoring the server's state. +For example, a client connected to a three-node replica set opens six +monitoring sockets. If the application uses the default setting for +``maxPoolSize`` and only queries the primary (default) node, then +there can be at most ``106`` total connections in the connection pool. If the +application uses a :ref:`read preference ` to query the +secondary nodes, those connection pools grow and there can be +``306`` total connections. + +To support high numbers of concurrent MongoDB requests +within one process, you can increase ``maxPoolSize``. + +Connection pools are rate-limited. The ``maxConnecting`` option +determines the number of connections that the pool can create in +parallel at any time. For example, if the value of ``maxConnecting`` is +``2``, the third request that attempts to concurrently check out a +connection succeeds only when one the following cases occurs: + +- The connection pool finishes creating a connection and there are fewer + than ``maxPoolSize`` connections in the pool. +- An existing connection is checked back into the pool. +- The driver's ability to reuse existing connections improves due to + rate-limits on connection creation. + +You can set the minimum number of concurrent connections to +each server with the ``minPoolSize`` option, which defaults to ``0``. +The driver initializes the connection pool with this number of sockets. If +sockets are closed, causing the total number +of sockets (both in use and idle) to drop below the minimum, more +sockets are opened until the minimum is reached. + +You can set the maximum number of milliseconds that a connection can +remain idle in the pool by setting the ``maxIdleTimeMS`` option. +Once a connection has been idle for ``maxIdleTimeMS``, the connection +pool removes and replaces it. This option defaults to ``0`` (no limit). + +The following default configuration for a ``MongoClient`` works for most +applications: + +.. code-block:: js + + const client = new MongoClient(""); + +``MongoClient`` supports multiple concurrent requests. For each process, +create a client and reuse it for all operations in a process. This +practice is more efficient than creating a client for each request. + +The driver does not limit the number of requests that +can wait for sockets to become available, and it is the application's +responsibility to limit the size of its pool to bound queuing +during a load spike. Requests wait for the amount of time specified in +the ``waitQueueTimeoutMS`` option, which defaults to ``0`` (no limit). + +A request that waits more than the length of time defined by +``waitQueueTimeoutMS`` for a socket raises a connection error. Use this +option if it is more important to bound the duration of operations +during a load spike than it is to complete every operation. + +When ``MongoClient.close()`` is called by any request, the driver +closes all idle sockets and closes all sockets that are in +use as they are returned to the pool. Calling ``MongoClient.close()`` +closes only inactive sockets and does not directly terminate +any ongoing operations. The driver closes any in-use sockets only when +the associated operations complete. However, the ``MongoClient.close()`` +method does close existing sessions and transactions, which might indirectly +affect the behavior of ongoing operations and open cursors. + +Avoid Socket Timeouts +--------------------- + +Having a large connection pool does not always reduce reconnection +requests. Consider the following example: + +An application has a connection pool size of 5 sockets and has the +``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur, +on average, every 3000 milliseconds, and reconnection requests are +frequent. Each socket times out after 5000 milliseconds, which means +that all sockets must do something during those 5000 milliseconds to +avoid closing. + +One message every 3000 milliseconds is not enough to keep the sockets +active, so several of the sockets will time out after 5000 milliseconds. +To avoid excessive socket timeouts, reduce the number of connections +that the driver can maintain in the connection pool by specifying the +``maxPoolSize`` option. + +To specify the optional ``maxPoolSize`` setting for your ``MongoClient``, declare +it in the ``options`` object of the constructor as follows: + +.. code-block:: javascript + + const client = new MongoClient(uri, { + maxPoolSize: , + }); \ No newline at end of file diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index db3f56544..efa64b9ab 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -26,8 +26,6 @@ using the {+driver-long+} to connect to a MongoDB deployment. This page addresses only connection issues. If you encounter any other issues with MongoDB or the driver, visit the following resources: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} - The :ref:`Issues & Help ` page, which has information about reporting bugs, contributing to the driver, and finding more resources @@ -35,7 +33,7 @@ using the {+driver-long+} to connect to a MongoDB deployment. questions, discussions, or general technical support Connection Error -~~~~~~~~~~~~~~~~ +---------------- The following error message indicates that the driver cannot connect to a server on the specified hostname or port. Multiple situations can generate this error @@ -53,7 +51,7 @@ issue. .. _node-troubleshooting-connection-string-port: Check Your Connection String ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Verify that the hostname and port number in the connection string are both accurate. The default port value for a MongoDB instance is @@ -62,7 +60,7 @@ accurate. The default port value for a MongoDB instance is .. _node-troubleshooting-connection-firewall: Configure Your Firewall ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Verify that the ports your MongoDB deployment listens on are not blocked by a firewall on the same network. MongoDB uses port ``27017`` by default. To learn @@ -75,7 +73,7 @@ more about the default ports MongoDB uses and how to change them, see used by your MongoDB deployment. ECONNREFUSED Error -~~~~~~~~~~~~~~~~~~ +------------------ If the connection is refused when the driver attempts to connect to the MongoDB instance, it generates this error message: @@ -89,7 +87,7 @@ The following sections describe actions you can take to potentially resolve the issue. Ensure MongoDB and Your Client Use the Same Protocol ----------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both the client and host support both. For example, if MongoDB uses IPv4 and your @@ -112,7 +110,7 @@ specifying ``family: 4`` as an }); ECONNRESET Error -~~~~~~~~~~~~~~~~ +---------------- If the connection is reset when the driver calls ``client.connect()``, it generates this error message: @@ -125,7 +123,7 @@ generates this error message: The following section describes a method that may help resolve the issue. Control the Number of File Descriptors --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A file descriptor is a unique identifier associated with an open process. In most operating systems, each open connection from the driver is associated with a @@ -143,7 +141,7 @@ file descriptor limit in your operating system. Always be cautious when changing the configuration of your operating system. Authentication Error -~~~~~~~~~~~~~~~~~~~~ +-------------------- The {+driver-short+} can fail to connect to a MongoDB instance if the authorization is not configured correctly. If you are using ``SCRAM-SHA-256`` @@ -169,7 +167,7 @@ issue. .. _node-troubleshooting-connection-string-auth: Check Your Connection String ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An invalid connection string is the most common cause of authentication issues when attempting to connect to MongoDB using ``SCRAM-SHA-256``. @@ -203,7 +201,7 @@ This results in the following output: .. _node-troubleshooting-connection-admin: Verify the User Is in the Authentication Database -------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To successfully authenticate a connection by using a username and password with ``SCRAM-SHA-256``, the username must be defined in the authentication database. @@ -224,7 +222,7 @@ instance hosted on the local machine with the same code. A deployment on the same machine doesn't require any authorization to connect. Error Sending Message -~~~~~~~~~~~~~~~~~~~~~ +--------------------- When the driver fails to send a command after you make a request, it may display the following error message: @@ -238,7 +236,7 @@ The following sections describe actions you can take to potentially resolve the issue. Check the User Permissions --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ Verify that you've accessed the MongoDB deployment with the correct user. The term "message" in the error can be a command sent by the driver. @@ -251,7 +249,7 @@ to a MongoDB deployment. For more information about how to configure RBAC in Mon see :manual:`Default MongoDB Port `. Configure Your Firewall ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ The firewall needs to have an open port for communicating with the MongoDB instance. For more information about configuring the firewall, see @@ -261,7 +259,7 @@ the Connection Error section. .. _node-troubleshooting-connection-number-connections: Check the Number of Connections -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each ``MongoClient`` instance supports a maximum number of concurrent open connections in its connection pool. You can configure the parameter ``maxPoolSize`` @@ -270,12 +268,12 @@ number of open connections equal to ``maxPoolSize``, the server waits until a connection becomes available. If this wait time exceeds the ``maxIdleTimeMS`` value, the driver responds with an error. -For more information about how connection pooling works, see -:ref:`How Does Connection Pooling Work in the Node Driver? ` -in the FAQ. +For more information about how connection pooling works, see the +:ref:`Connection Pool Overview ` +in the Connection Pools page. Too Many Open Connections -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- The driver creates the following error message when it attempts to open a connection, but it's reached the maximum number of connections: @@ -288,7 +286,7 @@ connection, but it's reached the maximum number of connections: The following section describes a method that may help resolve the issue. Check the Number of Connections -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To create more open connections, increase the value of ``maxPoolSize``. For more information about checking the number of connections, see @@ -296,7 +294,7 @@ information about checking the number of connections, see in the Error Sending Message section. Timeout Error -~~~~~~~~~~~~~ +------------- When the network is not able to deliver a request from the driver to the server quickly enough, it can time out. When this happens, you might receive an error message @@ -311,7 +309,7 @@ If you receive this error, try the following action to resolve the issue. Set connectTimeoutMS --------------------- +~~~~~~~~~~~~~~~~~~~~ The driver may hang when it's unable to establish a connection because it takes too long attempting to reach unreachable replica set nodes. You can limit the @@ -335,9 +333,73 @@ The following example sets ``connectTimeoutMS`` to 10000 milliseconds. }); Check the Number of Connections -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The number of connections to the server may exceed ``maxPoolSize``. For more information about checking the number of connections, see :ref:`Check the Number of Connections ` in the Error Sending Message section. + +Client Disconnect While Running Operation +----------------------------------------- + +Starting in {+mdb-server+} version 4.2, the server terminates +running operations such as aggregations and find operations if the +client disconnects. + +Other operations, such as write operations, continue to run on the +{+mdb-server+} even if the client disconnects. This behavior can cause data +inconsistencies if your application retries the operation after the +client disconnects. + +Unexpected Network Behavior +--------------------------- + +You might experience unexpected network behavior if the firewall between +your application and MongoDB is misconfigured. These firewalls can be +overly aggressive in their removal of connections, which can lead to +unexpected errors. + +Confirm that your firewall exhibits the following behavior: + +- The firewall sends a ``FIN`` packet when closing a connection, + informing the driver that the socket is closed. + +- The firewall allows keepalive messages. + +.. tip:: + + To learn more about keepalive messages, see the :ref:`keepAlive Connection Option + ` section in the Connection Options page. + +Connection String Errors for Replica Sets +----------------------------------------- + +The connection string passed to the driver must use exact hostnames for +the servers, as set in the :manual:`Replica Set Config `. +Given the following configuration settings for your replica set, in +order for the replica set discovery and :manual:`failover +` to work, the driver must have access +to ``server1``, ``server2``, and ``server3``. + +.. code-block:: JSON + + { + "_id": "testSet", + "version": 1, + "protocolVersion": 1, + "members": [ + { + "_id": 1, + "host": "server1:31000" + }, + { + "_id": 2, + "host": "server2:31001" + }, + { + "_id": 3, + "host": "server3:31002" + } + ] + } \ No newline at end of file diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index ab63a2245..f1b27a261 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -119,7 +119,57 @@ verify that the connection is successful: Call the ``MongoClient.connect()`` method explicitly if you want to verify that the connection is successful. -To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page `. +To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page +`. + +Prevent a Slow Operation From Delaying Other Operations +------------------------------------------------------- + +When you use the same ``MongoClient`` instance to run multiple MongoDB +operations concurrently, a slow operation can cause delays to other +operations. Slow operations keep a connection to MongoDB occupied, +which can cause other operations to wait until another connection +becomes available. + +If you suspect that slow MongoDB operations are causing delays, you +can check the performance of all in-progress operations by using the +following methods: + +- Enable the database profiler on your deployment. To learn more, see + :manual:`Database Profiler ` + in the Server manual. +- Run the ``db.currentOp()`` MongoDB Shell command. To learn more, see the + :manual:`db.currentOp() ` + documentation in the Server manual. +- Enable connection pool monitoring. To learn more, see + :ref:`node-connection-pool-monitoring`. + +After you determine which operations are causing delays, try to improve +the performance of these operations. Read the :website:`Best Practices +Guide for MongoDB Performance ` for possible solutions. + +If you implement performance best practices but still +experience delays, you can modify your connection settings to increase +the size of the connection pool. A connection pool is the group of +connections to the server that the driver maintains at any time. + +To specify the maximum size of a +connection pool, you can set the ``maxPoolSize`` option in the +:ref:`connection options ` for your +``MongoClient`` instance. The default value +of ``maxPoolSize`` is ``100``. If the number of in-use connections to a +server reaches ``maxPoolSize``, the next operation sent to the server +pauses until a connection to the driver becomes available. The following +code sets ``maxPoolSize`` to ``150`` when creating a new ``MongoClient``: + +.. code-block:: js + + const client = new MongoClient(uri, { maxPoolSize: 150 }); + +.. tip:: + + To learn more about connection pooling, see the :ref:`Connection Pool Overview + ` section in the Connection Pools page. API Documentation ----------------- diff --git a/source/faq.txt b/source/faq.txt deleted file mode 100644 index c472fc187..000000000 --- a/source/faq.txt +++ /dev/null @@ -1,369 +0,0 @@ -.. _node-faq: - -=== -FAQ -=== - -.. meta:: - :description: Find answers to frequently asked questions about the MongoDB Node.js Driver, including connection pooling, timeouts, and handling network behavior. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -This page contains frequently asked questions and their corresponding answers. - -.. tip:: - - If you can't find an answer to your problem on this page, - see the :ref:`node-issues-help` page for next steps and more - resources. - -Why Am I Getting Errors While Connecting to MongoDB? ----------------------------------------------------- - -If you have trouble connecting to a MongoDB deployment, see -the :ref:`Connection Troubleshooting Guide ` -for possible solutions. - -.. _node-faq-connection-pool: - -How Does Connection Pooling Work in the Node Driver? ----------------------------------------------------- - -Every ``MongoClient`` instance has a built-in connection pool for each server -in your MongoDB topology. Connection pools open sockets on demand to -support concurrent requests to MongoDB in your application. - -The maximum size of each connection pool is set by the ``maxPoolSize`` option, which -defaults to ``100``. If the number of in-use connections to a server reaches -the value of ``maxPoolSize``, the next request to that server will wait -until a connection becomes available. - -In addition to the sockets needed to support your application's requests, -each ``MongoClient`` instance opens two more sockets per server -in your MongoDB topology for monitoring the server's state. -For example, a client connected to a three-node replica set opens six -monitoring sockets. If the application uses the default setting for -``maxPoolSize`` and only queries the primary (default) node, then -there can be at most ``106`` total connections in the connection pool. If the -application uses a :ref:`read preference ` to query the -secondary nodes, those connection pools grow and there can be -``306`` total connections. - -To support high numbers of concurrent MongoDB requests -within one process, you can increase ``maxPoolSize``. - -Connection pools are rate-limited. The ``maxConnecting`` option -determines the number of connections that the pool can create in -parallel at any time. For example, if the value of ``maxConnecting`` is -``2``, the third request that attempts to concurrently check out a -connection succeeds only when one the following cases occurs: - -- The connection pool finishes creating a connection and there are fewer - than ``maxPoolSize`` connections in the pool. -- An existing connection is checked back into the pool. -- The driver's ability to reuse existing connections improves due to - rate-limits on connection creation. - -You can set the minimum number of concurrent connections to -each server with the ``minPoolSize`` option, which defaults to ``0``. -The driver initializes the connection pool with this number of sockets. If -sockets are closed, causing the total number -of sockets (both in use and idle) to drop below the minimum, more -sockets are opened until the minimum is reached. - -You can set the maximum number of milliseconds that a connection can -remain idle in the pool by setting the ``maxIdleTimeMS`` option. -Once a connection has been idle for ``maxIdleTimeMS``, the connection -pool removes and replaces it. This option defaults to ``0`` (no limit). - -The following default configuration for a ``MongoClient`` works for most -applications: - -.. code-block:: js - - const client = new MongoClient(""); - -``MongoClient`` supports multiple concurrent requests. For each process, -create a client and reuse it for all operations in a process. This -practice is more efficient than creating a client for each request. - -The driver does not limit the number of requests that -can wait for sockets to become available, and it is the application's -responsibility to limit the size of its pool to bound queuing -during a load spike. Requests wait for the amount of time specified in -the ``waitQueueTimeoutMS`` option, which defaults to ``0`` (no limit). - -A request that waits more than the length of time defined by -``waitQueueTimeoutMS`` for a socket raises a connection error. Use this -option if it is more important to bound the duration of operations -during a load spike than it is to complete every operation. - -When ``MongoClient.close()`` is called by any request, the driver -closes all idle sockets and closes all sockets that are in -use as they are returned to the pool. Calling ``MongoClient.close()`` -closes only inactive sockets and does not directly terminate -any ongoing operations. The driver closes any in-use sockets only when -the associated operations complete. However, the ``MongoClient.close()`` -method does close existing sessions and transactions, which might indirectly -affect the behavior of ongoing operations and open cursors. - -What Is the Difference Between "connectTimeoutMS", "socketTimeoutMS" and "maxTimeMS"? -------------------------------------------------------------------------------------- - -.. list-table:: - :widths: 22 78 - :header-rows: 1 - - * - Setting - - Description - * - **connectTimeoutMS** - - ``connectTimeoutMS`` is a :ref:`connection option - ` that sets the time, in milliseconds, - for an individual connection from your connection pool to - establish a TCP connection to the {+mdb-server+} before - timing out. To modify the allowed time for - `MongoClient.connect <{+api+}/classes/MongoClient.html#connect>`__ to establish a - connection to a {+mdb-server+}, use the ``serverSelectionTimeoutMS`` option instead. - - **Default:** 30000 - * - **socketTimeoutMS** - - ``socketTimeoutMS`` specifies the amount of time the driver waits - for an inactive socket before closing it. The default value is to - never time out the socket. This option applies only to sockets that - have already been connected. - * - **maxTimeMS** - - `maxTimeMS <{+api+}/classes/FindCursor.html#maxTimeMS>`__ - specifies the maximum amount of time that the server - waits for an operation to complete after it has reached the - server. If an operation runs over the specified time limit, it - returns a timeout error. You can pass ``maxTimeMS`` only to an - individual operation or to a cursor. - -To specify the optional settings for your ``MongoClient``, declare one or -more available settings in the ``options`` object of the constructor as -follows: - -.. code-block:: javascript - - const client = new MongoClient(uri, { - connectTimeoutMS: , - socketTimeoutMS: - }); - -To see all the available settings, see the -`MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ -API Documentation. - -To specify ``maxTimeMS``, chain the ``maxTimeMS()`` method with a -timeout specification to an operation that returns a ``Cursor``: - -.. code-block:: javascript - - const cursor = myColl.find({}).maxTimeMS(50); - -What Happens to Running Operations if the Client Disconnects? -------------------------------------------------------------- - -Starting in {+mdb-server+} version 4.2, the server terminates -running operations such as aggregations and find operations if the -client disconnects. - -Other operations, such as write operations, continue to run on the -{+mdb-server+} even if the client disconnects. This behavior can cause data -inconsistencies if your application retries the operation after the -client disconnects. - -How Can I Confirm That the Driver Closed Unusable Sockets? ----------------------------------------------------------- - -If you experience unexpected network behavior or if a MongoDB process -fails with an error, you may not receive confirmation that the -driver correctly closed the corresponding socket. - -To make sure that the driver correctly closes the socket in these cases, -set the ``socketTimeoutMS`` option. When a MongoDB process times out, the driver -will close the socket. We recommend that you select a value -for ``socketTimeoutMS`` that is two to three times longer than the -expected duration of the slowest operation that your application executes. - -How Can I Prevent Sockets From Timing Out Before They Become Active? --------------------------------------------------------------------- - -Having a large connection pool does not always reduce reconnection -requests. Consider the following example: - -An application has a connection pool size of 5 sockets and has the -``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur, -on average, every 3000 milliseconds, and reconnection requests are -frequent. Each socket times out after 5000 milliseconds, which means -that all sockets must do something during those 5000 milliseconds to -avoid closing. - -One message every 3000 milliseconds is not enough to keep the sockets -active, so several of the sockets will time out after 5000 milliseconds. -To avoid excessive socket timeouts, reduce the number of connections -that the driver can maintain in the connection pool by specifying the -``maxPoolSize`` option. - -To specify the optional ``maxPoolSize`` setting for your ``MongoClient``, declare -it in the ``options`` object of the constructor as follows: - -.. code-block:: javascript - - const client = new MongoClient(uri, { - maxPoolSize: , - }); - -What Does a Value of "0" Mean for "connectTimeoutMS" and "socketTimeoutMS"? ---------------------------------------------------------------------------- - -If you set the value of ``connectTimeoutMS`` or ``socketTimeoutMS`` to -``0``, your application will use the operating system's default socket -timeout value. - -How Can I Prevent Long-Running Operations From Slowing Down the Server? ------------------------------------------------------------------------ - -You can prevent long-running operations from slowing down the server by -specifying a timeout value. You can chain the ``maxTimeMS()`` method to -an operation that returns a ``Cursor`` to set a timeout on a specific action. - -The following example shows how you can chain the ``maxTimeMS()`` method -to an operation that returns a ``Cursor``: - -.. literalinclude:: /code-snippets/faq/maxTimeMS-example.js - :language: javascript - -.. _node-faq-keepalive: - -What Does the keepAlive Option Do? ----------------------------------- - -The ``keepAlive`` connection option specifies whether to enable -:wikipedia:`Transmission Control Protocol (TCP) keepalives -` on a TCP socket. If you enable keepalives, -the driver checks whether the connection is active by sending periodic pings -to your MongoDB deployment. This functionality only works if your -operating system supports the ``SO_KEEPALIVE`` socket option. - -The ``keepAliveInitialDelay`` option specifies the number of -milliseconds that the driver waits before initiating a keepalive. - -The 5.3 driver version release deprecated these options. Starting in -version 6.0 of the driver, the ``keepAlive`` option is permanently set -to ``true``, and the ``keepAliveInitialDelay`` is set to 300000 -milliseconds (300 seconds). - -.. warning:: - - If your firewall ignores or drops the keepalive messages, you might - not be able to identify dropped connections. - -What Can I Do If I'm Experiencing Unexpected Network Behavior? --------------------------------------------------------------- - -You might experience unexpected network behavior if the firewall between -your application and MongoDB is misconfigured. These firewalls can be -overly aggressive in their removal of connections, which can lead to -unexpected errors. - -Confirm that your firewall exhibits the following behavior: - -- The firewall sends a ``FIN`` packet when closing a connection, - informing the driver that the socket is closed. - -- The firewall allows keepalive messages. - -.. tip:: - - To learn more about keepalive messages, see the :ref:`What Does the - keepAlive Option Do? ` FAQ entry. - -How Can I Prevent a Slow Operation From Delaying Other Operations? ------------------------------------------------------------------- - -When you use the same ``MongoClient`` instance to run multiple MongoDB -operations concurrently, a slow operation can cause delays to other -operations. Slow operations keep a connection to MongoDB occupied, -which can cause other operations to wait until an additional connection -becomes available. - -If you suspect that slow MongoDB operations are causing delays, you -can check the performance of all in-progress operations by using the -following methods: - -- Enable the database profiler on your deployment. To learn more, see - :manual:`Database Profiler ` - in the Server manual. -- Run the ``db.currentOp()`` MongoDB Shell command. To learn more, see the - :manual:`db.currentOp() ` - documentation in the Server manual. -- Enable connection pool monitoring. To learn more, see - :ref:`node-connection-pool-monitoring`. - -After you determine which operations are causing delays, try to improve -the performance of these operations. Read the :website:`Best Practices -Guide for MongoDB Performance ` for possible solutions. - -If you implement performance best practices but still -experience delays, you can modify your connection settings to increase -the size of the connection pool. A connection pool is the group of -connections to the server that the driver maintains at any time. - -To specify the maximum size of a -connection pool, you can set the ``maxPoolSize`` option in the -:ref:`connection options ` for your -``MongoClient`` instance. The default value -of ``maxPoolSize`` is ``100``. If the number of in-use connections to a -server reaches ``maxPoolSize``, the next operation sent to the server -pauses until a connection to the driver becomes available. The following -code sets ``maxPoolSize`` to ``150`` when creating a new ``MongoClient``: - -.. code-block:: js - - const client = new MongoClient(uri, { maxPoolSize: 150 }); - -.. tip:: - - To learn more about connection pooling, see the :ref:`How Does Connection - Pooling Work in the Node Driver? ` FAQ entry. - -How Can I Ensure my Connection String Is Valid for a Replica Set? ------------------------------------------------------------------ - -The connection string passed to the driver must use exact hostnames for -the servers as set in the :manual:`Replica Set Config `. -Given the following configuration settings for your Replica Set, in -order for the Replica Set discovery and :manual:`failover -` to work, the driver must have access -to ``server1``, ``server2``, and ``server3``. - -.. code-block:: JSON - - { - "_id": "testSet", - "version": 1, - "protocolVersion": 1, - "members": [ - { - "_id": 1, - "host": "server1:31000" - }, - { - "_id": 2, - "host": "server2:31001" - }, - { - "_id": 3, - "host": "server3:31002" - } - ] - } - -If you are unable to find the answer to your question here, try our forums and -support channels listed in the :doc:`Issues and Help ` -section. From f497617c836eed56bb583b183db3b2e34bef9c69 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Mon, 31 Mar 2025 18:09:53 -0400 Subject: [PATCH 12/26] DOCSP-48592 Security Landing Page (#1064) * DOCSP-48592 Security Landing Page * remove sample app * change title --- source/security.txt | 15 ++++++++++----- source/security/authentication/scram.txt | 8 ++++++-- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/source/security.txt b/source/security.txt index ec4c2872c..ccd9ffa2b 100644 --- a/source/security.txt +++ b/source/security.txt @@ -1,8 +1,8 @@ .. _node-security: -========= -Security -========= +================ +Secure Your Data +================ .. contents:: On this page :local: @@ -30,5 +30,10 @@ Security Overview -------- -MongoDB supports multiple mechanisms that you can use to authenticate your application. -This page contains code examples that show each of these mechanisms. \ No newline at end of file +Learn how to set up security and authentication for your application +in the following sections: + +- :ref:`Authentication ` +- :ref:`In-Use Encryption ` +- :ref:`TLS Security Protocol ` +- :ref:`SOCKS Proxy ` diff --git a/source/security/authentication/scram.txt b/source/security/authentication/scram.txt index d11fed75b..979374e6d 100644 --- a/source/security/authentication/scram.txt +++ b/source/security/authentication/scram.txt @@ -86,6 +86,8 @@ To learn more about the SCRAM version that MongoDB supports, see the :manual:`SCRAM ` section of the {+mdb-server+} manual. +.. _node-scram-sha-256: + SCRAM-SHA-256 ------------- @@ -109,8 +111,10 @@ following sample code. .. literalinclude:: /code-snippets/authentication/sha256.js :language: javascript -``SCRAM-SHA-1`` ---------------- +.. _node-scram-sha-1: + +SCRAM-SHA-1 +----------- .. note:: ``SCRAM-SHA-1`` is the default authentication method for MongoDB versions From 6f969b57d3b7dca5ab1f1b55547c2a7531c8f43a Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Wed, 2 Apr 2025 15:07:16 -0400 Subject: [PATCH 13/26] DOCSP-48608 Edit AVS and AS section on Indexes page (#1065) * DOCSP-48606 Atlas Vector Search * edit existing sections * Edits * edit code comments * add link to as query guide * title change * more edits --- source/atlas-search.txt | 6 +- source/atlas-vector-search.txt | 5 +- source/code-snippets/indexes/searchIndexes.js | 10 +-- source/indexes.txt | 83 +++++++++---------- 4 files changed, 50 insertions(+), 54 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index b0241ac2b..bef911d49 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -1,8 +1,8 @@ .. _node-atlas-search: -============ -Atlas Search -============ +========================= +Run an Atlas Search Query +========================= .. facet:: :name: genre diff --git a/source/atlas-vector-search.txt b/source/atlas-vector-search.txt index 1c5bd2c44..1d3ede7d9 100644 --- a/source/atlas-vector-search.txt +++ b/source/atlas-vector-search.txt @@ -45,9 +45,8 @@ Perform a Vector Search To use this feature, you must create a vector search index and index your vector embeddings. To learn about how to programmatically create a -vector search index, see the :atlas:`Create an Atlas Vector Search Index -` section in the -Atlas documentation. To learn more about vector embeddings, see +vector search index, see the :ref:`` section in the +Indexes guide. To learn more about vector embeddings, see :atlas:`How to Create Vector Embeddings ` in the Atlas documentation. diff --git a/source/code-snippets/indexes/searchIndexes.js b/source/code-snippets/indexes/searchIndexes.js index d0ac72398..8eeff5770 100644 --- a/source/code-snippets/indexes/searchIndexes.js +++ b/source/code-snippets/indexes/searchIndexes.js @@ -17,7 +17,7 @@ async function run() { const collection = database.collection(""); // start createSearchIndex example - // Create a search index + // Creates an Atlas Search index const index1 = { name: "search1", definition: { @@ -30,7 +30,7 @@ async function run() { // end createSearchIndex example // start vectorSearchIdx example - // Create a Vector Search index + // Creates an Atlas Vector Search index const vectorSearchIdx = { name: "vsidx1", type: "vectorSearch", @@ -48,7 +48,7 @@ async function run() { // end vectorSearchIdx example // start listSearchIndexes example - // List search indexes + // Lists search indexes const result = await collection.listSearchIndexes().toArray(); console.log("Existing search indexes:\n"); for (const doc in result) { @@ -57,7 +57,7 @@ async function run() { // end listSearchIndexes example // start updateSearchIndex example - // Update a search index + // Updates a search index const index2 = { "mappings": { "dynamic": true, @@ -72,7 +72,7 @@ async function run() { // end updateSearchIndex example // start dropSearchIndex example - // Dropping (deleting) a search index + // Drops (deletes) a search index await collection.dropSearchIndex("search1"); // end dropSearchIndex example } finally { diff --git a/source/indexes.txt b/source/indexes.txt index fe9762ee1..4897e5d01 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -1,9 +1,9 @@ .. _node-fundamentals-indexes: .. _node-indexes: -======= -Indexes -======= +====================== +Indexes on Collections +====================== .. facet:: :name: genre @@ -340,27 +340,27 @@ To learn more, see :manual:`Unique Indexes `. .. _node-indexes-search: -Search Indexes --------------- +Atlas Search and Atlas Vector Search Indexes +-------------------------------------------- -Atlas Search is a feature that allows you to perform full-text -searches. To learn more, see the :ref:`Atlas Search ` -documentation. +You can programmatically manage your Atlas Search and Atlas Vector +Search indexes by using the {+driver-short+}. -Before you can perform a search on an Atlas collection, you must first -create an Atlas Search index on the collection. An Atlas Search -index is a data structure that categorizes data in a searchable format. +The Atlas Search feature enables you to perform full-text searches on +collections hosted on MongoDB Atlas. To learn more about Atlas +Search, see the :atlas:`Atlas Search +` documentation. -You can use the following methods to manage your Search indexes: +Atlas Vector Search enables you to perform semantic searches on vector +embeddings stored in Atlas. To learn more about Atlas +Vector Search, see the :atlas:`Atlas Vector Search +` documentation. -- ``createSearchIndex()`` -- ``createSearchIndexes()`` -- ``listSearchIndexes()`` -- ``updateSearchIndex()`` -- ``dropSearchIndex()`` +To learn more about how to run an Atlas Search or Atlas Vector Search query, see the +:ref:`node-atlas-search` or :ref:`node-atlas-vector-search` guide. -The following sections provide code samples that use each of the preceding -methods to manage Search indexes. +The following sections contain code examples that demonstrate how to manage Atlas +Search and Atlas Vector Search indexes. Create a Search Index ~~~~~~~~~~~~~~~~~~~~~ @@ -368,10 +368,10 @@ Create a Search Index You can use the `createSearchIndex() <{+api+}/classes/Collection.html#createSearchIndex>`__ and `createSearchIndexes() <{+api+}/classes/Collection.html#createSearchIndexes>`__ -methods to create new Search indexes. +methods to create new Atlas Search and Atlas Vector Search indexes. The following code shows how to -use the ``createSearchIndex()`` method to create an index called +use the ``createSearchIndex()`` method to create an Atlas Search index called ``search1``: .. literalinclude:: /code-snippets/indexes/searchIndexes.js @@ -380,15 +380,12 @@ use the ``createSearchIndex()`` method to create an index called :start-after: start createSearchIndex example :end-before: end createSearchIndex example -When connecting to {+mdb-server+} v6.0.11 and later v6 versions, or -v7.0.2 and later v7 versions, you can use the driver to create an Atlas -Vector Search index on a collection. Learn more about this feature in -the :atlas:`Atlas Vector Search documentation -`. +When connecting to {+mdb-server+} v6.0.11 and later, you can use the driver to +create an Atlas Vector Search index by specifying ``vectorSearch`` in the ``type`` +field of the index definition. The following code shows how to use the ``createSearchIndex()`` method -to create a search index in which the ``type`` field is -``vectorSearch``: +to create an Atlas Vector Search index: .. literalinclude:: /code-snippets/indexes/searchIndexes.js :language: javascript @@ -401,13 +398,14 @@ List Search Indexes You can use the `listSearchIndexes() <{+api+}/classes/Collection.html#listSearchIndexes>`__ -method to return a cursor that contains the Search indexes of a given -collection. The ``listSearchIndexes()`` method takes an optional string -parameter, ``name``, to return only the indexes with matching names. It -also takes an optional `aggregateOptions <{+api+}/interfaces/AggregateOptions.html>`__ parameter. +method to return a cursor that contains the Atlas Search and Atlas Vector Search +indexes of a given collection. The ``listSearchIndexes()`` method takes an +optional string parameter, ``name``, to return only the indexes with matching +names. It also takes an optional +`aggregateOptions <{+api+}/interfaces/AggregateOptions.html>`__ parameter. The following code uses the ``listSearchIndexes()`` method to list the -Search indexes in a collection: +Atlas Search and Atlas Vector Search indexes in a collection: .. literalinclude:: /code-snippets/indexes/searchIndexes.js :language: javascript @@ -419,12 +417,12 @@ Update a Search Index ~~~~~~~~~~~~~~~~~~~~~ You can use the `updateSearchIndex() -<{+api+}/classes/Collection.html#updateSearchIndex>`__ method to update a Search -index. +<{+api+}/classes/Collection.html#updateSearchIndex>`__ method to update an +Atlas Search or Atlas Vector Search index by providing a new index definition. -The following code shows how to -use the ``updateSearchIndex()`` method to update an index called -``search1`` to specify a string type for the ``description`` field: +The following code shows how to use the ``updateSearchIndex()`` method to +update an Atlas Search index called ``search1`` to change the type of the +``description`` field to a string: .. literalinclude:: /code-snippets/indexes/searchIndexes.js :language: javascript @@ -436,12 +434,11 @@ Drop a Search Index ~~~~~~~~~~~~~~~~~~~ You can use the `dropSearchIndex() -<{+api+}/classes/Collection.html#dropSearchIndex>`__ method to remove a Search -index. +<{+api+}/classes/Collection.html#dropSearchIndex>`__ method to remove an Atlas +Search or Atlas Vector Search index. -The following code shows how to -use the ``dropSearchIndex()`` method to remove an index called -``search1``: +The following code shows how to use the ``dropSearchIndex()`` method to remove +an index called ``search1``: .. literalinclude:: /code-snippets/indexes/searchIndexes.js :language: javascript From 1a4aada11affb0f5a404ecceaf25a9f7e6ee8c03 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Mon, 7 Apr 2025 16:16:30 -0400 Subject: [PATCH 14/26] DOCSP-48382: Configure CRUD operations (#1049) * DOCSP-48382: Configure CRUD operations * edits, move info * edits * AS feedback * tech feedback --- config/redirects | 2 +- source/crud.txt | 1 - source/crud/configure.txt | 505 ++++++++++++---------- source/crud/read-write-pref.txt | 245 ----------- source/includes/fundamentals/configure.js | 109 +++++ 5 files changed, 381 insertions(+), 481 deletions(-) delete mode 100644 source/crud/read-write-pref.txt create mode 100644 source/includes/fundamentals/configure.js diff --git a/config/redirects b/config/redirects index 38b67ad50..510ef00ce 100644 --- a/config/redirects +++ b/config/redirects @@ -44,7 +44,7 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/query/ [*-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query/query-document/ [*-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ -[*-master]: ${prefix}/${version}/fundamentals/crud/read-write-pref/ -> ${base}/${version}/crud/read-write-pref/ +[*-master]: ${prefix}/${version}/fundamentals/crud/read-write-pref/ -> ${base}/${version}/crud/configure/ [*-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ [*-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query/retrieve/ diff --git a/source/crud.txt b/source/crud.txt index abf96d299..6a2ea2af3 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -31,7 +31,6 @@ CRUD Operations Compound Operations Transactions Configure CRUD Operations - Operations on Replica Sets Store Large Files CRUD (Create, Read, Update, Delete) operations enable you to work with diff --git a/source/crud/configure.txt b/source/crud/configure.txt index 521f75e68..92748c8f9 100644 --- a/source/crud/configure.txt +++ b/source/crud/configure.txt @@ -20,81 +20,226 @@ Configure CRUD Operations Overview -------- -In this guide, you can learn how to configure read and write operations in {+driver-short+}. +In this guide, you can learn how to use the {+driver-short+} to configure read +and write operations. -.. _node-fundamentals-collations: -.. _node-collations: +Read and Write Settings +----------------------- -Collations ----------- +You can control how the driver routes read operations by setting a **read preference**. +You can also control how the driver handles data consistency and durability by setting +a **read concern** or **write concern**. Read concerns specify the level of durability +required for the data when performing read operations, and write concerns specify +how the driver waits for acknowledgment of write operations on a replica set. -*Collations are available in MongoDB 3.4 and later.* +You can set write concern, read concern, and read preference options at the following +levels: -You can use **collations**, a set of sorting rules, to run operations using -string ordering for specific languages and locales (a community or region that -shares common language idioms). +- Client, which sets the *default for all operation executions* unless overridden +- Transaction +- Database +- Collection -MongoDB sorts strings using *binary collation* by default. This collation -method uses the `ASCII standard `_ -character values to compare and order strings. Languages and locales -have specific character ordering conventions that differ from the ASCII -standard. +The preceding list also indicates the increasing order of precedence of the option settings. For +example, if you set a read concern level for a transaction, it will override a read +concern level set for the client. -For example, in Canadian French, the right-most accented character determines -the ordering for strings when the other characters are the same. Consider the -following French words: **cote**, **coté**, **côte**, and **côté**. +.. tip:: -MongoDB sorts them in the following order using the default binary collation: + To learn more about the read and write settings, see the following guides in the + {+mdb-server+} manual: -.. code-block:: none + - :manual:`Read Preference ` + - :manual:`Read Concern ` + - :manual:`Write Concern ` - cote - coté - côte - côté +This section shows how to configure your read and write settings at each level. -MongoDB sorts them in the following order using the Canadian French collation: +Client Configuration +~~~~~~~~~~~~~~~~~~~~ -.. code-block:: none +This example shows how to set the read preference, read concern, and +write concern of a ``MongoClient`` instance by passing a ``MongoClientOptions`` +object to the constructor. The code configures the following settings: + +- ``SECONDARY`` read preference: Read operations retrieve data from + secondary replica set members +- ``local`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``2`` write concern: The primary and one secondary replica set member + must acknowledge the write operation + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-client-settings + :end-before: end-client-settings + +Alternatively, you can specify the read and write settings in the connection +URI, which is passed as a parameter to the ``MongoClient`` constructor: + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-client-settings-uri + :end-before: end-client-settings-uri + +.. _node-read-write-transaction: + +Transaction Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example shows how to set the read preference, read concern, and +write concern of a transaction by passing a ``TransactionOptions`` object +to the ``startTransaction()`` method. The code configures the following settings: + +- ``PRIMARY`` read preference: Read operations retrieve data from + the primary replica set member +- ``majority`` read concern: Read operations return the instance's most recent data + that has been written to a majority of replica set members +- ``1`` write concern: The primary replica set member must acknowledge the + write operation + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-transaction-settings + :end-before: end-transaction-settings + +.. _node-read-write-database: + +Database Configuration +~~~~~~~~~~~~~~~~~~~~~~ + +This example shows how to set the read preference, read concern, and +write concern of a database called ``test_database`` by passing a ``DbOptions`` +object to the ``db()`` method. The code configures the following settings: + +- ``PRIMARY_PREFERRED`` read preference: Read operations retrieve data from + the primary replica set member, or secondary members if the primary is unavailable +- ``available`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``majority`` write concern: The majority of all replica set members + must acknowledge the write operation + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-database-settings + :end-before: end-database-settings + +.. _node-read-write-collection: + +Collection Configuration +~~~~~~~~~~~~~~~~~~~~~~~~ - cote - côte - coté - côté +This example shows how to set the read preference, read concern, and +write concern of a collection called ``test_collection`` by passing a ``CollectionOptions`` +object to the ``collection()`` method. The code configures the following settings: -Using Collations -~~~~~~~~~~~~~~~~~~ +- ``SECONDARY_PREFERRED`` read preference: Read operations retrieve data from + secondary replica set members, or the primary members if no secondaries are available +- ``available`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``0`` write concern: Does not request acknowledgment of the write operation + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-collection-settings + :end-before: end-collection-settings + +Tag Sets +-------- + +In {+mdb-server+}, you can apply key-value :manual:`tags +` to replica-set +members according to any criteria you choose. You can then use +those tags to target one or more members for a read operation. + +By default, the {+driver-short+} ignores tags when choosing a member +to read from. To instruct the {+driver-short+} to prefer certain tags, +pass them as a parameter to your read preference class +constructor. -You can specify a collation when you create a new collection or new index. You -can also specify a collation for :doc:`CRUD operations ` -and aggregations. +This code example sets the ``readPreference`` option to a tag set that +instructs ``test_database`` to prefer reads from secondary replica set +members in the following order: -When you create a new collection with a collation, you define the default -collation for any of the :manual:`operations that support collation -` called on that -collection. You can override the collation for an operation by specifying a -different one. +1. Members from the New York data center (``{ dc: 'ny' }``) +#. Members from the San Francisco data center (``{ dc: 'sf' }``) +#. Any secondary members (``{}``) + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-tag-set + :end-before: end-tag-set + +Local Threshold +--------------- + +If multiple replica-set members match the read preference and tag sets you specify, +the {+driver-short+} reads from the nearest replica set members, chosen according to +their ping time. + +By default, the driver uses only those members whose ping times are within 15 milliseconds +of the nearest member for queries. To distribute reads between members with +higher latencies, pass the ``localThresholdMS`` option to the ``MongoClient()`` constructor. + +The following example specifies a local threshold of 35 milliseconds: + +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-local-threshold + :end-before: end-local-threshold + +In the preceding example, the {+driver-short+} distributes reads between matching members +within 35 milliseconds of the closest member's ping time. .. note:: + + The {+driver-short+} ignores the value of ``localThresholdMS`` when communicating with a + replica set through a ``mongos`` instance. In this case, use the + :manual:`localThreshold ` + command-line option. - Currently, you cannot create a collation on an existing collection. To use - collations with an existing collection, create an index with the collation - and specify the same collation in your operations on it. +.. _node-fundamentals-collations: +.. _node-collations: -When you create an index with a collation, you specify the sort order for -operations that use that index. To use the collation in the index, you -must provide a matching collation in the operation, and the operation must -use the index. While most index types support collation, the following -types support only binary comparison: +Collation +--------- -- :manual:`text ` -- :manual:`2d ` -- :manual:`geoHaystack ` +You can specify a **collation** to modify the behavior of read +and write operations. A collation is a set of language-specific rules for string +comparison, such as for letter case and accent marks. -Collation Parameters -~~~~~~~~~~~~~~~~~~~~ +MongoDB sorts strings using *binary collation* by default. This default +collation uses the `ASCII standard `_ +character values to compare and order strings. Languages and locales +have specific character ordering conventions that differ from the ASCII +standard, and you can choose to apply a different set of collation rules +to your operation. + +You can specify a collation at the following levels: -The collation object contains the following parameters: +- Collection: Sets the default collation for operations on the collection. + You cannot define a collation for an existing collection. + +- Index: Sets the collation for operations that use the index. + +- Operation: Sets the operation's collation and overrides any inherited collations. + +.. _node-configure-collation-fields: + +Collation Fields +~~~~~~~~~~~~~~~~ + +The collation object contains the following fields: .. code-block:: javascript @@ -109,213 +254,105 @@ The collation object contains the following parameters: backwards: } -You must specify the ``locale`` field in the collation; all other fields -are optional. For a complete list of supported locales and the default values +When setting the ``collation`` option, you must specify the ``locale`` field. +All other fields are optional. For a complete list of supported locales and the default values for the ``locale`` fields, see :manual:`Supported Languages and Locales -`. -For descriptions of each field, see the :manual:`Collation Document MongoDB -manual entry `. - -Set a Default Collation on a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the following example, we create a new collection called ``souvenirs`` and -assign a default collation with the ``"fr_CA"`` locale. The collation applies -to all :manual:`operations that support collation -` performed on that -collection. - -.. literalinclude:: /code-snippets/collation/collection-collation.js - :language: javascript - :start-after: start collection collation - :end-before: end collection collation - -Any of the operations that support collations automatically apply the collation -defined on the collection. The query below searches the ``souvenirs`` -collection and applies the ``"fr_CA"`` locale collation: - -.. literalinclude:: /code-snippets/collation/collection-auto-collation.js - :language: javascript - :start-after: start auto collation - :end-before: end auto collation - -You can specify a different collation as a parameter in an operation that -supports collations. The following query specifies the ``"is"`` Iceland locale -and ``caseFirst`` optional parameter with the value ``"upper"``: - -.. literalinclude:: /code-snippets/collation/collection-specify-collation.js - :language: javascript - :start-after: start specified collation - :end-before: end specified collation - -Assign a Collation to an Index -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the following example, we create a new index on the ``title`` field of -a collection with a collation set to the ``"en_US"`` locale. - -.. literalinclude:: /code-snippets/collation/index-collation.js - :language: javascript - :start-after: start create index collation - :end-before: end create index collation - -The following query uses the index we created: - -.. literalinclude:: /code-snippets/collation/query-index-collation.js - :language: javascript - :start-after: start query index collation - :end-before: end query index collation - -The following queries **do not** use the index that we created. The first -query does not include a collation and the second contains a different -strength value than the collation on the index. - -.. literalinclude:: /code-snippets/collation/query-not-indexed-collation.js - :language: javascript - :start-after: start not indexed collation - :end-before: end not indexed collation - -.. literalinclude:: /code-snippets/collation/query-index-no-collation.js - :language: javascript - :start-after: start index no collation - :end-before: end index no collation - -Collation Query Examples -~~~~~~~~~~~~~~~~~~~~~~~~ - -Operations that read, update, and delete documents from a collection can use -collations. This section includes examples of a selection of these. See the -MongoDB manual for a full list of :manual:`operations that support collation -`. +` +in the {+mdb-server+} manual. -find() and sort() Example -````````````````````````` - -The following example calls both ``find()`` and ``sort()`` on a collection -that uses the default binary collation. We use the German collation by -setting the value of the ``locale`` parameter to ``"de"``. - -.. literalinclude:: /code-snippets/collation/find-sort-collation.js - :language: javascript - :start-after: start find sort collation - :end-before: end find sort collation - -findOneAndUpdate() Example -`````````````````````````` - -The following example calls the ``findOneAndUpdate()`` operation on a -collection that uses the default binary collation. The collection contains the -following documents: - -.. code-block:: none +.. _node-configure-collation-exs: - { "_id" : 1, "first_name" : "Hans" } - { "_id" : 2, "first_name" : "Gunter" } - { "_id" : 3, "first_name" : "Günter" } - { "_id" : 4, "first_name" : "Jürgen" } +Collation Examples +~~~~~~~~~~~~~~~~~~ -Consider the following ``findOneAndUpdate()`` operation on this collection -which **does not** specify a collation: +To specify a collation, create a ``collation`` object and set its +``locale`` field to the language collation you want to use. Then, +pass this object as an options parameter to the method corresponding +to the target collation level. -.. literalinclude:: /code-snippets/collation/findOneAndUpdate-default-order-collation.js - :language: javascript - :start-after: start findOneAndUpdate default order collation - :end-before: end findOneAndUpdate default order collation +This section includes examples that set collations at the collection, +index, and operation levels. -Since "Gunter" is the first sorted result when using a binary collation, none -of the documents come lexically before and match the ``$lt`` comparison -operator in the query document. As a result, the operation does not update any -documents. +.. _node-configure-collation-coll-index: -Consider the same operation with a collation specified with the locale set to -``de@collation=phonebook``. This locale specifies the ``collation=phonebook`` -option which contains rules for prioritizing proper nouns, identified by -capitalization of the first letter. The ``de@collation=phonebook`` locale and -option sorts characters with umlauts before the same characters without -umlauts. +Set Collection and Index Collations +``````````````````````````````````` -.. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js - :language: javascript - :start-after: start findOneAndUpdate collation - :end-before: end findOneAndUpdate collation +The following example creates a new collection named ``names`` +and sets its default collation to the ``"fr_CA"`` locale: -Since "Günter" lexically comes before "Gunter" using the -``de@collation=phonebook`` collation specified in ``findOneAndUpdate()``, -the operation returns the following updated document: +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-collection-collation + :end-before: end-collection-collation -.. code-block:: none +You can create an index on the ``names`` collection that specifies a different +collation, as shown in the following example: - { lastErrorObject: { updatedExisting: true, n: 1 }, - value: { _id: 3, first_name: 'Günter' }, - ok: 1 } +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-index-collation + :end-before: end-index-collation -findOneAndDelete() Example +Set an Operation Collation `````````````````````````` -The following example calls the ``findOneAndDelete()`` operation on a -collection that uses the default binary collation and contains the following -documents: - -.. code-block:: none - - { "_id" : 1, "a" : "16" } - { "_id" : 2, "a" : "84" } - { "_id" : 3, "a" : "179" } +You can run an operation on the ``names`` collection, created in +the :ref:`preceding section `, that overrides +the default collation. -In this example, we set the ``numericOrdering`` collation parameter to ``true`` -to sort numeric strings based on their numerical order instead of their -lexical order. - -.. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js - :language: javascript - :start-after: start findOneAndDelete collation - :end-before: end findOneAndDelete collation - -After you run the operation above, the collection contains the following -documents: +The ``names`` collection contains the following documents: .. code-block:: none - { "_id" : 1, "a" : "16" } - { "_id" : 2, "a" : "84" } + { "_id" : 1, "first_name" : "Hans", "last_name" : "Muller" } + { "_id" : 2, "first_name" : "Gunter", "last_name" : "Braun" } + { "_id" : 3, "first_name" : "Günter", "last_name" : "Krause" } + { "_id" : 4, "first_name" : "Jürgen", "last_name" : "Weber" } -If you perform the same operation without collation on the original -collection of three documents, it matches documents based on the lexical value -of the strings (``"16"``, ``"84"``, and ``"179"``), and deletes the first -document it finds that matches the query criteria. +This example calls the ``findOneAndUpdate()`` method to update +the first matching document that has a ``first_name`` value of ``"Gunter"``. +The code applies a collation with the ``"de"`` locale and the ``"phonebook"`` +locale variant: -.. literalinclude:: /code-snippets/collation/findOneAndDelete-no-collation.js - :language: javascript - :start-after: start findOneAndDelete no collation - :end-before: end findOneAndDelete no collation +.. literalinclude:: /includes/fundamentals/configure.js + :language: javascript + :dedent: + :start-after: start-operation-collation + :end-before: end-operation-collation -Since all the documents contain lexical values in the ``a`` field that -match the criteria (greater than the lexical value of ``"100"``), the operation -removes the first result. After you run the operation above, the collection -contains the following documents: +In the preceding example, the ``phonebook`` locale variant instructs +the driver to sort characters with umlauts before the same characters without +umlauts. As a result, the operation matches the document that has +a ``first_name`` value of ``"Günter"``, with an umlaut, and returns +the following update information: .. code-block:: none + :copyable: false - { "_id" : 2, "a" : "84" } - { "_id" : 3, "a" : "179" } - -Aggregation Example -``````````````````` + { lastErrorObject: { updatedExisting: true, n: 1 }, + value: { _id: 3, first_name: 'Günter', last_name: 'Krause' }, + ok: 1 } -To use collation with the `aggregate <{+api+}/classes/Collection.html#aggregate>`__ -operation, pass the collation document in the options field, after the -array of pipeline stages. +.. tip:: -The following example shows an aggregation pipeline on a collection that uses -the default binary collation. The aggregation groups the ``first_name`` field, -counts the total number of results in each group, and sorts the results by -the German phonebook (``"de@collation=phonebook"`` locale) order. + To learn more about locale variants, see :manual:`Local Variants ` + in the {+mdb-server+} manual. -.. note:: +API Documentation +----------------- - You can specify only one collation on an aggregation. +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: -.. literalinclude:: /code-snippets/collation/aggregation-collation.js - :language: javascript - :start-after: start aggregation collation - :end-before: end aggregation collation +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +- `ClientSessionOptions <{+api+}/interfaces/ClientSessionOptions.html>`__ +- `TransactionOptions <{+api+}/interfaces/TransactionOptions.html>`__ +- `DbOptions <{+api+}/interfaces/DbOptions.html>`__ +- `CollectionOptions <{+api+}/interfaces/CollectionOptions.html>`__ +- `collation <{+api+}/interfaces/CreateCollectionOptions.html#collation>`__ \ No newline at end of file diff --git a/source/crud/read-write-pref.txt b/source/crud/read-write-pref.txt deleted file mode 100644 index 6107e624c..000000000 --- a/source/crud/read-write-pref.txt +++ /dev/null @@ -1,245 +0,0 @@ -.. _node-crud-write-read-pref: - -=============================================== -Specify How CRUD Operations Run on Replica Sets -=============================================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: node.js, customize, preferences, replica set, consistency - :description: Learn to use the MongoDB Node.js Driver to configure write concern, read concern, and read preference for CRUD operations on replica sets to customize data consistency and availability. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn how to use the **write concern**, **read concern**, and -**read preference** configurations to modify the way that MongoDB runs -create, read, update, and delete (CRUD) operations on replica sets. - -You can set write concern, read concern, and read preference options at the following -levels: - -- Client, which sets the *default for all operation executions* unless overridden -- Session -- Transaction -- Database -- Collection - -This list also indicates the increasing order of precedence of the option settings. For -example, if you set a read concern level for a transaction, it will override a read -concern level set for the client. - -These options allow you to customize the causal consistency and availability of the data -in your replica sets. - -Write Concern -------------- - -The write concern specifies the level of acknowledgement requested from MongoDB for write -operations, such as an insert or update, before the operation successfully returns. -Operations that do not specify an explicit write concern inherit the global default write -concern settings. - -For more information, see :manual:`Write Concern ` in the -Server manual. For detailed API documentation, see the `WriteConcern API documentation -<{+api+}/classes/WriteConcern.html>`__. - -The following table describes the ``WriteConcern`` parameters: - -.. list-table:: - :header-rows: 1 - :widths: 25 25 50 - - * - Parameter - - Type - - Description - - * - ``w`` *(optional)* - - `W <{+api+}/types/W.html>`__ - - Requests acknowledgment that the write operation has propagated to a specified - number of ``mongod`` instances or to ``mongod`` instances that are labelled specified tags - - * - ``wtimeoutMS`` *(optional)* - - number - - Specifies a time limit to prevent write operations from blocking indefinitely - - * - ``journal`` *(optional)* - - boolean - - Requests acknowledgment that the write operation has been written to the on-disk journal - -Example: Set the Write Concern for a Single Write Operation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This code uses custom ``WriteConcern`` settings while creating new a document: - -.. code-block:: js - - myDB.myCollection.insertOne( - { name: "anotherDocumentName" }, - { writeConcern: - { w: 2, wtimeoutMS: 5000 } - } - ); - -Example: Retrieve and Apply an Existing Write Concern -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This code uses the ``fromOptions()`` method to construct a ``WriteConcern`` from the -options of an existing database reference, ``myDB``. Note that ``myDB`` could be replaced -with a reference to any entity that accepts a write concern option. Then the new write -concern is applied to a document, ``myDoc``. - -.. code-block:: js - - const newWriteConcern = WriteConcern.fromOptions(myDB); - const myDoc = { name: "New Document" }; - WriteConcern.apply(myDoc,newWriteConcern); - -Read Concern ------------- - -The read concern specifies the following behaviors: - -- Level of :manual:`causal consistency ` across replica sets - -- `Isolation guarantees - `__ maintained during a query - -You can specify the read concern setting by using the ``level`` parameter. The default -read concern level is ``local``. This means that the client returns the data from the -replica set member that the client is connected to, with no guarantee that the data has -been written to all replica set members. Note that lower read concern level requirements -may reduce latency. - -For more information about read concerns or read concern levels, see -:manual:`Read Concern ` in the Server manual. For more detail on -the ``ReadConcern`` type and definitions of the read concern levels, see the `ReadConcern <{+api+}/classes/ReadConcern.html>`__ in -the API documentation. - -Example: Set the Read Concern Level of an Aggregation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This code sets the read concern level of an an aggregation to ``"majority"``: - -.. code-block:: js - - const pipeline = [ - {"$match": { - category: "KITCHENWARE", - }}, - {"$unset": [ - "_id", - "category", - ]} - ]; - - result = await myDB.collection("mycollection") - .aggregate( - pipeline, - { readConcern: - { level: "available" } - } - ); - -For more information about aggregates, see the :ref:`nodejs-aggregation` page. - -Example: Change the Read Concern of a Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This code changes the read concern level of a database to ``"local"``: - -.. code-block:: js - - const options = { readConcern: { level: "local" } }; - const myDB = client.db("mydb", options); - -Read Preference ---------------- - -The read preference determines which member of a replica set MongoDB reads when running a -query. You can also customize how the server evaluates members. - -For more detailed API documentation, see the `ReadPreference API -documentation <{+api+}/classes/ReadPreference.html>`__. - -The following table describes the ``ReadPreference`` parameters: - -.. list-table:: - :widths: 25 25 50 - :header-rows: 1 - - * - Parameter - - Type - - Description - - * - ``mode`` - - :manual:`ReadPreferenceMode ` - - Specifies a requirement or preference for which replica set - member the server reads from. The default mode, ``primary``, specifies that - operations read from the primary member of the replica set. - - * - ``tags`` *(optional)* - - :manual:`TagSet List ` - - Assigns tags to secondary replica set members to customize how the server evaluates - them. Tags cannot be used with the ``primary`` read preference mode setting. - - * - ``options`` *(optional)* - - `ReadPreferenceOptions <{+api+}/interfaces/ReadPreferenceOptions.html>`__ - - Sets various options, including :manual:`hedge ` - and :manual:`maxStalenessSeconds ` that can be - applied to your read preference. - -Example: Set Read Preference and Concerns for a Transaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This code sets the read preference, read concern, and write concern for the operations in -a transaction: - -.. code-block:: js - - const transactionOptions = { - readPreference: "primary", - readConcern: { level: "local" }, - writeConcern: { w: "majority" }, - }; - - const session = client.startSession(); - session.startTransaction(transactionOptions); - // ... - await session.commitTransaction(); - await session.endSession(); - -For more information about transactions, see :ref:`nodejs-transactions`. - -Example: Set the Read Preference of a Cluster in the Connection String -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This code example creates a MongoClient that uses the "secondary" read preference mode -when performing queries on a cluster: - -.. code-block:: js - - const uri = "mongodb+srv://:@?readPreference=secondary&maxStalenessSeconds=120"; - const client = new MongoClient(uri); - -This example also sets the ``maxStalenessSeconds`` option. For more information about connection string options, see the :manual:`Connection String Options ` -section in the manual. - -API Documentation ------------------ - -To learn more about the methods and types mentioned in this guide, see the following API -documentation: - -- `API WriteConcern <{+api+}/classes/WriteConcern.html>`__ -- `API ReadConcern <{+api+}/classes/ReadConcern.html>`__ -- `API ReadPreference <{+api+}/classes/ReadPreference.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/configure.js b/source/includes/fundamentals/configure.js new file mode 100644 index 000000000..d22a23aa0 --- /dev/null +++ b/source/includes/fundamentals/configure.js @@ -0,0 +1,109 @@ +const { MongoClient, ReadPreference } = require('mongodb'); + +// start-client-settings +const clientOptions = { + readPreference: ReadPreference.SECONDARY, + readConcern: { level: "local" }, + writeConcern: { w: 2 }, +}; + +const client = new MongoClient("mongodb://localhost:27017", clientOptions); +// end-client-settings + +async function main() { + await client.connect(); + + // start-client-settings-uri + const uri = "mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=2"; + const clientWithUri = new MongoClient(uri); + // end-client-settings-uri + + // start-transaction-settings + const transactionOptions = { + readPreference: ReadPreference.PRIMARY, + readConcern: { level: "majority" }, + writeConcern: { w: 1 }, + }; + + const session = client.startSession(); + session.startTransaction(transactionOptions); + // end-transaction-settings + + // Sets read and write settings for the "test_database" database + // start-database-settings + const dbOptions = { + readPreference: ReadPreference.PRIMARY_PREFERRED, + readConcern: { level: "available" }, + writeConcern: { w: "majority" }, + }; + + const db = client.db("test_database", dbOptions); + // end-database-settings + + // Sets read and write settings for the "test_collection" collection + // start-collection-settings + const collOptions = { + readPreference: ReadPreference.SECONDARY_PREFERRED, + readConcern: { level: "available" }, + writeConcern: { w: 0 }, + }; + + const collection = db.collection("test_collection", collOptions); + // end-collection-settings + + // Instructs the library to prefer reads from secondary replica set members + // located in New York, followed by a secondary in San Francisco, and + // lastly fall back to any secondary. + // start-tag-set + const taggedReadPreference = new ReadPreference( + ReadPreference.SECONDARY, + [ + { dc: "ny" }, + { dc: "sf" }, + {} + ] + ); + + const dbWithTags = client.db( + "test_database", + { readPreference: taggedReadPreference } + ); + // end-tag-set + + // Instructs the library to distribute reads between members within 35 milliseconds + // of the closest member's ping time + // start-local-threshold + const clientWithLocalThreshold = new MongoClient("mongodb://localhost:27017", { + replicaSet: "repl0", + readPreference: ReadPreference.SECONDARY_PREFERRED, + localThresholdMS: 35 + }); + // end-local-threshold + + // Create the "souvenirs" collection and specify the French Canadian collation + // start-collection-collation + const db = client.db("db") + db.createCollection("names", { + collation: { locale: "fr_CA" }, + }); + // end-collection-collation + + // Create an index collation on the "souvenirs" collection + // start-index-collation + const coll = db.collection("names"); + coll.createIndex( + { "last_name" : 1 }, + { "collation" : { "locale" : "en_US" } }); + // end-index-collation + + // Apply a collation to an operation + // start-operation-collation + coll.findOneAndUpdate( + { first_name: { $lt: "Gunter" } }, + { $set: { verified: true } }, + { collation: { locale: "de@collation=phonebook" } }, + ); + // end-operation-collation +} + +main().catch(console.error); \ No newline at end of file From 406b0f16a991aac8bf39a293c2b3a944df91c05c Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Thu, 10 Apr 2025 11:34:22 -0700 Subject: [PATCH 15/26] DOCSP-48386 Add monitoring page (#1046) --- .../code-snippets/monitoring/apm-subscribe.js | 6 +- .../code-snippets/monitoring/cpm-subscribe.js | 4 +- .../monitoring/sdam-subscribe.js | 6 +- source/fundamentals.txt | 1 - .../monitoring/cluster-monitoring.txt | 346 -------- .../monitoring/command-monitoring.txt | 133 ---- .../monitoring/connection-monitoring.txt | 243 ------ source/monitoring-and-logging.txt | 13 +- .../monitoring-and-logging/change-streams.txt | 6 +- source/monitoring-and-logging/logging.txt | 9 +- source/monitoring-and-logging/monitoring.txt | 741 +++++++++++++++++- 11 files changed, 747 insertions(+), 761 deletions(-) delete mode 100644 source/fundamentals/monitoring/cluster-monitoring.txt delete mode 100644 source/fundamentals/monitoring/command-monitoring.txt delete mode 100644 source/fundamentals/monitoring/connection-monitoring.txt diff --git a/source/code-snippets/monitoring/apm-subscribe.js b/source/code-snippets/monitoring/apm-subscribe.js index fb53b757c..524c01788 100644 --- a/source/code-snippets/monitoring/apm-subscribe.js +++ b/source/code-snippets/monitoring/apm-subscribe.js @@ -10,16 +10,16 @@ const client = new MongoClient(uri, { monitorCommands:true }); // Replace with the name of the event you are subscribing to const eventName = ""; -// Subscribe to a specified event and print a message when the event is received +// Subscribes to a specified event and print a message when the event is received client.on(eventName, event => console.log(event)); async function run() { try { - // Establish and verify connection to the "admin" database + // Establishes and verifies connection to the "admin" database await client.db("admin").command({ ping: 1 }); console.log("Connected successfully"); } finally { - // Close the database connection on completion or error + // Closes the database connection on completion or error await client.close(); } } diff --git a/source/code-snippets/monitoring/cpm-subscribe.js b/source/code-snippets/monitoring/cpm-subscribe.js index 596af4178..ddcc6b564 100644 --- a/source/code-snippets/monitoring/cpm-subscribe.js +++ b/source/code-snippets/monitoring/cpm-subscribe.js @@ -9,14 +9,14 @@ const client = new MongoClient(uri); // Replace with the name of the event you are subscribing to const eventName = ""; -// Subscribe to the event +// Subscribes to the event client.on(eventName, (event) => console.log("\nreceived event:\n", event) ); async function run() { try { - // Establish and verify connection + // Establishes and verifies connection await client.db("admin").command({ ping: 1 }); console.log("\nConnected successfully!\n"); } finally { diff --git a/source/code-snippets/monitoring/sdam-subscribe.js b/source/code-snippets/monitoring/sdam-subscribe.js index 90db667f1..5f24919b4 100644 --- a/source/code-snippets/monitoring/sdam-subscribe.js +++ b/source/code-snippets/monitoring/sdam-subscribe.js @@ -10,18 +10,18 @@ const client = new MongoClient(uri); // Replace with the name of the event you are subscribing to const eventName = ""; -// Subscribe to a specified event and print a message when the event is received +// Subscribes to a specified event and prints a message when the event is received client.on(eventName, event => { console.log(`received ${eventName}: ${JSON.stringify(event, null, 2)}`); }); async function run() { try { - // Establish and verify connection to the database + // Establishes and verifies connection to the database await client.db("admin").command({ ping: 1 }); console.log("Connected successfully"); } finally { - // Close the database connection on completion or error + // Closes the database connection on completion or error await client.close(); } } diff --git a/source/fundamentals.txt b/source/fundamentals.txt index b5ef4e2ab..3010fedcb 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -20,7 +20,6 @@ Fundamentals Indexes Collations Logging - Monitoring GridFS Time Series TypeScript diff --git a/source/fundamentals/monitoring/cluster-monitoring.txt b/source/fundamentals/monitoring/cluster-monitoring.txt deleted file mode 100644 index a09f792c0..000000000 --- a/source/fundamentals/monitoring/cluster-monitoring.txt +++ /dev/null @@ -1,346 +0,0 @@ -.. _node-cluster-monitoring: - -================== -Cluster Monitoring -================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, node.js, watch - :description: Monitor topology events in a MongoDB instance, replica set, or sharded cluster by subscribing to Server Discovery and Monitoring (SDAM) events with the MongoDB Node.js Driver. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecols - -Overview --------- - -This guide shows you how to monitor topology events in a MongoDB instance, -replica set, or sharded cluster. The driver creates topology events, also -known as Server Discovery and Monitoring (SDAM) events, when there is -a change in the state of the instance or cluster that you connected to. -For example, the driver creates an event when you establish a new connection -or if the cluster elects a new primary. - -The following sections demonstrate how to record topology changes in your application -and explore the information provided in these events. - -Event Subscription Example --------------------------- - -You can access one or more SDAM events using the driver by subscribing to them -in your application. The following example demonstrates connecting to a -replica set and subscribing to one of the SDAM events created by the MongoDB -deployment: - -.. literalinclude:: /code-snippets/monitoring/sdam-subscribe.js - :language: javascript - -Event Descriptions ------------------- - -You can subscribe to any of the following SDAM events: - -.. list-table:: - :widths: 33 67 - :header-rows: 1 - - * - Event Name - - Description - - * - ``serverOpening`` - - Created when a connection to an instance opens. - - * - ``serverClosed`` - - Created when a connection to an instance closes. - - * - ``serverDescriptionChanged`` - - Created when an instance state changes (such as from secondary to - primary). - - * - ``topologyOpening`` - - Created before attempting a connection to an instance. - - * - ``topologyClosed`` - - Created after all instance connections in the topology close. - - * - ``topologyDescriptionChanged`` - - Created when the topology changes, such as an election of a new - primary or a **mongos** proxy disconnecting. - - * - ``serverHeartbeatStarted`` - - Created before issuing a ``hello`` command to a MongoDB instance. - - * - ``serverHeartbeatSucceeded`` - - Created when the ``hello`` command returns successfully from a - MongoDB instance. - - * - ``serverHeartbeatFailed`` - - Created when a ``hello`` command issued to a specific MongoDB - instance fails to return a successful response. - -Example Event Documents ------------------------ - -The following sections show sample output for each type of SDAM event. - -serverDescriptionChanged -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - ServerDescriptionChangedEvent { - topologyId: 0, - address: 'localhost:27017', - previousDescription: ServerDescription { - address: 'localhost:27017', - error: null, - roundTripTime: 0, - lastUpdateTime: 1571251089030, - lastWriteDate: null, - opTime: null, - type: 'Unknown', - minWireVersion: 0, - maxWireVersion: 0, - hosts: [], - passives: [], - arbiters: [], - tags: [] - }, - newDescription: ServerDescription { - address: 'localhost:27017', - error: null, - roundTripTime: 0, - lastUpdateTime: 1571251089051, - lastWriteDate: 2019-10-16T18:38:07.000Z, - opTime: { ts: Timestamp, t: 18 }, - type: 'RSPrimary', - minWireVersion: 0, - maxWireVersion: 7, - maxBsonObjectSize: 16777216, - maxMessageSizeBytes: 48000000, - maxWriteBatchSize: 100000, - me: 'localhost:27017', - hosts: [ 'localhost:27017' ], - passives: [], - arbiters: [], - tags: [], - setName: 'rs', - setVersion: 1, - electionId: ObjectID, - primary: 'localhost:27017', - logicalSessionTimeoutMinutes: 30, - '$clusterTime': ClusterTime - } - } - -The ``type`` field of the ``ServerDescription`` object in this event contains -one of the following possible values: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Type - - Description - * - ``Unknown`` - - Unknown instance - * - ``Standalone`` - - Standalone instance - * - ``Mongos`` - - Mongos proxy instance - * - ``PossiblePrimary`` - - At least one server recognizes this as the primary, but is not yet - verified by all instances. - * - ``RSPrimary`` - - Primary instance - * - ``RSSecondary`` - - Secondary instance - * - ``RSArbiter`` - - Arbiter instance - * - ``RSOther`` - - See the `RSGhost and RSOther specification `__ - for more details - * - ``RSGhost`` - - See the `RSGhost and RSOther specification `__ - for more details - -serverHeartbeatStarted -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - ServerHeartbeatStartedEvent { - connectionId: 'localhost:27017' - } - -serverHeartbeatSucceeded -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - ServerHeartbeatSucceededEvent { - duration: 1.939997, - reply:{ - hosts: [ 'localhost:27017' ], - setName: 'rs', - setVersion: 1, - isWritablePrimary: true, - secondary: false, - primary: 'localhost:27017', - me: 'localhost:27017', - electionId: ObjectID, - lastWrite: { - opTime: { ts: [Timestamp], t: 18 }, - lastWriteDate: 2019-10-16T18:38:17.000Z, - majorityOpTime: { ts: [Timestamp], t: 18 }, - majorityWriteDate: 2019-10-16T18:38:17.000Z - }, - maxBsonObjectSize: 16777216, - maxMessageSizeBytes: 48000000, - maxWriteBatchSize: 100000, - localTime: 2019-10-16T18:38:19.589Z, - logicalSessionTimeoutMinutes: 30, - minWireVersion: 0, - maxWireVersion: 7, - readOnly: false, - ok: 1, - operationTime: Timestamp, - '$clusterTime': ClusterTime - }, - connectionId: 'localhost:27017' - } - -serverHeartbeatFailed -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - ServerHeartbeatFailed { - duration: 20, - failure: MongoError('some error'), - connectionId: 'localhost:27017' - } - -serverOpening -^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - ServerOpeningEvent { - topologyId: 0, - address: 'localhost:27017' - } - -serverClosed -^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - ServerClosedEvent { - topologyId: 0, - address: 'localhost:27017' - } - -topologyOpening -^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - TopologyOpeningEvent { - topologyId: 0 - } - -topologyClosed -^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - TopologyClosedEvent { - topologyId: 0 - } - -topologyDescriptionChanged -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - TopologyDescriptionChangedEvent { - topologyId: 0, - previousDescription: TopologyDescription { - type: 'ReplicaSetNoPrimary', - setName: null, - maxSetVersion: null, - maxElectionId: null, - servers: Map { - 'localhost:27017' => ServerDescription - }, - stale: false, - compatible: true, - compatibilityError: null, - logicalSessionTimeoutMinutes: null, - heartbeatFrequencyMS: 10000, - localThresholdMS: 15, - options: Object, - error: undefined, - commonWireVersion: null - }, - newDescription: TopologyDescription { - type: 'ReplicaSetWithPrimary', - setName: 'rs', - maxSetVersion: 1, - maxElectionId: null, - servers: Map { - 'localhost:27017' => ServerDescription - }, - stale: false, - compatible: true, - compatibilityError: null, - logicalSessionTimeoutMinutes: 30, - heartbeatFrequencyMS: 10000, - localThresholdMS: 15, - options: Object, - error: undefined, - commonWireVersion: 7 - } - } - -The ``type`` field of the ``TopologyDescription`` object in this event contains -one of the following possible values: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Type - - Description - - * - ``Single`` - - Standalone instance - - * - ``ReplicaSetWithPrimary`` - - Replica set with a primary - - * - ``ReplicaSetNoPrimary`` - - Replica set with no primary - - * - ``Sharded`` - - Sharded cluster - - * - ``Unknown`` - - Unknown topology diff --git a/source/fundamentals/monitoring/command-monitoring.txt b/source/fundamentals/monitoring/command-monitoring.txt deleted file mode 100644 index 6ee286625..000000000 --- a/source/fundamentals/monitoring/command-monitoring.txt +++ /dev/null @@ -1,133 +0,0 @@ -.. _node-command-monitoring: - -================== -Command Monitoring -================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, node.js, watch, command status - :description: Monitor the success or failure of MongoDB commands by subscribing to command monitoring events in your application with the MongoDB Node.js Driver. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecols - -Overview --------- - -This guide shows you how to monitor the success or failure of commands -sent by the driver to your MongoDB deployment. - -The following sections demonstrate how to record command status in your -application and explore the information provided in these events. - -Event Subscription Example --------------------------- - -You can access one or more command monitoring events using the driver by -subscribing to them in your application. The following example demonstrates -connecting to a replica set and subscribing to one of the command monitoring -events created by the MongoDB deployment: - -.. literalinclude:: /code-snippets/monitoring/apm-subscribe.js - :language: javascript - -.. note:: - - Command monitoring is disabled by default. To enable command - monitoring, pass the ``monitorCommands`` option as ``true`` to - your ``MongoClient`` constructor. - -Event Descriptions ------------------- - -You can subscribe to any of the following command monitoring events: - -.. list-table:: - :widths: 33 67 - :header-rows: 1 - - * - Event Name - - Description - - * - ``commandStarted`` - - Created when a command is started. - - * - ``commandSucceeded`` - - Created when a command succeeded. - - * - ``commandFailed`` - - Created when a command failed. - -Example Event Documents ------------------------ - -The following sections show sample output for each type of command monitoring event. - -commandStarted -^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - CommandStartedEvent { - requestId: 1534, - databaseName: "app", - commandName: "find", - address: 'localhost:27017', - connectionId: 812613, - command: { - find: { firstName: "Jane", lastName: "Doe" } - } - } - -commandSucceeded -^^^^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - CommandSucceededEvent { - requestId: 1534, - commandName: "find", - address: 'localhost:27017', - connectionId: 812613, - duration: 15, - reply: { - cursor: { - firstBatch: [ - { - _id: ObjectId("5e8e2ca217b5324fa9847435"), - firstName: "Jane", - lastName: "Doe" - } - ], - _id: 0, - ns: "app.users" - }, - ok: 1, - operationTime: 1586380205 - } - } - - -commandFailed -^^^^^^^^^^^^^ - -.. code-block:: javascript - :copyable: false - - CommandFailedEvent { - requestId: 1534, - commandName: "find", - address: 'localhost:27017', - connectionId: 812613, - failure: Error("something failed"), - duration: 11 - } diff --git a/source/fundamentals/monitoring/connection-monitoring.txt b/source/fundamentals/monitoring/connection-monitoring.txt deleted file mode 100644 index 0c00c65be..000000000 --- a/source/fundamentals/monitoring/connection-monitoring.txt +++ /dev/null @@ -1,243 +0,0 @@ -.. _node-connection-pool-monitoring: - -========================== -Connection Pool Monitoring -========================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, node.js, watch, deployment - :description: Monitor the MongoDB Node.js Driver's connection pool by subscribing to connection pool events to understand and debug your application's connection behavior. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecols - -Overview --------- - -This guide shows you how to monitor the driver's **connection pool**. 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 and can help your -application run faster. - -The following sections demonstrate how to record connection pool events in your -application and explore the information provided in these events. - -Event Subscription Examples ---------------------------- - -You can access one or more connection pool events using the driver by -subscribing to them in your application. The following example demonstrates -connecting to a replica set and subscribing to one of the connection -pool monitoring events created by the MongoDB deployment: - -.. literalinclude:: /code-snippets/monitoring/cpm-subscribe.js - :language: javascript - -Connection pool monitoring events can aid you in debugging and understanding -the behavior of your application's connection pool. The following example uses connection -pool monitoring events to return a count of checked-out connections in the pool: - -.. literalinclude:: /code-snippets/monitoring/cpm-status.js - :language: javascript - -Event Descriptions ------------------- - -You can subscribe to any of the following connection pool monitoring events: - -.. list-table:: - :widths: 33 67 - :header-rows: 1 - - * - Event Name - - Description - - * - ``connectionPoolCreated`` - - Created when a connection pool is created. - - * - ``connectionPoolReady`` - - Created when a connection pool is ready. - - * - ``connectionPoolClosed`` - - Created when a connection pool is closed before server - instance destruction. - - * - ``connectionCreated`` - - Created when a connection is created, but not necessarily - when it is used for an operation. - - * - ``connectionReady`` - - Created after a connection has successfully completed a - handshake and is ready to be used for operations. - - * - ``connectionClosed`` - - Created when a connection is closed. - - * - ``connectionCheckOutStarted`` - - Created when an operation attempts to acquire a connection for - execution. - - * - ``connectionCheckOutFailed`` - - Created when an operation fails to acquire a connection for - execution. - - * - ``connectionCheckedOut`` - - Created when an operation successfully acquires a connection for - execution. - - * - ``connectionCheckedIn`` - - Created when a connection is checked back into the pool after an operation - is executed. - - * - ``connectionPoolCleared`` - - Created when a connection pool is cleared. - -Example Event Documents ------------------------ - -The following sections show sample output for each type of connection -pool monitoring event. - -connectionPoolCreated -~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionPoolCreatedEvent { - time: 2023-02-13T15:54:06.944Z, - address: '...', - options: {...} - } - -connectionPoolReady -~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionPoolReadyEvent { - time: 2023-02-13T15:56:38.440Z, - address: '...' - } - -connectionPoolClosed -~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionPoolClosedEvent { - time: 2023-02-13T15:56:38.440Z, - address: '...' - } - -connectionCreated -~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionCreatedEvent { - time: 2023-02-13T15:56:38.291Z, - address: '...', - connectionId: 1 - } - -connectionReady -~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionReadyEvent { - time: 2023-02-13T15:56:38.291Z, - address: '...', - connectionId: 1, - durationMS: 60 - } - -connectionClosed -~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionClosedEvent { - time: 2023-02-13T15:56:38.439Z, - address: '...', - connectionId: 1, - reason: 'poolClosed', - serviceId: undefined - } - -connectionCheckOutStarted -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionCheckOutStartedEvent { - time: 2023-02-13T15:56:38.291Z, - address: '...', - } - -connectionCheckOutFailed -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionCheckOutFailedEvent { - time: 2023-02-13T15:56:38.291Z, - address: '...', - reason: ..., - durationMS: 60 - } - -connectionCheckedOut -~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionCheckedOutEvent { - time: 2023-02-13T15:54:07.188Z, - address: '...', - connectionId: 1, - durationMS: 60 - } - -connectionCheckedIn -~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionCheckedInEvent { - time: 2023-02-13T15:54:07.189Z, - address: '...', - connectionId: 1 - } - -connectionPoolCleared -~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - :copyable: false - - ConnectionPoolClearedEvent { - time: 2023-02-13T15:56:38.439Z, - address: '...', - serviceId: undefined, - interruptInUseConnections: true, - } - diff --git a/source/monitoring-and-logging.txt b/source/monitoring-and-logging.txt index f3e5e66cc..9dc894729 100644 --- a/source/monitoring-and-logging.txt +++ b/source/monitoring-and-logging.txt @@ -4,12 +4,9 @@ Monitoring and Logging ====================== -.. facet:: - :name: programming_language - :values: python - .. meta:: :keywords: event + :description: Learn how to monitor and log events by using the {+driver-long+}. .. toctree:: @@ -20,5 +17,9 @@ Monitoring and Logging Overview -------- -On this page, you can see copyable code examples that show common -methods you can use to monitor and log events with {+driver-short+}. \ No newline at end of file +Learn how to set up monitoring and logging for your application in the following +sections: + +- :doc:`/monitoring-and-logging/monitoring` +- :doc:`/monitoring-and-logging/logging` +- :doc:`/monitoring-and-logging/change-streams` \ No newline at end of file diff --git a/source/monitoring-and-logging/change-streams.txt b/source/monitoring-and-logging/change-streams.txt index e16fd4226..b03d55bc5 100644 --- a/source/monitoring-and-logging/change-streams.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -1,9 +1,9 @@ .. _node-usage-watch: .. _node-change-streams: -==================== -Monitor Data Changes -==================== +================================ +Monitor Data with Change Streams +================================ .. meta:: :description: Monitor changes in MongoDB using the watch() method in the MongoDB Node.js Driver on collections, databases, or clients to open change streams and handle change events. diff --git a/source/monitoring-and-logging/logging.txt b/source/monitoring-and-logging/logging.txt index e2cde5919..383e3b70f 100644 --- a/source/monitoring-and-logging/logging.txt +++ b/source/monitoring-and-logging/logging.txt @@ -202,18 +202,13 @@ The following example sets the maximum document length to 500 characters: Additional Information ---------------------- -For more information about monitoring with the {+driver-short+}, see the -following monitoring guides: - -- :ref:`Command Monitoring ` -- :ref:`Cluster Monitoring ` -- :ref:`Connection Pool Monitoring ` +For more information about monitoring with the {+driver-short+}, see the :ref:`Monitoring ` guide. API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the options or types discussed in this guide, see the -following API documentaion: +following API documentation: - `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ - `mongodbLogComponentSeverities <{+api+}/interfaces/MongoClientOptions.html#mongodbLogComponentSeverities>`__ diff --git a/source/monitoring-and-logging/monitoring.txt b/source/monitoring-and-logging/monitoring.txt index 3d329071c..742e4034d 100644 --- a/source/monitoring-and-logging/monitoring.txt +++ b/source/monitoring-and-logging/monitoring.txt @@ -1,8 +1,14 @@ .. _node-monitoring: -========== -Monitoring -========== +========================== +Monitor Application Events +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol .. meta:: :description: Explore cluster, command, and connection pool monitoring in the MongoDB Node.js Driver. @@ -11,16 +17,723 @@ Monitoring :name: genre :values: reference -.. toctree:: - :caption: CRUD Operations +.. meta:: + :keywords: event + :description: Learn how to monitor events by using the {+driver-long+}. + +Overview +-------- + +In this guide, you can learn how to set up and configure **monitoring** in the +{+driver-long+}. + +Monitoring involves collecting information about the activities of a running +program, which you can use with an application performance management +library. + +Monitoring the {+driver-short+} lets you understand the driver's resource usage +and performance, and can help you make informed decisions when designing and +debugging your application. + +In this guide you will learn how to perform these tasks: + +- :ref:`Monitor Command Events ` +- :ref:`Monitor Server Discovery and Monitoring (SDAM) Events ` +- :ref:`Monitor Connection Pool Events ` + +This guide shows how to use information about the activity of the driver in code. +To learn how to record events in the driver, see the {+driver-short+}'s +:ref:`Logging ` guide. + +.. _node-monitoring-events: + +Monitor Events +-------------- + +You can monitor events using the {+driver-short+} by subscribing to them in your +application. + +An event is any action that occurs within the driver during its operation. The +{+driver-short+} includes functionality for listening to a subset of these +events. + +The {+driver-short+} organizes the events it defines into the following categories: + +- Command Events +- Server Discovery and Monitoring (SDAM) Events +- Connection Pool Events + +The following sections show how to monitor each event category. + +.. _node-command-monitoring: + +Command Events +~~~~~~~~~~~~~~ + +A command event is an event related to a MongoDB database command. You can +access one or more command monitoring events using the driver by subscribing to +them in your application. + +To learn more about MongoDB database commands, see the +:manual:`Database Commands ` guide in the Server Manual. + +.. note:: + + Command monitoring is disabled by default. To enable command + monitoring, pass the ``monitorCommands`` option as ``true`` to + your ``MongoClient`` constructor. + +Example +``````` + +The following example demonstrates connecting to a replica set and subscribing +to one of the command monitoring events created by the MongoDB deployment: + +.. literalinclude:: /code-snippets/monitoring/apm-subscribe.js + :language: javascript + +Event Descriptions +`````````````````` + +You can subscribe to any of the following command monitoring events: + +.. list-table:: + :widths: 33 67 + :header-rows: 1 + + * - Event Name + - Description + + * - ``commandStarted`` + - Created when a command is started. + + * - ``commandSucceeded`` + - Created when a command succeeded. + + * - ``commandFailed`` + - Created when a command failed. + +commandStarted +++++++++++++++ + +.. code-block:: javascript + :copyable: false + + CommandStartedEvent { + requestId: 1534, + databaseName: "app", + commandName: "find", + address: 'localhost:27017', + connectionId: 812613, + command: { + find: { firstName: "Jane", lastName: "Doe" } + } + } + +commandSucceeded +++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + CommandSucceededEvent { + requestId: 1534, + commandName: "find", + address: 'localhost:27017', + connectionId: 812613, + duration: 15, + reply: { + cursor: { + firstBatch: [ + { + _id: ObjectId("5e8e2ca217b5324fa9847435"), + firstName: "Jane", + lastName: "Doe" + } + ], + _id: 0, + ns: "app.users" + }, + ok: 1, + operationTime: 1586380205 + } + } + + +commandFailed ++++++++++++++ + +.. code-block:: javascript + :copyable: false + + CommandFailedEvent { + requestId: 1534, + commandName: "find", + address: 'localhost:27017', + connectionId: 812613, + failure: Error("something failed"), + duration: 11 + } + + +.. _node-cluster-monitoring: + +Server Discovery and Monitoring Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} creates topology events, also known as SDAM events, when +there is a change in the state of the instance or cluster that you connected to. +For example, the driver creates an event when you establish a new connection or +if the cluster elects a new primary node. + +To learn more about topology events, see the :manual:`Replication ` guide in the Server Manual. + +The following sections demonstrate how to record topology changes in your application +and explore the information provided in these events. + +Event Subscription Example +`````````````````````````` + +You can access one or more SDAM events by subscribing to them +in your application. The following example demonstrates connecting to a +replica set and subscribing to one of the SDAM events created by the MongoDB +deployment: + +.. literalinclude:: /code-snippets/monitoring/sdam-subscribe.js + :language: javascript + +Event Descriptions +`````````````````` + +You can subscribe to any of the following SDAM events: + +.. list-table:: + :widths: 33 67 + :header-rows: 1 + + * - Event Name + - Description + + * - ``serverOpening`` + - Created when a connection to an instance opens. + + * - ``serverClosed`` + - Created when a connection to an instance closes. + + * - ``serverDescriptionChanged`` + - Created when an instance state changes (such as from secondary to + primary). + + * - ``topologyOpening`` + - Created before attempting a connection to an instance. + + * - ``topologyClosed`` + - Created after all instance connections in the topology close. + + * - ``topologyDescriptionChanged`` + - Created when the topology changes, such as an election of a new + primary or a **mongos** proxy disconnecting. + + * - ``serverHeartbeatStarted`` + - Created before issuing a ``hello`` command to a MongoDB instance. + + * - ``serverHeartbeatSucceeded`` + - Created when the ``hello`` command returns successfully from a + MongoDB instance. + + * - ``serverHeartbeatFailed`` + - Created when a ``hello`` command issued to a specific MongoDB + instance fails to return a successful response. + +Example Event Documents +``````````````````````` + +The following sections show sample output for each type of SDAM event. + +serverDescriptionChanged +++++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ServerDescriptionChangedEvent { + topologyId: 0, + address: 'localhost:27017', + previousDescription: ServerDescription { + address: 'localhost:27017', + error: null, + roundTripTime: 0, + lastUpdateTime: 1571251089030, + lastWriteDate: null, + opTime: null, + type: 'Unknown', + minWireVersion: 0, + maxWireVersion: 0, + hosts: [], + passives: [], + arbiters: [], + tags: [] + }, + newDescription: ServerDescription { + address: 'localhost:27017', + error: null, + roundTripTime: 0, + lastUpdateTime: 1571251089051, + lastWriteDate: 2019-10-16T18:38:07.000Z, + opTime: { ts: Timestamp, t: 18 }, + type: 'RSPrimary', + minWireVersion: 0, + maxWireVersion: 7, + maxBsonObjectSize: 16777216, + maxMessageSizeBytes: 48000000, + maxWriteBatchSize: 100000, + me: 'localhost:27017', + hosts: [ 'localhost:27017' ], + passives: [], + arbiters: [], + tags: [], + setName: 'rs', + setVersion: 1, + electionId: ObjectID, + primary: 'localhost:27017', + logicalSessionTimeoutMinutes: 30, + '$clusterTime': ClusterTime + } + } + +The ``type`` field of the ``ServerDescription`` object in this event contains +one of the following possible values: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Type + - Description + * - ``Unknown`` + - Unknown instance + * - ``Standalone`` + - Standalone instance + * - ``Mongos`` + - Mongos proxy instance + * - ``PossiblePrimary`` + - At least one server recognizes this as the primary, but is not yet + verified by all instances. + * - ``RSPrimary`` + - Primary instance + * - ``RSSecondary`` + - Secondary instance + * - ``RSArbiter`` + - Arbiter instance + * - ``RSOther`` + - See the `RSGhost and RSOther specification `__ + for more details + * - ``RSGhost`` + - See the `RSGhost and RSOther specification `__ + for more details + +serverHeartbeatStarted +++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ServerHeartbeatStartedEvent { + connectionId: 'localhost:27017' + } + +serverHeartbeatSucceeded +++++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ServerHeartbeatSucceededEvent { + duration: 1.939997, + reply:{ + hosts: [ 'localhost:27017' ], + setName: 'rs', + setVersion: 1, + isWritablePrimary: true, + secondary: false, + primary: 'localhost:27017', + me: 'localhost:27017', + electionId: ObjectID, + lastWrite: { + opTime: { ts: [Timestamp], t: 18 }, + lastWriteDate: 2019-10-16T18:38:17.000Z, + majorityOpTime: { ts: [Timestamp], t: 18 }, + majorityWriteDate: 2019-10-16T18:38:17.000Z + }, + maxBsonObjectSize: 16777216, + maxMessageSizeBytes: 48000000, + maxWriteBatchSize: 100000, + localTime: 2019-10-16T18:38:19.589Z, + logicalSessionTimeoutMinutes: 30, + minWireVersion: 0, + maxWireVersion: 7, + readOnly: false, + ok: 1, + operationTime: Timestamp, + '$clusterTime': ClusterTime + }, + connectionId: 'localhost:27017' + } + +serverHeartbeatFailed ++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ServerHeartbeatFailed { + duration: 20, + failure: MongoError('some error'), + connectionId: 'localhost:27017' + } + +serverOpening ++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ServerOpeningEvent { + topologyId: 0, + address: 'localhost:27017' + } + +serverClosed +++++++++++++ + +.. code-block:: javascript + :copyable: false + + ServerClosedEvent { + topologyId: 0, + address: 'localhost:27017' + } + +topologyOpening ++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + TopologyOpeningEvent { + topologyId: 0 + } + +topologyClosed +++++++++++++++ + +.. code-block:: javascript + :copyable: false + + TopologyClosedEvent { + topologyId: 0 + } + +topologyDescriptionChanged +++++++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + TopologyDescriptionChangedEvent { + topologyId: 0, + previousDescription: TopologyDescription { + type: 'ReplicaSetNoPrimary', + setName: null, + maxSetVersion: null, + maxElectionId: null, + servers: Map { + 'localhost:27017' => ServerDescription + }, + stale: false, + compatible: true, + compatibilityError: null, + logicalSessionTimeoutMinutes: null, + heartbeatFrequencyMS: 10000, + localThresholdMS: 15, + options: Object, + error: undefined, + commonWireVersion: null + }, + newDescription: TopologyDescription { + type: 'ReplicaSetWithPrimary', + setName: 'rs', + maxSetVersion: 1, + maxElectionId: null, + servers: Map { + 'localhost:27017' => ServerDescription + }, + stale: false, + compatible: true, + compatibilityError: null, + logicalSessionTimeoutMinutes: 30, + heartbeatFrequencyMS: 10000, + localThresholdMS: 15, + options: Object, + error: undefined, + commonWireVersion: 7 + } + } + +The ``type`` field of the ``TopologyDescription`` object in this event contains +one of the following possible values: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Type + - Description + + * - ``Single`` + - Standalone instance + + * - ``ReplicaSetWithPrimary`` + - Replica set with a primary + + * - ``ReplicaSetNoPrimary`` + - Replica set with no primary + + * - ``Sharded`` + - Sharded cluster + + * - ``Unknown`` + - Unknown topology + +.. _node-connection-pool-monitoring: + +Connection Pool Events +~~~~~~~~~~~~~~~~~~~~~~ + +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 and can help your application run faster. + +The following sections demonstrate how to record connection pool events in your +application and explore the information provided in these events. + +Event Subscription Examples +``````````````````````````` + +You can access one or more connection pool events using the driver by +subscribing to them in your application. The following example demonstrates +connecting to a replica set and subscribing to one of the connection +pool monitoring events created by the MongoDB deployment: + +.. literalinclude:: /code-snippets/monitoring/cpm-subscribe.js + :language: javascript + +Connection pool monitoring events can aid you in debugging and understanding +the behavior of your application's connection pool. The following example uses connection +pool monitoring events to return a count of checked-out connections in the pool: + +.. literalinclude:: /code-snippets/monitoring/cpm-status.js + :language: javascript + +Event Descriptions +`````````````````` + +You can subscribe to any of the following connection pool monitoring events: + +.. list-table:: + :widths: 33 67 + :header-rows: 1 + + * - Event Name + - Description + + * - ``connectionPoolCreated`` + - Created when a connection pool is created. + + * - ``connectionPoolReady`` + - Created when a connection pool is ready. + + * - ``connectionPoolClosed`` + - Created when a connection pool is closed before server + instance destruction. + + * - ``connectionCreated`` + - Created when a connection is created, but not necessarily + when it is used for an operation. + + * - ``connectionReady`` + - Created after a connection has successfully completed a + handshake and is ready to be used for operations. + + * - ``connectionClosed`` + - Created when a connection is closed. + + * - ``connectionCheckOutStarted`` + - Created when an operation attempts to acquire a connection for + execution. + + * - ``connectionCheckOutFailed`` + - Created when an operation fails to acquire a connection for + execution. + + * - ``connectionCheckedOut`` + - Created when an operation successfully acquires a connection for + execution. + + * - ``connectionCheckedIn`` + - Created when a connection is checked back into the pool after an operation + is executed. + + * - ``connectionPoolCleared`` + - Created when all connections are closed and the connection pool is + cleared. + +Example Event Documents +``````````````````````` + +The following sections show sample output for each type of connection +pool monitoring event. + +connectionPoolCreated ++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionPoolCreatedEvent { + time: 2023-02-13T15:54:06.944Z, + address: '...', + options: {...} + } + +connectionPoolReady ++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionPoolReadyEvent { + time: 2023-02-13T15:56:38.440Z, + address: '...' + } + +connectionPoolClosed +++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionPoolClosedEvent { + time: 2023-02-13T15:56:38.440Z, + address: '...' + } + +connectionCreated ++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionCreatedEvent { + time: 2023-02-13T15:56:38.291Z, + address: '...', + connectionId: 1 + } + +connectionReady ++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionReadyEvent { + time: 2023-02-13T15:56:38.291Z, + address: '...', + connectionId: 1, + durationMS: 60 + } + +connectionClosed +++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionClosedEvent { + time: 2023-02-13T15:56:38.439Z, + address: '...', + connectionId: 1, + reason: 'poolClosed', + serviceId: undefined + } + +connectionCheckOutStarted ++++++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionCheckOutStartedEvent { + time: 2023-02-13T15:56:38.291Z, + address: '...', + } + +connectionCheckOutFailed +++++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionCheckOutFailedEvent { + time: 2023-02-13T15:56:38.291Z, + address: '...', + reason: ..., + durationMS: 60 + } + +connectionCheckedOut +++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionCheckedOutEvent { + time: 2023-02-13T15:54:07.188Z, + address: '...', + connectionId: 1, + durationMS: 60 + } + +connectionCheckedIn ++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionCheckedInEvent { + time: 2023-02-13T15:54:07.189Z, + address: '...', + connectionId: 1 + } + +connectionPoolCleared ++++++++++++++++++++++ + +.. code-block:: javascript + :copyable: false + + ConnectionPoolClearedEvent { + time: 2023-02-13T15:56:38.439Z, + address: '...', + serviceId: undefined, + interruptInUseConnections: true, + } + +API Documentation +----------------- - Clusters - Commands - Connection Pool +To learn more about any of the options or types discussed in this guide, see the +following API documentation: -- :doc:`Cluster Monitoring `: monitoring - changes in a cluster -- :doc:`Command Monitoring `: monitoring - the execution status of commands -- :doc:`Connection Pool Monitoring `: monitoring - the driver's connection pool \ No newline at end of file +- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +- `MongoClient <{+api+}/classes/MongoClient.html>`__ \ No newline at end of file From 8dc797c046a26c5d5f4f380beb430f31ee5386ca Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Fri, 11 Apr 2025 09:20:17 -0700 Subject: [PATCH 16/26] DOCSP-48683 Refine Connection Pools page (#1067) --- .../connection-options/connection-pools.txt | 276 +++++++++++++----- 1 file changed, 207 insertions(+), 69 deletions(-) diff --git a/source/connect/connection-options/connection-pools.txt b/source/connect/connection-options/connection-pools.txt index 97fa3533a..f70abd878 100644 --- a/source/connect/connection-options/connection-pools.txt +++ b/source/connect/connection-options/connection-pools.txt @@ -1,8 +1,8 @@ .. _node-connection-pools: -================ -Connection Pools -================ +======================================== +Manage Connections with Connection Pools +======================================== .. facet:: :name: genre @@ -31,62 +31,167 @@ are created by {+driver-short+}. .. _node-faq-connection-pool: -Connection Pool Overview -------------------------- - -Every ``MongoClient`` instance has a built-in connection pool for each server -in your MongoDB topology. Connection pools open sockets on demand to -support concurrent requests to MongoDB in your application. - -The maximum size of each connection pool is set by the ``maxPoolSize`` option, which -defaults to ``100``. If the number of in-use connections to a server reaches -the value of ``maxPoolSize``, the next request to that server will wait -until a connection becomes available. - -In addition to the sockets needed to support your application's requests, -each ``MongoClient`` instance opens two more sockets per server -in your MongoDB topology for monitoring the server's state. -For example, a client connected to a three-node replica set opens six -monitoring sockets. If the application uses the default setting for -``maxPoolSize`` and only queries the primary (default) node, then -there can be at most ``106`` total connections in the connection pool. If the -application uses a :ref:`read preference ` to query the -secondary nodes, those connection pools grow and there can be -``306`` total connections. +Configure Connection Pools +-------------------------- + +Every ``MongoClient`` instance has a built-in connection pool for each server in +your MongoDB topology. If you do not configure the ``minPoolSize`` option, +connection pools open sockets on demand to support concurrent requests to +MongoDB in your application. + +You can specify the following connection pool settings in your ``MongoClient`` +instance: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Setting + - Description + + * - ``maxPoolSize`` + - | The maximum number of concurrent connections that the pool maintains. + If the number of in-use connections to a server reaches the specified + value, the next request to that server waits until a connection becomes + available. + | + | **Default**: ``100`` + + * - ``maxConnecting`` + - | The maximum number of connections that each pool can establish + concurrently. + + * - ``minPoolSize`` + - | The minimum number of concurrent connections that the pool maintains. + | + | **Default**: ``0`` + + * - ``maxIdleTimeMS`` + - | The maximum number of milliseconds that a connection can remain idle in + the pool. + | + | **Default**: ``0`` (no limit) + + * - ``waitQueueTimeoutMS`` + - | The maximum number of milliseconds that a request can wait for a socket + to become available. + | + | **Default**: ``0`` (no limit) + + +.. _node-connection-pool-max-pool-size: + +maxPoolSize +~~~~~~~~~~~ + +In addition to the sockets needed to support your application's requests, each +``MongoClient`` instance opens up to two connections per server in your +MongoDB topology for monitoring the server's state. + +For example, a client connected to a three-node replica set opens six monitoring +sockets. If the application uses the default setting for ``maxPoolSize`` and +only queries the primary (default) node, then there can be at most ``106`` open +sockets and ``100`` connections in the connection pool. If the application uses +a :ref:`read preference ` to query the secondary nodes, those +connection pools grow and there can be ``306`` total connections including the +open monitoring sockets. To support high numbers of concurrent MongoDB requests within one process, you can increase ``maxPoolSize``. -Connection pools are rate-limited. The ``maxConnecting`` option -determines the number of connections that the pool can create in -parallel at any time. For example, if the value of ``maxConnecting`` is -``2``, the third request that attempts to concurrently check out a -connection succeeds only when one the following cases occurs: +The following code creates a ``MongoClient`` instance with a maximum connection +pool size of ``200`` by specifying the ``maxPoolSize`` option in the +``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxPoolSize: 200 + }); + +.. _node-connection-pool-max-connecting: + +maxConnecting +~~~~~~~~~~~~~ + +Connection pools rate-limit connection establishment. The ``maxConnecting`` +option determines the number of connections that the pool can create in parallel +at any time. For example, if the value of ``maxConnecting`` is ``2``, the third +request that attempts to concurrently check out a connection succeeds only when +one the following cases occurs: - The connection pool finishes creating a connection and there are fewer than ``maxPoolSize`` connections in the pool. - An existing connection is checked back into the pool. -- The driver's ability to reuse existing connections improves due to - rate-limits on connection creation. -You can set the minimum number of concurrent connections to -each server with the ``minPoolSize`` option, which defaults to ``0``. -The driver initializes the connection pool with this number of sockets. If -sockets are closed, causing the total number -of sockets (both in use and idle) to drop below the minimum, more -sockets are opened until the minimum is reached. +The following code creates a ``MongoClient`` instance with a maximum number of +``2`` connections to be established concurrently per pool by specifying the +``maxConnecting`` option in the ``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxConnecting: 2 + }); + +.. _node-connection-pool-min-pool-size: + +minPoolSize +~~~~~~~~~~~ + +You can set the minimum number of connections to each server with the +``minPoolSize`` option. The driver ensures that there are always at least the +number of connections set by the ``minPoolSize`` option in the connection pool. +If sockets are closed, causing the total number of sockets (both in use and +idle) to drop below the minimum, more sockets are opened until the minimum is +reached. + +The following code creates a ``MongoClient`` instance with a minimum connnection +pool size of ``10`` by specifying the ``minPoolSize`` option in the ``options`` +object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + minPoolSize: 10 + }); + +.. _node-connection-pool-max-idle-time: + +maxIdleTimeMS +~~~~~~~~~~~~~ You can set the maximum number of milliseconds that a connection can remain idle in the pool by setting the ``maxIdleTimeMS`` option. Once a connection has been idle for ``maxIdleTimeMS``, the connection pool removes and replaces it. This option defaults to ``0`` (no limit). -The following default configuration for a ``MongoClient`` works for most -applications: +The following code creates a ``MongoClient`` instance with a maximum idle time +of ``10000`` milliseconds (10 seconds) by specifying the ``maxIdleTimeMS`` +setting in the ``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + maxIdleTimeMS: 10000 + }); + +.. _node-connection-pool-wait-queue-timeout: -.. code-block:: js - - const client = new MongoClient(""); +waitQueueTimeoutMS +~~~~~~~~~~~~~~~~~~ ``MongoClient`` supports multiple concurrent requests. For each process, create a client and reuse it for all operations in a process. This @@ -103,39 +208,72 @@ A request that waits more than the length of time defined by option if it is more important to bound the duration of operations during a load spike than it is to complete every operation. -When ``MongoClient.close()`` is called by any request, the driver -closes all idle sockets and closes all sockets that are in -use as they are returned to the pool. Calling ``MongoClient.close()`` -closes only inactive sockets and does not directly terminate -any ongoing operations. The driver closes any in-use sockets only when -the associated operations complete. However, the ``MongoClient.close()`` -method does close existing sessions and transactions, which might indirectly -affect the behavior of ongoing operations and open cursors. +The following code creates a ``MongoClient`` instance with a maximum wait queue +timeout of ``10000`` milliseconds (10 seconds) by declaring it in the +``options`` object: + +.. code-block:: javascript + + const { MongoClient } = require('mongodb'); + + const uri = ''; + const client = new MongoClient(uri, { + waitQueueTimeoutMS: 10000 + }); + +Closing Connections +-------------------- + +When any request calls ``MongoClient.close()``, the {+driver-short+} performs +the following actions: + +- Closes all idle sockets in the connection pool +- Closes all sockets that are in use as they are returned to the pool +- Closes all sockets that are in use only when the associated operations + complete + +Calling ``MongoClient.close()`` closes only inactive sockets and does not +directly terminate any ongoing operations. + +.. note:: + + The ``MongoClient.close()`` method does close existing sessions and + transactions, which might indirectly affect the behavior of ongoing + operations and open cursors. Avoid Socket Timeouts --------------------- Having a large connection pool does not always reduce reconnection -requests. Consider the following example: +requests. Consider the following example scenario: -An application has a connection pool size of 5 sockets and has the -``socketTimeoutMS`` option set to 5000 milliseconds. Operations occur, -on average, every 3000 milliseconds, and reconnection requests are -frequent. Each socket times out after 5000 milliseconds, which means -that all sockets must do something during those 5000 milliseconds to -avoid closing. +- An application has a connection pool size of 5 sockets and has the + ``socketTimeoutMS`` option set to 5000 milliseconds. +- Operations occur, on average, every 3000 milliseconds, and reconnection + requests are frequent. +- Each socket times out after 5000 milliseconds, which means that all sockets + must do something during those 5000 milliseconds to avoid closing. -One message every 3000 milliseconds is not enough to keep the sockets -active, so several of the sockets will time out after 5000 milliseconds. -To avoid excessive socket timeouts, reduce the number of connections -that the driver can maintain in the connection pool by specifying the -``maxPoolSize`` option. +In this scenario, each socket times out after 5000 milliseconds, requiring +activity within this timeout period to avoid closure. However, one message every +3000 milliseconds isn't enough to keep all sockets active, causing several of +them to time out. -To specify the optional ``maxPoolSize`` setting for your ``MongoClient``, declare -it in the ``options`` object of the constructor as follows: +To avoid excessive socket timeouts, reduce the number of connections that the +driver can maintain in the connection pool by specifying the ``maxPoolSize`` +option. To learn how to set the ``maxPoolSize`` option, see the +:ref:`node-connection-pool-max-pool-size` section. -.. code-block:: javascript +API Documentation +----------------- - const client = new MongoClient(uri, { - maxPoolSize: , - }); \ No newline at end of file +For more information about creating a ``MongoClient`` object with the +{+driver-short+} and specifying options, see the following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +- `maxPoolSize <{+api+}/interfaces/MongoClientOptions.html#maxPoolSize>`__ +- `maxConnecting <{+api+}/interfaces/MongoClientOptions.html#maxConnecting>`__ +- `minPoolSize <{+api+}/interfaces/MongoClientOptions.html#minPoolSize>`__ +- `maxIdleTimeMS <{+api+}/interfaces/MongoClientOptions.html#maxIdleTimeMS>`__ +- `waitQueueTimeoutMS <{+api+}/interfaces/MongoClientOptions.html#waitQueueTimeoutMS>`__ From 7509b7958252ff2f52d99126317c1c07ac56a264 Mon Sep 17 00:00:00 2001 From: shuangela Date: Mon, 14 Apr 2025 11:32:15 -0400 Subject: [PATCH 17/26] DOCSP-48501 add casual consistency section (#1047) * add casual consistency section: * change find to findone --- source/crud/transactions.txt | 43 ++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index cc983373d..66f19d53f 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -48,18 +48,6 @@ ACID transactions `. Operations ` section in the Server manual. -In MongoDB, multi-document transactions run within a **client session**. -A client session is a grouping of related read or write operations that -you want to execute sequentially. We recommend you reuse -your client for multiple sessions and transactions instead of -instantiating a new client each time. - -When combined with ``majority`` read and -write concerns, the driver guarantees causal consistency between the -operations. To learn more, see :manual:`Client Sessions and Causal Consistency Guarantees -` in the -Server manual. - Learn more about how to use the driver to perform multi-document transactions in the following sections of this guide: @@ -67,6 +55,37 @@ transactions in the following sections of this guide: - :ref:`Transaction Options ` - :ref:`Transaction Errors ` +.. _nodejs-causal-consistency: + +Causal Consistency +~~~~~~~~~~~~~~~~~~ + +.. sharedinclude:: dbx/causal-consistency.rst + + .. replacement:: insert-one-method + + ``insertOne()`` + + .. replacement:: update-one-method + + ``updateOne()`` + + .. replacement:: find-one-method + + ``findOne()`` + + .. replacement:: delete-one-method + + ``deleteOne()`` + + .. replacement:: majority-rc + + ``majority`` + + .. replacement:: majority-wc + + ``majority`` + .. _nodejs-transaction-apis: Transaction APIs From 822ed4cb848e790c3402430952697c28cb3dd538 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Mon, 14 Apr 2025 12:51:25 -0400 Subject: [PATCH 18/26] DOCSP-49031 UUID (#1072) * DOCSP-48717 UUID * DOCSP-49031 UUID * edits * edit import * edit * edit * JS review * tech review --- source/data-formats/bson.txt | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 25fd0f948..bef850a93 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -20,11 +20,8 @@ In this guide, you can learn how to create BSON documents, read BSON from a file and write BSON to a file by using the {+driver-short+}. **BSON**, or Binary JSON, is the data format that MongoDB uses to organize -and store data. This data format includes all JSON data structure types and -adds support for types including dates, different size integers, ObjectIds, and -binary data. You can use BSON documents in your {+language+} application by importing the -BSON package. For a complete list of supported types, see the -:manual:`BSON Types ` server manual page. +and store data. You can use BSON documents in your {+language+} application +by importing the BSON package. The code samples in this guide use the following BSON document as an example: @@ -40,6 +37,27 @@ The code samples in this guide use the following BSON document as an example: "name" : "Mongo's Pizza" } +BSON Data Types +--------------- + +BSON supports all JSON data structure types and adds support for types including +dates, different size integers, ``ObjectId``, and binary data. For a complete list of +supported types, see the :manual:`BSON Types ` page in the +{+mdb-server+} Manual. + +Universally Unique IDs (UUIDs) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} supports UUIDs by using the BSON Binary subclass ``UUID``. You +can create a ``UUID`` object by using the ``UUID()`` constructor. The following code +example generates a random UUID: + +.. code-block:: javascript + + import { UUID } from 'mongodb'; + + const myUuid = new BSON.UUID(); + Create a BSON Document ---------------------- @@ -137,5 +155,7 @@ API Documentation ----------------- To learn more about any of the methods or types discussed in this -guide, see the `BSON <{+api+}/modules/BSON.html>`__ API documentation. +guide, see the following API documentation: +- `BSON <{+api+}/modules/BSON.html>`__ +- `UUID <{+api+}/classes/BSON.UUID.html>`__ From 10c96848c5b5b2290c551932dc5fa4fcd1358cc7 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:57:37 -0400 Subject: [PATCH 19/26] DOCSP-48390 Document Data Formats: EJSON (#1069) * DOCSP-48390 Document Data Formats: EJSON * add to toc and bson import note * edit * add binary type * edit ouputs * remove additional info section * last small edits * fix link * edit * tech review * edits * tech review 2 * add note about bad orange highlighting * tech review --- source/data-formats.txt | 1 + source/data-formats/bson.txt | 22 ++- source/data-formats/extended-json.txt | 219 ++++++++++++++++++++++++++ 3 files changed, 236 insertions(+), 6 deletions(-) create mode 100644 source/data-formats/extended-json.txt diff --git a/source/data-formats.txt b/source/data-formats.txt index 4a0c516fd..a0b28f2a8 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -22,6 +22,7 @@ Specialized Data Formats :maxdepth: 1 BSON + Extended JSON Time Series Data Overview diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index bef850a93..28726bc22 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -1,9 +1,9 @@ .. _node-bson-control: .. _node-bson: -============== -Work with BSON -============== +=================== +Work with BSON Data +=================== .. default-domain:: mongodb @@ -37,6 +37,16 @@ The code samples in this guide use the following BSON document as an example: "name" : "Mongo's Pizza" } +.. note:: Use the {+driver-short+}'s BSON package + + We recommend that you use the BSON package that is bundled with the driver to avoid + compatibility issues with other BSON packages. You can import the {+driver-short+}'s + BSON package with the following import statement: + + .. code-block:: js + + import { BSON } from 'mongodb'; + BSON Data Types --------------- @@ -56,7 +66,7 @@ example generates a random UUID: import { UUID } from 'mongodb'; - const myUuid = new BSON.UUID(); + const myUuid = new UUID(); Create a BSON Document ---------------------- @@ -109,7 +119,7 @@ The following example writes the sample BSON document to ``file.bson``: .. code-block:: javascript import fs from 'fs/promises'; // Import the file system module - import { BSON } from 'bson'; // Import the BSON package + import { BSON } from 'mongodb'; // Import the BSON package // Create a BSON object const bsonData = BSON.serialize(result); @@ -133,7 +143,7 @@ The following example reads the sample BSON document from ``file.bson``: :language: javascript import fs from 'fs/promises'; // Import the file system module - import { BSON } from 'bson'; // Import the BSON package + import { BSON } from 'mongodb'; // Import the BSON package // Read the BSON data from a file const data = await fs.readFile('file.bson'); diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 000000000..0f1a93bd0 --- /dev/null +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,219 @@ +.. _node-extended-json: + +============================ +Work with Extended JSON Data +============================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code examples, bson, relaxed, canonical, legacy + +Overview +-------- + +JSON is a data format that represents the values of objects, arrays, numbers, +strings, booleans, and nulls. The **Extended JSON** format defines a reserved +set of keys prefixed with "``$``" to represent field type information that +directly corresponds to each type in BSON, the format that MongoDB uses to +store data. + +Extended JSON Formats +--------------------- + +MongoDB Extended JSON features different string formats to represent BSON data. +Each of the different formats conform to the JSON RFC +and meet specific use cases. The **Extended** format, also known as the +**Canonical** format, features specific representations for every BSON type +for bidirectional conversion without loss of information. The **Relaxed Mode** +format is more concise and closer to ordinary JSON, but does not represent +all the type information such as the specific bit width of numeric fields. + +See the following table to see a description of each format: + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 10 40 + + * - Name + - Description + + * - **Extended** + - | Also known as the *Canonical* format, this JSON representation avoids loss of + BSON type information. + | This format prioritizes type preservation at the loss of human-readability and + interoperability with older formats. + + * - **Relaxed Mode** + - | JSON representation that describes BSON documents with some type information loss. + | This format prioritizes human-readability and interoperability at the loss of + certain type information. + +To learn more about JSON, BSON, and Extended JSON, see +`our article about JSON and BSON `__ +and :manual:`Extended JSON ` in the {+mdb-server+} manual. + +.. _extended_json_example_section: + +Extended JSON Examples +~~~~~~~~~~~~~~~~~~~~~~ + +The following examples show a document containing an ObjectId, date, and long +number field represented in the Extended JSON format. Click the tab that +corresponds to the format of the example you want to see: + +.. tabs:: + + .. tab:: Extended + :tabid: extended-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": { "$numberLong": "1601499609" }}, + "numViews": { "$numberLong": "36520312" } + } + + .. tab:: Relaxed Mode + :tabid: relaxed-mode-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": "2020-09-30T18:22:51.648Z" }, + "numViews": 36520312 + } + +Write Extended JSON +------------------- + +You can write an Extended JSON string from a BSON document object by using the +``EJSON.stringify()`` method. + +The following example outputs an Extended JSON string in the Relaxed format: + +.. io-code-block:: + + .. input:: + :language: js + + import { Code, BSON } from 'mongodb'; + const EJSON = BSON.EJSON; + + const doc = { + foo: [1, 2], + bar: { hello: "world" }, + code: new Code("function x() { return 1; }", {}), + date: new Date(2024, 6, 20, 10, 30, 0), + }; + + const ejsonStr = EJSON.stringify(doc); + console.log(ejsonStr); + + .. output:: + :language: none + :visible: false + + {"foo":[1,2],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":"2024-07-20T14:30:00Z"}} + +By default, the ``stringify()`` method returns the Extended JSON string in the +Relaxed format. To specify the Canonical format, set the ``relaxed`` +option to ``false``. + +The following example shows how to output Extended JSON in the Canonical format: + +.. io-code-block:: + + .. input:: + :language: js + + import { Code, BSON } from 'mongodb'; + const EJSON = BSON.EJSON; + + const doc = { + foo: [1, 2], + bar: { hello: "world" }, + code: new Code("function x() { return 1; }", {}), + date: new Date(2024, 6, 20, 10, 30, 0), + }; + + const ejsonStr = EJSON.stringify(doc, { relaxed: false }); + print(ejsonStr) + + .. output:: + :language: none + :visible: false + + {"foo":[{"$numberInt":"1"},{"$numberInt":"2"}],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":{"$numberLong":"1721485800000"}}} + +Read Extended JSON +------------------ + +You can read an Extended JSON string into the JavaScript value or object described +by the string by using the ``EJSON.parse()`` method. + +The following example shows how you can read an Extended JSON string into a +JavaScript value or object by using the ``parse()`` method: + +.. The back ticks on ejsonStr in the below code example causes the orange +.. highlighting in this file, but the page still renders correctly. + +.. io-code-block:: + + .. input:: + :language: javascript + + import { BSON } from 'mongodb'; + const EJSON = BSON.EJSON; + + const ejsonStr = `{ + "foo": [ + { "$numberInt": "1" }, + { "$numberInt": "2" } + ], + "bar": { "hello": "world" }, + "code": { + "$code": "function x() { return 1; }", + "$scope": {} + }, + "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } } + }`; + + const doc = EJSON.parse(ejsonStr); + console.log(doc); + + .. output:: + :language: none + :visible: false + + { + foo: [ 1, 2 ], + bar: { hello: 'world' }, + code: new Code('function x() { return 1; }', {}), + bin: Binary.createFromBase64('AQIDBA==', 0) + } + +.. note:: + + The driver parses the ``$uuid`` Extended JSON type from a string to a + ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field + parsing, see the + :spec:`Special Rules for Parsing $uuid Fields ` + section in the extended JSON specification. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the `EJSON `__ API documentation. From 2c7d5f5d5bfd1ff5b0347e78096491fa0759a7fe Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Fri, 18 Apr 2025 09:56:52 -0700 Subject: [PATCH 20/26] DOCSP-48487 Move usage examples (#1071) --- config/redirects | 24 ++- snooty.toml | 7 +- source/archive-reference-files/collations.txt | 1 - .../usage-examples/insertMany.js | 14 +- .../usage-examples/insertMany.ts | 22 +-- .../code-snippets/usage-examples/insertOne.js | 16 +- .../code-snippets/usage-examples/insertOne.ts | 18 ++- source/crud/bulk-write.txt | 66 +++++++- source/crud/delete.txt | 103 +++++++++++- source/crud/insert.txt | 86 +++++++++- source/crud/query.txt | 2 +- source/crud/query/count.txt | 67 ++++---- source/crud/query/cursor.txt | 4 +- source/crud/query/distinct.txt | 49 +++++- source/crud/query/query-document.txt | 2 +- source/crud/query/retrieve.txt | 122 ++++++++++++-- source/crud/transactions.txt | 6 + .../transactions}/transaction-conv.txt | 7 +- .../transactions}/transaction-core.txt | 5 + source/crud/update.txt | 8 +- source/crud/update/modify.txt | 137 ++++++++-------- source/crud/update/replace.txt | 150 +++++++++++++++++- source/includes/connect-guide-note.rst | 3 +- .../includes/crud/example-identical-code.rst | 4 + source/includes/crud/example-intro.rst | 10 ++ .../monitoring-and-logging/change-streams.txt | 53 ++----- source/reference/release-notes.txt | 2 +- source/run-command.txt | 42 ++++- source/typescript.txt | 5 +- source/usage-examples.txt | 130 --------------- source/usage-examples/bulkWrite.txt | 101 ------------ source/usage-examples/command.txt | 71 --------- source/usage-examples/delete-operations.txt | 18 --- source/usage-examples/deleteMany.txt | 65 -------- source/usage-examples/deleteOne.txt | 77 --------- source/usage-examples/distinct.txt | 80 ---------- source/usage-examples/find-operations.txt | 16 -- source/usage-examples/find.txt | 108 ------------- source/usage-examples/findOne.txt | 87 ---------- source/usage-examples/insert-operations.txt | 16 -- source/usage-examples/insertMany.txt | 51 ------ source/usage-examples/insertOne.txt | 70 -------- source/usage-examples/replaceOne.txt | 64 -------- source/usage-examples/transactions.txt | 20 --- .../update-and-replace-operations.txt | 19 --- source/usage-examples/updateMany.txt | 51 ------ source/usage-examples/updateOne.txt | 73 --------- 47 files changed, 810 insertions(+), 1342 deletions(-) rename source/{usage-examples => crud/transactions}/transaction-conv.txt (98%) rename source/{usage-examples => crud/transactions}/transaction-core.txt (98%) create mode 100644 source/includes/crud/example-identical-code.rst create mode 100644 source/includes/crud/example-intro.rst delete mode 100644 source/usage-examples.txt delete mode 100644 source/usage-examples/bulkWrite.txt delete mode 100644 source/usage-examples/command.txt delete mode 100644 source/usage-examples/delete-operations.txt delete mode 100644 source/usage-examples/deleteMany.txt delete mode 100644 source/usage-examples/deleteOne.txt delete mode 100644 source/usage-examples/distinct.txt delete mode 100644 source/usage-examples/find-operations.txt delete mode 100644 source/usage-examples/find.txt delete mode 100644 source/usage-examples/findOne.txt delete mode 100644 source/usage-examples/insert-operations.txt delete mode 100644 source/usage-examples/insertMany.txt delete mode 100644 source/usage-examples/insertOne.txt delete mode 100644 source/usage-examples/replaceOne.txt delete mode 100644 source/usage-examples/transactions.txt delete mode 100644 source/usage-examples/update-and-replace-operations.txt delete mode 100644 source/usage-examples/updateMany.txt delete mode 100644 source/usage-examples/updateOne.txt diff --git a/config/redirects b/config/redirects index 510ef00ce..23238c3bf 100644 --- a/config/redirects +++ b/config/redirects @@ -26,6 +26,8 @@ raw: ${prefix}/stable -> ${base}/current/ [*-v6.0)]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ +# Comprehensive Coverage Redirects + [*-master]: ${prefix}/${version}/quick-start/download-and-install/ -> ${base}/${version}/get-started/ [*-master]: ${prefix}/${version}/quick-start/create-a-deployment/ -> ${base}/${version}/get-started/ [*-master]: ${prefix}/${version}/quick-start/create-a-connection-string/ -> ${base}/${version}/get-started/ @@ -49,7 +51,6 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/query/retrieve/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/query/project/ -[*-master]: ${prefix}/${version}/fundamentals/usage-examples/count/ -> ${base}/${version}/crud/query/count/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/distinct/ -> ${base}/${version}/crud/query/distinct/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/query/cursor/ [*-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/query/geo/ @@ -83,6 +84,23 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/crud/update/modify/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/crud/update/embedded-arrays/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/pkFactory/ -> ${base}/crud/pkFactory/ - -# Comprehensive Coverage Redirects [*-master]: ${prefix}/${version}/security/authentication/enterprise-mechanisms/ -> ${base}/security/authentication + +# Usage Example Redirects + +[*-master]: ${prefix}/${version}/usage-examples/findOne/ -> ${base}/crud/query/retrieve/ +[*-master]: ${prefix}/${version}/usage-examples/find/ -> ${base}/crud/query/retrieve/ +[*-master]: ${prefix}/${version}/usage-examples/insertOne/ -> ${base}/crud/insert/ +[*-master]: ${prefix}/${version}/usage-examples/insertMany/ -> ${base}/crud/insert/ +[*-master]: ${prefix}/${version}/usage-examples/updateOne/ -> ${base}/crud/update/modify/ +[*-master]: ${prefix}/${version}/usage-examples/updateMany/ -> ${base}/crud/update/modify/ +[*-master]: ${prefix}/${version}/usage-examples/replaceOne/ -> ${base}/crud/update/replace/ +[*-master]: ${prefix}/${version}/usage-examples/deleteOne/ -> ${base}/crud/delete/ +[*-master]: ${prefix}/${version}/usage-examples/deleteMany/ -> ${base}/crud/delete/ +[*-master]: ${prefix}/${version}/usage-examples/count/ -> ${base}/crud/query/count/ +[*-master]: ${prefix}/${version}/usage-examples/distinct/ -> ${base}/crud/query/distinct/ +[*-master]: ${prefix}/${version}/usage-examples/command/ -> ${base}/run-command/ +[*-master]: ${prefix}/${version}/usage-examples/bulkWrite/ -> ${base}/bulk-write/ +[*-master]: ${prefix}/${version}/usage-examples/transactions/ -> ${base}/crud/transactions/ +[*-master]: ${prefix}/${version}/usage-examples/transaction-conv/ -> ${base}/crud/transactions/transaction-conv/ +[*-master]: ${prefix}/${version}/usage-examples/transaction-core/ -> ${base}/crud/transactions/transaction-core/ \ No newline at end of file diff --git a/snooty.toml b/snooty.toml index 0a1898d0f..ec8980a92 100644 --- a/snooty.toml +++ b/snooty.toml @@ -15,11 +15,12 @@ toc_landing_pages = [ "/security/authentication", "/aggregation-tutorials", "/data-formats", - "connect/connection-options", - "crud", + "/connect/connection-options", + "/crud", "/crud/query", "crud/update", - "monitoring-and-logging" + "/crud/transactions", + "/monitoring-and-logging" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/archive-reference-files/collations.txt b/source/archive-reference-files/collations.txt index 2ad831cbd..dc893b7f5 100644 --- a/source/archive-reference-files/collations.txt +++ b/source/archive-reference-files/collations.txt @@ -1,5 +1,4 @@ .. _node-fundamentals-collations: -.. _node-collations: ========== Collations diff --git a/source/code-snippets/usage-examples/insertMany.js b/source/code-snippets/usage-examples/insertMany.js index 93725a522..e499740c0 100644 --- a/source/code-snippets/usage-examples/insertMany.js +++ b/source/code-snippets/usage-examples/insertMany.js @@ -9,21 +9,21 @@ async function run() { try { // Get the database and collection on which to run the operation - const database = client.db("insertDB"); - const foods = database.collection("foods"); + const database = client.db("sample_mflix"); + const movies = database.collection("movies"); // Create an array of documents to insert - const docs = [ - { name: "cake", healthy: false }, - { name: "lettuce", healthy: true }, - { name: "donut", healthy: false } + const moviesToInsert = [ + { title: "Arsenic and Old Lace", genres: ["Comedy", "Romance"], year: 1944, cast: ["Cary Grant", "Priscilla Lane", "Raymond Massey"] }, + { title: "Ball of Fire", genres: ["Comedy", "Romance"], year: 1941, cast: ["Gary Cooper", "Barbara Stanwyck", "Oskar Homolka"] }, + { title: "I Married a Witch", genres: ["Comedy", "Fantasy", "Romance"], year: 1942, cast: ["Veronica Lake", "Fredric March", "Susan Hayward"] }, ]; // Prevent additional documents from being inserted if one fails const options = { ordered: true }; // Execute insert operation - const result = await foods.insertMany(docs, options); + const result = await movies.insertMany(moviesToInsert, options); // Print result console.log(`${result.insertedCount} documents were inserted`); diff --git a/source/code-snippets/usage-examples/insertMany.ts b/source/code-snippets/usage-examples/insertMany.ts index 0b1eeb3ee..a9618a76a 100644 --- a/source/code-snippets/usage-examples/insertMany.ts +++ b/source/code-snippets/usage-examples/insertMany.ts @@ -5,24 +5,24 @@ const uri = ""; const client = new MongoClient(uri); -interface Food { - name: string; - healthy: boolean; +interface Movie { + title: string; + genres: string[]; + year: number; + cast: string[]; } async function run() { try { - const database = client.db("insertDB"); + const database = client.db("sample_mflix"); // Specifying a schema is optional, but it enables type hints on // finds and inserts - const foods = database.collection("foods"); + const movies = database.collection("movies"); - const result = await foods.insertMany( - [ - { name: "cake", healthy: false }, - { name: "lettuce", healthy: true }, - { name: "donut", healthy: false }, - ], + const result = await movies.insertMany( + { title: "Arsenic and Old Lace", genres: ["Comedy", "Romance"], year: 1944, cast: ["Cary Grant", "Priscilla Lane", "Raymond Massey"] }, + { title: "Ball of Fire", genres: ["Comedy", "Romance"], year: 1941, cast: ["Gary Cooper", "Barbara Stanwyck", "Oskar Homolka"] }, + { title: "I Married a Witch", genres: ["Comedy", "Fantasy", "Romance"], year: 1942, cast: ["Veronica Lake", "Fredric March", "Susan Hayward"] }, { ordered: true } ); console.log(`${result.insertedCount} documents were inserted`); diff --git a/source/code-snippets/usage-examples/insertOne.js b/source/code-snippets/usage-examples/insertOne.js index 1fe32e496..a8353e0fb 100644 --- a/source/code-snippets/usage-examples/insertOne.js +++ b/source/code-snippets/usage-examples/insertOne.js @@ -8,17 +8,19 @@ const client = new MongoClient(uri); async function run() { try { - // Connect to the "insertDB" database and access its "haiku" collection - const database = client.db("insertDB"); - const haiku = database.collection("haiku"); + // Connect to the "sample_mflix" database and access its "movies" collection + const database = client.db("sample_mflix"); + const movies = database.collection("movies"); // Create a document to insert const doc = { - title: "Record of a Shriveled Datum", - content: "No bytes, no problem. Just insert a document, in MongoDB", + title: "Charade", + genres: ["Comedy", "Romance", "Thriller"], + year: 1963, + cast: ["Cary Grant", "Audrey Hepburn", "Walter Matthau"], } - // Insert the defined document into the "haiku" collection - const result = await haiku.insertOne(doc); + // Insert the defined document into the "movies" collection + const result = await movies.insertOne(doc); // Print the ID of the inserted document console.log(`A document was inserted with the _id: ${result.insertedId}`); diff --git a/source/code-snippets/usage-examples/insertOne.ts b/source/code-snippets/usage-examples/insertOne.ts index 99a229bdf..3bdd1be4d 100644 --- a/source/code-snippets/usage-examples/insertOne.ts +++ b/source/code-snippets/usage-examples/insertOne.ts @@ -5,20 +5,24 @@ const uri = ""; const client = new MongoClient(uri); -interface Haiku { +interface Movie { title: string; - content: string; + content: string[]; + year: number; + cast: string[]; } async function run() { try { - const database = client.db("insertDB"); + const database = client.db("sample_mflix"); // Specifying a Schema is optional, but it enables type hints on // finds and inserts - const haiku = database.collection("haiku"); - const result = await haiku.insertOne({ - title: "Record of a Shriveled Datum", - content: "No bytes, no problem. Just insert a document, in MongoDB", + const movies = database.collection("movies"); + const result = await movies.insertOne({ + title: "Charade", + genres: ["Comedy", "Romance", "Thriller"], + year: 1963, + cast: ["Cary Grant", "Audrey Hepburn", "Walter Matthau"], }); console.log(`A document was inserted with the _id: ${result.insertedId}`); } finally { diff --git a/source/crud/bulk-write.txt b/source/crud/bulk-write.txt index 35c9c6310..100204b56 100644 --- a/source/crud/bulk-write.txt +++ b/source/crud/bulk-write.txt @@ -10,6 +10,14 @@ Bulk Operations :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to perform bulk operations by using the {+driver-long+}. + :keywords: insert, update, replace, code example, efficiency + Overview -------- @@ -220,7 +228,7 @@ The following table describes the fields that you can set in a * - ``collation`` - | (Optional) The collation to use when sorting results. To learn more - about collations, see the :ref:`node-fundamentals-collations` guide. + about collations, see the :ref:`node-collations` section of the :ref:`node-configure` guide. | Type: ``String`` or ``Object`` * - ``hint`` @@ -299,7 +307,7 @@ The following table describes the fields that you can set in a * - ``collation`` - | (Optional) The collation to use when sorting results. To learn more - about collations, see the :ref:`node-fundamentals-collations` guide. + about collations, see the :ref:`node-collations` section of the :ref:`node-configure` guide. | Type: ``String`` or ``Object`` * - ``hint`` @@ -387,7 +395,7 @@ The following table describes the fields you can set in an ``UpdateOneModel`` or * - ``collation`` - | (Optional) The collation to use when sorting results. To learn more about - collations, see the :ref:`node-fundamentals-collations` guide. + collations, see the :ref:`node-collations` section of the :ref:`node-configure` guide. | Type: ``Object`` * - ``hint`` @@ -474,7 +482,7 @@ to specify an update operation: * - ``collation`` - | (Optional) The collation to use when sorting results. To learn more about - collations, see the :ref:`node-fundamentals-collations` guide. + collations, see the :ref:`node-collations` section of the :ref:`node-configure` guide. | Type: ``Document`` * - ``hint`` @@ -558,7 +566,7 @@ The following table describes the fields you can set in a ``DeleteOneModel`` or * - ``collation`` - | (Optional) The collation to use when sorting results. To learn more about - collations, see the :ref:`node-fundamentals-collations` guide. + collations, see the :ref:`node-collations` section of the :ref:`node-configure` guide. | Type: ``Object`` * - ``hint`` @@ -635,7 +643,7 @@ to specify a delete operation: * - ``collation`` - | (Optional) The collation to use when sorting results. To learn more about - collations, see the :ref:`node-fundamentals-collations` guide. + collations, see the :ref:`node-collations` section of the :ref:`node-configure` guide. | Type: ``Document`` Example @@ -823,6 +831,52 @@ A ``MongoClientBulkWriteError`` object contains the following properties: progress before the error. | Type: ``ClientBulkWriteResult`` +.. _node-usage-bulk: + +bulkWrite() Example: Full File +------------------------------ + +.. include:: /includes/crud/example-intro.rst + +The following code is a complete, standalone file that performs a bulk write +operation on the ``theaters`` collection in the ``sample_mflix`` database. The +``operations`` parameter includes examples of ``insertOne``, +``updateMany``, and ``deleteOne`` write operations: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/bulkWrite.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/bulkWrite.ts + :language: typescript + :linenos: + +Running the preceding example results in the following output: + +.. code-block:: javascript + :copyable: false + + BulkWriteResult { + insertedCount: 2, + matchedCount: 1, + modifiedCount: 1, + deletedCount: 0, + upsertedCount: 0, + upsertedIds: {}, + insertedIds: { + '0': new ObjectId("..."), + '1': new ObjectId("...") + } + } + .. _node-bulk-addtl-info: Additional Information diff --git a/source/crud/delete.txt b/source/crud/delete.txt index fe388e822..fdc804afd 100644 --- a/source/crud/delete.txt +++ b/source/crud/delete.txt @@ -11,9 +11,16 @@ Delete Documents .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, node.js, delete data + Overview -------- @@ -28,6 +35,14 @@ use ``deleteOne()`` to remove one document or ``deleteMany()`` for one or more documents. These methods accept a query document that matches the documents you want to delete. +.. note:: + + If your application uses information about the deleted document after deletion, + you can use the + `collection.findOneAndDelete() <{+api+}/classes/Collection.html#findOneAndDelete>`__ + method, which has a similar interface to ``deleteOne()`` but also + returns the deleted document. + You can specify the document or documents to be deleted by the ``deleteOne()`` or ``deleteMany()`` write operations in a JSON object as follows: @@ -62,6 +77,86 @@ method calls above as follows: If the delete operation is successful, these statements print the number of documents deleted by the associated operation. -To see fully runnable examples and more information on the available options, see the usage -examples for :doc:`deleteOne() ` and -:doc:`deleteMany() `. +.. _node-usage-deleteone: + +deleteOne() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/crud/example-intro.rst + +.. include:: /includes/crud/example-identical-code.rst + +The following code is a complete, standalone file that performs a delete one +operation: + +.. literalinclude:: /code-snippets/usage-examples/deleteOne.js + :language: javascript + :linenos: + +Running the preceding example results in the following output: + +.. code-block:: none + :copyable: false + + Successfully deleted one document. + +If you run the example more than once, the code produces the following output +because you deleted the matching document in the first run: + +.. code-block:: none + :copyable: false + + No documents matched the query. Deleted 0 documents. + +.. _node-usage-deletemany: + +deleteMany() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/crud/example-intro.rst + +The following code is a complete, standalone file that performs a delete many +operation: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/deleteMany.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/deleteMany.ts + :language: typescript + :linenos: + +Running the preceding example for the first time results in the following output: + +.. code-block:: none + :copyable: false + + Deleted 19 documents + +If you run the example more than once, you see the following output because +you deleted the matching documents in the first run: + +.. code-block:: none + :copyable: false + + Deleted 0 documents + +API Documentation +----------------- + +To learn more about any of the types or methods discussed in this guide, see the +following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `deleteOne() <{+api+}/classes/Collection.html#deleteOne>`__ +- `deleteMany() <{+api+}/classes/Collection.html#deleteMany>`__ \ No newline at end of file diff --git a/source/crud/insert.txt b/source/crud/insert.txt index daf2bda5d..c60b916a2 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -16,7 +16,7 @@ Insert Documents .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol Overview @@ -46,8 +46,8 @@ operations: full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane. The following sections focus on ``insertOne()`` and ``insertMany()``. For an -example on how to use the ``bulkWrite()`` method, see our runnable :doc:`Bulk -Operations Example `. +example on how to use the ``bulkWrite()`` method, see the :ref:`node-usage-bulk` +section of the :ref:`node-bulk-write` guide. .. _id-note: @@ -115,7 +115,39 @@ section, see the following resources: - API Documentation on `insertOne() <{+api+}/classes/Collection.html#insertOne>`__ - API Documentation on `InsertOneResult <{+api+}/interfaces/InsertOneResult.html>`__ - Server manual entry on :manual:`insertOne() ` -- Runnable :doc:`Insert a Document Example ` + +.. _node-usage-insert: + +insertOne() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/crud/example-intro.rst + +The following code is a complete, standalone file that performs an insert one +operation: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/insertOne.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/insertOne.ts + :language: typescript + :linenos: + +Running the preceding example results in the following output: + +.. code-block:: none + :copyable: false + + A document was inserted with the _id: ... Insert Multiple Documents ------------------------- @@ -240,10 +272,54 @@ section, see the following resources: - API Documentation on `InsertManyResult <{+api+}/interfaces/InsertManyResult.html>`__ - API Documentation on `PkFactory <{+api+}/interfaces/PkFactory.html>`__ - Server manual entry on :manual:`insertMany() ` -- Runnable :doc:`Insert Multiple Documents Example ` + +.. _node-usage-insertmany: + +insertMany() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/crud/example-intro.rst + +The following code is a complete, standalone file that performs an insert many +operation: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/insertMany.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/insertMany.ts + :language: typescript + :linenos: + +Running the preceding example results in the following output: + +.. code-block:: none + :copyable: false + + 3 documents were inserted .. _node-insert-instruqt-lab: .. instruqt:: /mongodb-docs/tracks/insert-node?token=em_S6rjcmIzxGB4Sz_y :title: insertOne() Lesson :drawer: + +API Documentation +----------------- + +To learn more about any of the types or methods discussed in this guide, see the +following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `insertOne() <{+api+}/classes/Collection.html#insertOne>`__ +- `insertMany() <{+api+}/classes/Collection.html#insertMany>`__ \ No newline at end of file diff --git a/source/crud/query.txt b/source/crud/query.txt index b8e793575..b0d5f9cf7 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -157,7 +157,7 @@ Additional Information ~~~~~~~~~~~~~~~~~~~~~~ For runnable code examples that demonstrate find operations, see the following -usage examples: +examples: - :ref:`node-usage-findone` - :ref:`node-usage-find` diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index e272af18d..1299bb121 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -5,11 +5,26 @@ Count Documents =============== -.. meta:: - :description: Learn how to count documents in a collection by using the MongoDB Node.js Driver, with methods for both estimated and accurate counts. +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol -The Node.js driver provides two methods for counting documents in a -collection: +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, node.js, count documents + :description: Learn how to count documents in a collection using the {+driver-long+}. + +Overview +-------- + +In this guide, you can learn how to count the number of documents in your +MongoDB collections. The {+driver-short+} provides two methods for counting +documents in a collection: - `collection.countDocuments() <{+api+}/classes/Collection.html#countDocuments>`__ returns the number of documents in the collection that match the specified query. If you specify an empty @@ -27,7 +42,7 @@ provides an **accurate** count of the number of documents and supports specifying a filter. Choose the appropriate method for your workload. To specify which documents you wish to count, ``countDocuments()`` -accepts a :doc:`query ` parameter. +accepts a :ref:`query ` parameter. ``countDocuments()`` counts the documents that match the specified query. ``countDocuments()`` and ``estimatedDocumentCount()`` support optional @@ -46,41 +61,37 @@ documentation for each method for more information. collection.countDocuments({}, { hint: "_id_" }); -Example -------- +countDocuments() Example: Full File +----------------------------------- + +.. include:: /includes/crud/example-intro.rst + +.. include:: /includes/crud/example-identical-code.rst The following example estimates the number of documents in the ``movies`` collection in the ``sample_mflix`` database, and then returns an accurate count of the number of documents in the ``movies`` -collection with ``Canada`` in the ``countries`` field. - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/count.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript +collection with ``Canada`` in the ``countries`` field: .. literalinclude:: /code-snippets/usage-examples/count.js :language: javascript :linenos: -.. note:: Identical Code Snippets - - The JavaScript and TypeScript code snippets above are identical. There are no - TypeScript specific features of the driver relevant to this use case. - -Running the preceding sample code, you see the following output: +Running the preceding sample code results in the following output: .. code-block:: none :copyable: false Estimated number of documents in the movies collection: 23541 Number of movies from Canada: 1349 + +API Documentation +----------------- + +To learn more about any of the types or methods discussed in this guide, see the +following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `countDocuments() <{+api+}/classes/Collection.html#countDocuments>`__ \ No newline at end of file diff --git a/source/crud/query/cursor.txt b/source/crud/query/cursor.txt index bbe4212fa..2abaaa62b 100644 --- a/source/crud/query/cursor.txt +++ b/source/crud/query/cursor.txt @@ -40,8 +40,8 @@ The following functions directly return cursors: - ``Db.listCollections()`` -Other methods such as :doc:`Collection.findOne() ` -and :doc:`Collection.watch() ` use +Other methods such as :ref:`Collection.findOne() ` +and :doc:`Collection.watch() ` use cursors internally, and return the results of the operations instead of a cursor. diff --git a/source/crud/query/distinct.txt b/source/crud/query/distinct.txt index 96aa5ca06..99300a878 100644 --- a/source/crud/query/distinct.txt +++ b/source/crud/query/distinct.txt @@ -120,7 +120,8 @@ You can specify the collation to the ``distinct()`` method by defining a ``collation`` field as an ``options`` parameter. This field allows you to set regional rules for string ordering and comparisons. -See :ref:`node-fundamentals-collations` for instructions on applying collations. +See the :ref:`node-collations` section of the :ref:`node-configure` guide for +instructions on applying collations. .. note:: @@ -162,15 +163,47 @@ with unaccented first letters: [ "Borgatti's", "Samba Kitchen", "Tanoreen", "Via Carota", "White Bear", "Äpfel" ] -Additional Information ----------------------- +.. _node-usage-distinct: -For a runnable example of retrieving distinct values, see :ref:`node-usage-distinct`. +distinct() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -API Documentation -~~~~~~~~~~~~~~~~~ +.. include:: /includes/crud/example-intro.rst + +The following snippet retrieves a list of distinct values for the ``year`` +document field from the ``movies`` collection. It uses a query document to +match movies that include ``"Barbara Streisand"`` in the ``director`` array. + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/distinct.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript -To learn more about the ``distinct()`` method and its parameters, you can visit the -`API documentation <{+api+}/classes/Collection.html#distinct>`__. + .. literalinclude:: /code-snippets/usage-examples/distinct.ts + :language: typescript + :linenos: + +Running the preceding example, results in the following output: + +.. code-block:: json + :copyable: false + + [ 1983, 1991, 1996 ] + +API Documentation +----------------- +To learn more about any of the types or methods discussed in this guide, see the +following API documentation: +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `distinct() <{+api+}/classes/Collection.html#distinct>`__. \ No newline at end of file diff --git a/source/crud/query/query-document.txt b/source/crud/query/query-document.txt index d9835dcdc..5eb84aafd 100644 --- a/source/crud/query/query-document.txt +++ b/source/crud/query/query-document.txt @@ -13,7 +13,7 @@ Specify a Query .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol Overview diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 585d920b6..8b42501b4 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -16,7 +16,7 @@ Find Documents .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol .. _nodejs-driver-retrieve-data-overview: @@ -42,10 +42,8 @@ You can also further specify the information that the find operation returns by specifying optional parameters or by chaining other methods, as shown in the following guides: -- :ref:`node-fundamentals-sort` -- :ref:`node-fundamentals-skip` -- :ref:`node-fundamentals-limit` -- :ref:`node-fundamentals-project` +- :ref:`node-specify-documents-to-return` +- :ref:`node-project` You can also use an aggregation operation to retrieve data. This type of operation allows you to apply an ordered pipeline of transformations to the @@ -144,14 +142,112 @@ a ``null`` value if there are no matches. ... ] -Additional Information -~~~~~~~~~~~~~~~~~~~~~~ +.. _node-usage-findone: + +findOne() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/crud/example-intro.rst + +The following full file example finds a single document from the ``movies`` +collection. It uses the following parameters: + +- **Filter** that matches documents in which the ``title`` value is ``'The + Room'``. + +- **Sort** that organizes matched documents in descending order by + rating, so if our query matches multiple documents the returned + document will be the document with the highest rating. + +- **Projection** that explicitly excludes the ``_id`` field from + returned documents and explicitly includes only the ``title`` and + ``imdb`` object (and its embedded fields). + +.. _node-driver-findone-usage-example-code-snippet: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/findOne.js + :language: javascript + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/findOne.ts + :language: typescript + + +Running the preceding example results in the following output: + +.. code-block:: javascript + :copyable: false + + { title: 'The Room', imdb: { rating: 3.5, votes: 25673, id: 368226 } } + +.. _node-usage-find: -For runnable code examples that demonstrate find operations, see the following -usage examples: +find() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~ -- :ref:`node-usage-findone` -- :ref:`node-usage-find` +.. include:: /includes/crud/example-intro.rst + +The following full file example finds documents from the ``movies`` collection. It +uses the following parameters: + +- **Filter** that matches documents in which the ``runtime`` value is less than 15 + minutes. + +- **Sort** that organizes returned documents in ascending order by + title (alphabetical order in which "A" comes before "Z" and "1" before + "9"). + +- **Projection** that explicitly excludes the ``_id`` field from + returned documents and explicitly includes only the ``title`` and + ``imdb`` object (and its embedded fields). + +.. _node-driver-find-usage-example-code-snippet: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/find.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/find.ts + :language: typescript + :linenos: + +Running the preceding example results in the following output: + +.. code-block:: javascript + :copyable: false + + { title: '10 Minutes', imdb: { rating: 7.9, votes: 743, id: 339976 } } + { title: '3x3', imdb: { rating: 6.9, votes: 206, id: 1654725 } } + { title: '7:35 in the Morning', imdb: { rating: 7.3, votes: 1555, id: 406501 } } + { title: '8', imdb: { rating: 7.8, votes: 883, id: 1592502 } } + ... + +You can also specify ``sort`` and ``projection`` options by chaining the +``sort()`` and ``projection`` methods to the ``find()`` method. The following +two commands are equivalent: + +.. code-block:: javascript + + movies.find({ runtime: { $lt: 15 } }, { sort: { title: 1 }, projection: { _id: 0, title: 1, imdb: 1 }}); + movies.find({ runtime: { $lt: 15 } }).sort({ title: 1}).project({ _id: 0, title: 1, imdb: 1 }); + +Additional Information +~~~~~~~~~~~~~~~~~~~~~~ For more information about the ``findOne()`` and ``find()`` methods, see the following Server manual documentation: @@ -234,8 +330,8 @@ data whenever write operations are executed on the collection. Additional Information ~~~~~~~~~~~~~~~~~~~~~~ -For a runnable example of the ``watch()`` method, see the -:ref:`Watch for Changes ` usage example. +For a runnable example of the ``watch()`` method, see the :ref:`examples +` section in the :ref:`node-change-streams` guide. .. _node-retrieve-instruqt-lab: diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 66f19d53f..4a82050d4 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -19,6 +19,12 @@ Transactions :depth: 2 :class: singlecol +.. toctree:: + :caption: Transaction Usage Examples + + Convenient Transaction API + Core API + Overview -------- diff --git a/source/usage-examples/transaction-conv.txt b/source/crud/transactions/transaction-conv.txt similarity index 98% rename from source/usage-examples/transaction-conv.txt rename to source/crud/transactions/transaction-conv.txt index 149f99146..3e918dda3 100644 --- a/source/usage-examples/transaction-conv.txt +++ b/source/crud/transactions/transaction-conv.txt @@ -4,9 +4,14 @@ Use the Convenient Transaction API ================================== +.. facet:: + :name: genre + :values: reference + .. meta:: :description: Perform a transaction using the Convenient Transaction API with the MongoDB Node.js Driver to update data atomically. - + :keywords: modify, customize + .. contents:: On this page :local: :backlinks: none diff --git a/source/usage-examples/transaction-core.txt b/source/crud/transactions/transaction-core.txt similarity index 98% rename from source/usage-examples/transaction-core.txt rename to source/crud/transactions/transaction-core.txt index 0c2545325..bf8d3714e 100644 --- a/source/usage-examples/transaction-core.txt +++ b/source/crud/transactions/transaction-core.txt @@ -4,8 +4,13 @@ Use the Core API ================ +.. facet:: + :name: genre + :values: reference + .. meta:: :description: Use the Core API with the MongoDB Node.js Driver to update multiple documents in a single transaction. + :keywords: modify, customize .. contents:: On this page :local: diff --git a/source/crud/update.txt b/source/crud/update.txt index fbf2dd272..80cf3caec 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -16,7 +16,7 @@ Update Documents .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol .. toctree:: @@ -36,9 +36,9 @@ an insert or update operation depends on whether the document exists. In these cases, you can streamline your application logic by using the ``upsert`` option available in the following methods: -- :doc:`updateOne() ` -- :doc:`replaceOne() ` -- :doc:`updateMany() ` +- :ref:`updateOne() ` +- :ref:`replaceOne() ` +- :ref:`updateMany() ` If the query filter passed to these methods does not find any matches and you set the ``upsert`` option to ``true``, MongoDB inserts the update diff --git a/source/crud/update/modify.txt b/source/crud/update/modify.txt index b4bef4ad8..501c0359d 100644 --- a/source/crud/update/modify.txt +++ b/source/crud/update/modify.txt @@ -11,9 +11,16 @@ Modify Documents .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, node.js, modify data + Overview -------- @@ -30,6 +37,8 @@ The {+driver-short+} provides the following methods to change documents: - ``updateMany()`` - ``replaceOne()`` +To learn how to replace documents, see the :ref:`` guide. + .. tip:: Interactive Lab This page includes a short interactive lab that demonstrates how to @@ -143,89 +152,91 @@ You cannot modify the ``_id`` field of a document nor change a field to a value that violates a unique index constraint. See the {+mdb-server+} manual for more information on :manual:`unique indexes `. -.. _node-fundamentals-replaceone: -.. _replacementDocument: +.. _node-usage-updateone: -Replace a Document ------------------- +updateOne() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To perform a replacement operation, create a **replacement document** that -consists of the fields and values that you want to use in your -**replace** operation. Replacement documents use the following format: +.. include:: /includes/crud/example-intro.rst -.. code-block:: javascript +This example uses the ``$set`` update operator which specifies +update values for document fields. For more information on update operators, +see the :manual:`MongoDB update operator reference documentation +`. - { - : { - - }, - : { - ... - } - } +The following code is a complete, standalone file that performs an update one +operation: -Replacement documents are the documents that you want to take the place of -existing documents that match the query filters. +.. tabs:: -Example -~~~~~~~ + .. tab:: JavaScript + :tabid: javascript -Consider a document in the ``myDB.items`` collection with fields -describing an item for sale, its price, and the quantity available: + .. literalinclude:: /code-snippets/usage-examples/updateOne.js + :language: javascript + :linenos: -.. code-block:: javascript + .. tab:: TypeScript + :tabid: typescript - { - _id: 501, - item: "3-wick beeswax candle", - price: 18.99, - quantity: 10, - } + .. literalinclude:: /code-snippets/usage-examples/updateOne.ts + :language: typescript + :linenos: -Suppose you wanted to replace this document with one that contains a -description for an entirely different item. Your replacement operation might -resemble the following: +Running the preceding example results in the following output: -.. code-block:: javascript +.. code-block:: none + :copyable: false - const myDB = client.db("myDB"); - const myColl = myDB.collection("items"); + 1 document(s) matched the filter, updated 1 document(s) - const filter = { _id: 501 }; +.. _node-usage-updatemany: - // replace the matched document with the replacement document - const replacementDocument = { - item: "Vintage silver flatware set", - price: 79.15, - quantity: 1, - }; - const result = await myColl.replaceOne(filter, replacementDocument); +updateMany() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The replaced document contains the contents of the replacement document -and the immutable ``_id`` field as follows: +.. include:: /includes/crud/example-intro.rst -.. code-block:: javascript - :copyable: false +The following code is a complete, standalone file that performs an update many +operation: - { - _id: 501, - item: "Vintage silver flatware set", - price: 79.15, - quantity: 1, - } +.. tabs:: -If a replace operation fails to match any documents in a collection, it -does not make any changes. Replace operations can be configured to perform -an :doc:`upsert ` which -attempts to perform the replacement, but if no documents are matched, it -inserts a new document with the specified fields and values. + .. tab:: JavaScript + :tabid: javascript -You cannot modify the ``_id`` field of a document nor change a field to -a value that violates a unique index constraint. See the {+mdb-server+} manual -for more information on :manual:`unique indexes `. + .. literalinclude:: /code-snippets/usage-examples/updateMany.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/updateMany.ts + :language: typescript + :linenos: + +Running the preceding example, you see an output like the following: + +.. code-block:: none + :copyable: false + + Updated 477 documents .. _node-update-instruqt-lab: .. instruqt:: /mongodb-docs/tracks/update-node?token=em_FEr9KfMh4WQ0VosU :title: updateMany() Lesson - :drawer: \ No newline at end of file + :drawer: + +API Documentation +----------------- + +To learn more about any of the types or methods discussed in this guide, see the +following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `updateOne() <{+api+}/classes/Collection.html#updateOne>`__ +- `updateMany() <{+api+}/classes/Collection.html#updateMany>`__ \ No newline at end of file diff --git a/source/crud/update/replace.txt b/source/crud/update/replace.txt index 741b2a854..2099e331d 100644 --- a/source/crud/update/replace.txt +++ b/source/crud/update/replace.txt @@ -4,6 +4,12 @@ Replace Documents ================= +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + .. facet:: :name: genre :values: reference @@ -18,4 +24,146 @@ In this guide, you can learn how to use {+driver-short+} to perform a replace operation on a document in a MongoDB collection. A replace operation performs differently than an update operation. An update operation modifies only the specified fields in a target document. A replace operation removes *all* fields -in the target document and replaces them with new ones. \ No newline at end of file +in the target document and replaces them with new ones. + +.. _node-fundamentals-replaceone: +.. _replacementDocument: + +Replace a Document +------------------ + +To perform a replacement operation, create a **replacement document** that +consists of the fields and values that you want to use in your +**replace** operation. Replacement documents use the following format: + +.. code-block:: javascript + + { + : { + + }, + : { + ... + } + } + +Replacement documents are the documents that you want to take the place of +existing documents that match the query filters. + +You can specify more options, such as ``upsert``, using the +optional ``options`` parameter. If you set the ``upsert`` option field to +``true`` the method inserts a new document if no document matches the query. + +The ``replaceOne()`` method throws an exception if an error occurs +during execution. For example, if you specify a value that violates a +unique index rule, ``replaceOne()`` throws a ``duplicate key error``. + +.. note:: + + If your application requires the document after updating, + use the `collection.findOneAndReplace() <{+api+}/classes/Collection.html#findOneAndReplace>`__ + method which has a similar interface to ``replaceOne()``. + You can configure ``findOneAndReplace()`` to return either the + original matched document or the replacement document. + +Example +~~~~~~~ + +Consider a document in the ``myDB.items`` collection with fields +describing an item for sale, its price, and the quantity available: + +.. code-block:: javascript + + { + _id: 501, + item: "3-wick beeswax candle", + price: 18.99, + quantity: 10, + } + +Suppose you wanted to replace this document with one that contains a +description for an entirely different item. Your replacement operation might +resemble the following: + +.. code-block:: javascript + + const myDB = client.db("myDB"); + const myColl = myDB.collection("items"); + + const filter = { _id: 501 }; + + // replace the matched document with the replacement document + const replacementDocument = { + item: "Vintage silver flatware set", + price: 79.15, + quantity: 1, + }; + const result = await myColl.replaceOne(filter, replacementDocument); + +The replaced document contains the contents of the replacement document +and the immutable ``_id`` field as follows: + +.. code-block:: javascript + :copyable: false + + { + _id: 501, + item: "Vintage silver flatware set", + price: 79.15, + quantity: 1, + } + +If a replace operation fails to match any documents in a collection, it +does not make any changes. Replace operations can be configured to perform +an :ref:`upsert ` which +attempts to perform the replacement, but if no documents are matched, it +inserts a new document with the specified fields and values. + +You cannot modify the ``_id`` field of a document nor change a field to +a value that violates a unique index constraint. See the {+mdb-server+} manual +for more information on :manual:`unique indexes `. + +.. _node-usage-replaceone: + +replaceOne() Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/crud/example-intro.rst + +The following code is a complete, standalone file that performs a replace one +operation: + +.. tabs:: + + .. tab:: JavaScript + :tabid: javascript + + .. literalinclude:: /code-snippets/usage-examples/replaceOne.js + :language: javascript + :linenos: + + .. tab:: TypeScript + :tabid: typescript + + .. literalinclude:: /code-snippets/usage-examples/replaceOne.ts + :language: typescript + :linenos: + +Running the preceding example results in the following output: + +.. code-block:: none + :copyable: false + + Modified 1 document(s) + +API Documentation +----------------- + +To learn more about any of the types or methods discussed in this guide, see the +following API documentation: + +- `MongoClient <{+api+}/classes/MongoClient.html>`__ +- `Db <{+api+}/classes/Db.html>`__ +- `Collection <{+api+}/classes/Collection.html>`__ +- `replaceOne() <{+api+}/classes/Collection.html#replaceOne>`__ +- `findOneAndReplace() <{+api+}/classes/Collection.html#findOneAndReplace>`__ \ No newline at end of file diff --git a/source/includes/connect-guide-note.rst b/source/includes/connect-guide-note.rst index c69db80d1..6e7817314 100644 --- a/source/includes/connect-guide-note.rst +++ b/source/includes/connect-guide-note.rst @@ -2,5 +2,4 @@ You can use this example to connect to an instance of MongoDB and interact with a database that contains sample data. To learn more about connecting to your MongoDB - instance and loading a sample dataset, see the :doc:`Usage Examples - guide `. + instance and loading a sample dataset, see the :ref:`node-get-started` guide. diff --git a/source/includes/crud/example-identical-code.rst b/source/includes/crud/example-identical-code.rst new file mode 100644 index 000000000..028615e0e --- /dev/null +++ b/source/includes/crud/example-identical-code.rst @@ -0,0 +1,4 @@ +.. note:: No TypeScript Specific Features + + The following code example uses JavaScript. There are no TypeScript + specific features of the driver relevant to this use case. \ No newline at end of file diff --git a/source/includes/crud/example-intro.rst b/source/includes/crud/example-intro.rst new file mode 100644 index 000000000..a99b9750c --- /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:`node-connect` 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 diff --git a/source/monitoring-and-logging/change-streams.txt b/source/monitoring-and-logging/change-streams.txt index b03d55bc5..8aa294c0e 100644 --- a/source/monitoring-and-logging/change-streams.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -1,4 +1,3 @@ -.. _node-usage-watch: .. _node-change-streams: ================================ @@ -117,37 +116,24 @@ read events from the change stream: .. include:: /includes/changestream-paradigm-warning.rst +.. _node-usage-watch: + Examples -------- Iteration ~~~~~~~~~ -The following example opens a change stream on the ``haikus`` collection in -the ``insertDB`` database and prints change events as they occur: - .. include:: /includes/connect-guide-note.rst -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/changeStream.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript +.. include:: /includes/crud/example-identical-code.rst - .. literalinclude:: /code-snippets/usage-examples/changeStream.js - :language: javascript - :linenos: - -.. note:: Identical Code Snippets +The following example opens a change stream on the ``haikus`` collection in +the ``insertDB`` database and prints change events as they occur: - The JavaScript and TypeScript code snippets above are identical. There are no - TypeScript specific features of the driver relevant to this use case. +.. literalinclude:: /code-snippets/usage-examples/changeStream.js + :language: javascript + :linenos: When you run this code and then make a change to the ``haikus`` collection, such as performing an insert or delete operation, you can @@ -219,26 +205,11 @@ closing the ``ChangeStream`` instance using the ``close()`` method. the listener and have the listener process the change event before exiting. -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/changeStream_listener.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/changeStream_listener.js - :language: javascript - :linenos: - -.. note:: Identical Code Snippets +.. include:: /includes/crud/example-identical-code.rst - The JavaScript and TypeScript code snippets above are identical. There are no - TypeScript specific features of the driver relevant to this use case. +.. literalinclude:: /code-snippets/usage-examples/changeStream_listener.js + :language: javascript + :linenos: Visit the following resources for more material on the classes and methods mentioned on this page: diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index 31e8c0454..3cb3474b0 100644 --- a/source/reference/release-notes.txt +++ b/source/reference/release-notes.txt @@ -763,7 +763,7 @@ The {+driver-short+} v6.0 release includes the following features: Although you cannot pass these options to the ``Db.command()`` method, you can still set them in the command document. To learn more, see the :ref:`Command Options - ` section of the Run a Command guide. + ` section of the Run a Database Command guide. To learn more about this release, see the `v6.0.0 Release Highlights `__. diff --git a/source/run-command.txt b/source/run-command.txt index 4027e6700..322c224ba 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -1,8 +1,8 @@ .. _node-run-command: -============== -Run a Command -============== +====================== +Run a Database Command +====================== .. meta:: :description: Learn how to execute database commands using the MongoDB Node.js Driver, including options and response handling. @@ -13,6 +13,14 @@ Run a Command :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: database, call, admin, administration, meta, backend, configure + :description: Learn about how to run database commands in the {+driver-long+}. + Overview -------- @@ -204,6 +212,34 @@ describe any metadata inconsistencies in the database: command result documents when you access the contents of the cursor. You won't see the ``ok``, ``operationTime``, and ``$clusterTime`` fields. +.. _node-run-command-usageex: + +Run Command Example: Full File +------------------------------ + +.. include:: /includes/crud/example-intro.rst + +.. include:: /includes/crud/example-identical-code.rst + +In the following sample code, we send the ``dbStats`` command to request +statistics from the ``sample_mflix`` database: + +.. literalinclude:: /code-snippets/usage-examples/command.js + :language: javascript + :linenos: + +Running the preceding command results in the following output: + +.. code-block:: javascript + :copyable: false + + { + db: 'sample_mflix', + collections: 6, + views: 0, + objects: 75620, + .. + .. _addl-info-runcommand: Additional Information diff --git a/source/typescript.txt b/source/typescript.txt index e40f58b0b..de1ee0cdc 100644 --- a/source/typescript.txt +++ b/source/typescript.txt @@ -94,8 +94,9 @@ The following classes accept all type parameters: - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ You can find a code snippet that shows how to specify a type for the ``FindCursor`` -class in the -:ref:`Find Multiple Documents Usage Example `. +class in the :ref:`find() Example: Full File +` section of the :ref:`node-find` +guide. .. _node-ts-type-safety: diff --git a/source/usage-examples.txt b/source/usage-examples.txt deleted file mode 100644 index f3c6d6e6b..000000000 --- a/source/usage-examples.txt +++ /dev/null @@ -1,130 +0,0 @@ -.. _node-usage-examples: - -============== -Usage Examples -============== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :description: Learn how to load sample data into a MongoDB Atlas deployment and run Node.js driver usage examples. - :keywords: node.js - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. toctree:: - - Find - Insert - Update & Replace - Delete - Count Documents - Distinct Field Values - Run a Command - Watch for Changes - Bulk Operations - Perform a Transaction - -Overview --------- - -Usage examples provide convenient starting points for popular MongoDB -operations. Each example provides the following information: - -- Explanation of the operation in the example, including the - purpose and a sample use case for the method - -- Explanation of how to use the operation, including parameters, - return values, and common exceptions you might encounter - -- Full Node.js program that you can copy and paste to run the example - in your own environment - -How to Use the Usage Examples ------------------------------ - -These examples use the -:atlas:`MongoDB Atlas sample data ` -database. You can use this sample data on the free tier -of MongoDB Atlas by following the :atlas:`Get Started with Atlas -` guide or you -can :guides:`import the sample dataset into a local MongoDB instance -`. - -Once you have imported the dataset, you can copy and paste a usage -example into your development environment of choice. You can follow the -:doc:`get started guide ` to learn more about getting -started with Node.js, npm, and the Node.js driver. Once you've copied -a usage example, you must edit one line to get the example running -with your instance of MongoDB: - -.. code-block:: javascript - - // Replace the following with your MongoDB deployment's connection string. - const uri = - "mongodb+srv://:@?retryWrites=true&writeConcern=majority"; - -All examples use ES module imports. You can -`enable ES module imports `__ -by adding the following key-value pair to your package.json file: - -.. code-block:: json - - "type": "module" - -.. note:: CommonJS - - You can use any usage example with CommonJS ``require``. To use CommonJS ``require``, you - must swap out the ES module ``import`` statement for your CommonJS ``require`` - statement. - - Click on the tabs to see the syntax for importing the driver with ES module - ``import`` and CommonJS ``require``: - - .. tabs:: - - .. tab:: ES Module - :tabid: es-module - - .. code-block:: javascript - - import { MongoClient } from 'mongodb' - - .. tab:: CommonJS Module - :tabid: commonjs-module - - .. code-block:: javascript - - const { MongoClient } = require('mongodb') - -You can use the :guides:`Atlas Connectivity Guide -` to enable connectivity to your instance of -Atlas and find the :manual:`connection string -` to replace the ``uri`` variable in the -usage example. If your instance uses :manual:`SCRAM authentication -`, you can replace ```` with your username, -```` with your password, and ```` with the IP -address or URL of your instance. Consult the -:doc:`Connection Guide ` for more information -about getting connected to your MongoDB instance. - -Available Usage Examples ------------------------- - -- :doc:`Find Operations ` -- :doc:`Insert Operations ` -- :doc:`Update Operations ` -- :doc:`Delete Operations ` -- :doc:`Retrieve Distinct Values of a Field ` -- :doc:`Run a Command ` -- :doc:`Perform Bulk Operations ` -- :doc:`Perform a Transaction ` - -.. - :doc:`Count Documents ` -.. - :doc:`Watch for Changes ` diff --git a/source/usage-examples/bulkWrite.txt b/source/usage-examples/bulkWrite.txt deleted file mode 100644 index 07f6a9089..000000000 --- a/source/usage-examples/bulkWrite.txt +++ /dev/null @@ -1,101 +0,0 @@ -.. _node-usage-bulk: - -======================= -Perform Bulk Operations -======================= - -.. meta:: - :description: Perform batch write operations using the bulkWrite() method in the MongoDB Node.js Driver to increase throughput and performance by reducing network round trips. - -.. default-domain:: mongodb - -The ``bulkWrite()`` method performs batch write operations against a -*single* collection. This method reduces the number of network round trips from -your application to the server which therefore increases the throughput and -performance. Bulk writes return a collection of results for all operations -only after *all* operations passed to the method complete. - -You can specify one or more of the following write operations in -``bulkWrite()``: - -- ``insertOne`` -- ``updateOne`` -- ``updateMany`` -- ``deleteOne`` -- ``deleteMany`` -- ``replaceOne`` - -The ``bulkWrite()`` method accepts the following parameters: - -- ``operations``: specifies the bulk write operations to - perform. Pass each operation to ``bulkWrite()`` as an object in - an array. For examples that show the syntax for each write operation, see - the `bulkWrite API documentation <{+api+}/classes/Collection.html#bulkWrite>`__. - -- ``options``: *optional* settings that affect the execution - of the operation, such as whether the write operations executes in - sequential order and the write concern. - - By default, MongoDB executes bulk write operations one-by-one in the specified order - (serially). During an ordered bulk write, if an error occurs during the processing of an - operation, MongoDB returns without processing the remaining operations in the list. In - contrast, when ``ordered`` is ``false``, MongoDB continues to process remaining write - operations in the list. Unordered operations are theoretically faster since MongoDB can - execute them in parallel, but only use them if the writes do not depend on order. - -If you create an index with a :manual:`unique index ` -constraint, you might encounter a duplicate key write error during an -operation in the following format: - -.. code-block:: sh - - Error during bulkWrite, BulkWriteError: E11000 duplicate key error collection: ... - -Similarly, if you attempt to perform a bulk write against a collection -that uses :manual:`schema validation `, you may -encounter warnings or errors related to the formatting of inserted or -modified documents. - -Example -------- - -The following code sample performs a bulk write operation on the -``theaters`` collection in the ``sample_mflix`` database. The example call -to ``bulkWrite()`` includes examples of ``insertOne``, ``updateMany``, and -``deleteOne`` write operations: - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/bulkWrite.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/bulkWrite.ts - :language: typescript - :linenos: - -Running the preceding example results in the following output: - -.. code-block:: javascript - :copyable: false - - BulkWriteResult { - insertedCount: 2, - matchedCount: 1, - modifiedCount: 1, - deletedCount: 0, - upsertedCount: 0, - upsertedIds: {}, - insertedIds: { - '0': new ObjectId("..."), - '1': new ObjectId("...") - } - } diff --git a/source/usage-examples/command.txt b/source/usage-examples/command.txt deleted file mode 100644 index 971fe227d..000000000 --- a/source/usage-examples/command.txt +++ /dev/null @@ -1,71 +0,0 @@ -.. _node-run-command-usageex: - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: code example, multiple, modify, customize, debug - :description: Execute database commands using the command() method on a database instance with the MongoDB Node.js Driver. - -===================== -Run a Command Example -===================== - -You can execute database commands by using the -`command() <{+api+}/classes/Db.html#command>`__ method on a ``Db`` -instance. - -You can specify a command and options in a document. To run the -command, pass this document to the ``command()`` method. To see a full -list of database commands, see :manual:`Database Commands -` in the Server manual. - -.. tip:: - - Use the :mongosh:`MongoDB Shell ` for administrative tasks instead of - the {+driver-short+} whenever possible. - -You can specify optional command behavior by passing a -``RunCommandOptions`` object to the ``command()`` method. To learn more -about the supported options, see the -`Db.command() API documentation <{+api+}/classes/Db.html#command>`__. - -Example -------- - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/command.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/command.js - :language: javascript - :linenos: - -.. note:: Identical Code Snippets - - The JavaScript and TypeScript code snippets above are identical. There are no - TypeScript specific features of the driver relevant to this use case. - -Running the preceding command, you see the following output: - -.. code-block:: javascript - :copyable: false - - { - db: 'sample_mflix', - collections: 6, - views: 0, - objects: 75620, - ... - } diff --git a/source/usage-examples/delete-operations.txt b/source/usage-examples/delete-operations.txt deleted file mode 100644 index 663fbbc68..000000000 --- a/source/usage-examples/delete-operations.txt +++ /dev/null @@ -1,18 +0,0 @@ -================= -Delete Operations -================= - -.. meta:: - :description: Explore examples of deleting single or multiple documents using the MongoDB Node.js Driver. - -.. default-domain:: mongodb - -.. toctree:: - :caption: Examples - - Delete a Document - Delete Multiple Documents - -- :doc:`Delete a Document ` - -- :doc:`Delete Multiple Documents ` diff --git a/source/usage-examples/deleteMany.txt b/source/usage-examples/deleteMany.txt deleted file mode 100644 index 761307040..000000000 --- a/source/usage-examples/deleteMany.txt +++ /dev/null @@ -1,65 +0,0 @@ -.. _node-usage-deletemany: - -========================= -Delete Multiple Documents -========================= - -.. meta:: - :description: Delete multiple document in a collection with the MongoDB Node.js Driver by using the deleteMany() method with a query to specify which documents to remove. - -.. default-domain:: mongodb - -You can delete multiple documents in a collection at once using the -`collection.deleteMany() <{+api+}/classes/Collection.html#deleteMany>`__ method. -Pass a query document to the ``deleteMany()`` method to specify a subset -of documents in the collection to delete. If you do not provide a query -document (or if you provide an empty document), MongoDB matches all documents -in the collection and deletes them. While you can use ``deleteMany()`` -to delete all documents in a collection, consider using -`drop() <{+api+}/classes/Collection.html#drop>`__ instead for better performance -and clearer code. - -You can specify more options in the ``options`` object passed in -the second parameter of the ``deleteMany()`` method. For more detailed -information, see the -`deleteMany() API documentation <{+api+}/classes/Collection.html#deleteMany>`__. - -Example -------- - -The following snippet deletes multiple documents from the ``movies`` -collection. It uses a **query document** that configures the query to -match and delete movies with the title "Santa Claus". - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/deleteMany.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/deleteMany.ts - :language: typescript - :linenos: - -Running the preceding example for the first time, you see the following output: - -.. code-block:: none - :copyable: false - - Deleted 19 documents - -If you run the example more than once, you see the following output because -you deleted the matching documents in the first run: - -.. code-block:: none - :copyable: false - - Deleted 0 documents diff --git a/source/usage-examples/deleteOne.txt b/source/usage-examples/deleteOne.txt deleted file mode 100644 index 693766a1a..000000000 --- a/source/usage-examples/deleteOne.txt +++ /dev/null @@ -1,77 +0,0 @@ -.. _node-usage-deleteone: - -================= -Delete a Document -================= - -.. meta:: - :description: Delete a single document from a collection with the MongoDB Node.js Driver by using the deleteOne() method with a query to match the document. - -.. default-domain:: mongodb - -You can delete a single document in a collection with -``collection.deleteOne()``. -The ``deleteOne()`` method uses a query document that you provide -to match the subset of the documents in the collection that match -the query. If you do not provide a query document (or if you provide an -empty document), MongoDB matches all documents in the collection and -deletes the first match. - -You can specify more query options using the -``options`` object passed as the second parameter of the -``deleteOne`` method. For more information on this method, -see the -`deleteOne() API documentation <{+api+}/classes/Collection.html#deleteOne>`__. - -.. note:: - - If your application requires the deleted document after deletion, - consider using the - `collection.findOneAndDelete() <{+api+}/classes/Collection.html#findOneAndDelete>`__ - method, which has a similar interface to ``deleteOne()`` but also - returns the deleted document. - -Example -------- - -The following snippet deletes a single document from the ``movies`` -collection. It uses a **query document** that configures the query -to match movies with a ``title`` value of "Annie Hall". - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/deleteOne.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/deleteOne.js - :language: javascript - :linenos: - -.. note:: Identical Code Snippets - - The JavaScript and TypeScript code snippets above are identical. There are no - TypeScript specific features of the driver relevant to this use case. - -Running the preceding example, you see the following output: - -.. code-block:: none - :copyable: false - - Successfully deleted one document. - -If you run the example more than once, you see the following output because -you deleted the matching document in the first run: - -.. code-block:: none - :copyable: false - - No documents matched the query. Deleted 0 documents. diff --git a/source/usage-examples/distinct.txt b/source/usage-examples/distinct.txt deleted file mode 100644 index 428760081..000000000 --- a/source/usage-examples/distinct.txt +++ /dev/null @@ -1,80 +0,0 @@ -.. _node-usage-distinct: - -=================================== -Retrieve Distinct Values of a Field -=================================== - -.. meta:: - :description: Retrieve distinct values of a field in a collection using the distinct() method in the MongoDB Node.js Driver, with examples in JavaScript and TypeScript. - -.. default-domain:: mongodb - -You can retrieve a list of distinct values for a field across a collection by using -the `collection.distinct() <{+api+}/classes/Collection.html#distinct>`__ -method. Call the ``distinct()`` method on a ``Collection`` object with a document -field name parameter as a ``String`` to produce a list that contains one of each -of the different values found in the specified document field as shown below: - -.. code-block:: javascript - - const distinctValues = myColl.distinct("countries", query); - -You can specify a document field within an *embedded document* using -:manual:`dot notation `. If you call -``distinct()`` on an document field that contains an array, the method -treats each element as a separate value. See the following example of -a method call to the ``wins`` field in the ``awards`` subdocument: - -.. code-block:: javascript - - const distinctValues = myColl.distinct("awards.wins", query); - -You can specify more query options using the ``options`` object passed -as the third parameter to the ``distinct()`` method. For details on the -query parameters, see the -`distinct() method in the API documentation <{+api+}/classes/Collection.html#distinct>`__. - -If you specify a value for the document field name that is not of type -``String`` such as a ``Document``, ``Array``, ``Number``, or ``null``, -the method does not execute and returns a ``TypeMismatch`` error with a -message that resembles the following: - -.. blockquote:: - - "key" had the wrong type. Expected string, found - -Visit :ref:`node-fundamentals-distinct` for more information about the ``distinct()`` -method. - -Example -------- - -The following snippet retrieves a list of distinct values for the ``year`` -document field from the ``movies`` collection. It uses a query document to -match movies that include "Barbara Streisand" as a ``director``. - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/distinct.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/distinct.ts - :language: typescript - :linenos: - -Running the preceding example, you see the following output: - -.. code-block:: json - :copyable: false - - [ 1983, 1991, 1996 ] - diff --git a/source/usage-examples/find-operations.txt b/source/usage-examples/find-operations.txt deleted file mode 100644 index ca37cc69c..000000000 --- a/source/usage-examples/find-operations.txt +++ /dev/null @@ -1,16 +0,0 @@ -=============== -Find Operations -=============== - -.. meta:: - :description: Learn by example: how to create queries and retrieve data from MongoDB by using the {+driver-long+}. - -.. toctree:: - :caption: Examples - - Find a Document - Find Multiple Documents - -- :doc:`Find a Document ` - -- :doc:`Find Multiple Documents ` diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt deleted file mode 100644 index e88bbb51c..000000000 --- a/source/usage-examples/find.txt +++ /dev/null @@ -1,108 +0,0 @@ -.. _node-usage-find: - -======================= -Find Multiple Documents -======================= - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :description: Learn how to retrieve multiple documents from MongoDB by using the Node.js driver. - :keywords: code example, node.js, sample dataset - -You can query for multiple documents in a collection with -``collection.find()``. The ``find()`` method uses a query document that you -provide to match the subset of the documents in the collection that match the -query. If you don't provide a query document (or if you provide an empty -document), MongoDB returns all documents in the collection. For more -information on querying MongoDB, see our -:doc:`documentation on query documents `. - -You can also define more query options such as -:doc:`sort ` -and -:doc:`projection ` -to configure the result set. You can specify these in the options -parameter in your ``find()`` method call in ``sort`` and ``projection`` -objects. See `collection.find() <{+api+}/classes/Collection.html#find>`__ for more -information on the parameters you can pass to the method. - -The ``find()`` method returns a `FindCursor <{+api+}/classes/FindCursor.html>`__ that -manages the results of your query. You can iterate through the matching -documents using the ``for await...of`` syntax, or one of the following -:ref:`cursor methods `: - -- ``next()`` -- ``toArray()`` - -If no documents match the query, ``find()`` returns an empty cursor. - -Compatibility -------------- - -.. |page-topic| replace:: use the ``find()`` method -.. |link-topic-ing| replace:: finding documents in the Atlas UI - -.. |atlas-url| replace:: :atlas:`Create, View, Update, and Delete Documents ` - -.. include:: /includes/fact-atlas-compatible.rst -.. include:: /includes/fact-atlas-link.rst - -Example -------- - -The following snippet finds documents from the ``movies`` collection. It -uses the following parameters: - -- A **query document** that configures the query to return only - movies with a runtime of less than 15 minutes. - -- A **sort** that organizes returned documents in ascending order by - title (alphabetical order in which "A" comes before "Z" and "1" before - "9"). - -- A **projection** that explicitly excludes the ``_id`` field from - returned documents and explicitly includes only the ``title`` and - ``imdb`` object (and its embedded fields). - -.. include:: /includes/connect-guide-note.rst - -.. _node-driver-find-usage-example-code-snippet: - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/find.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/find.ts - :language: typescript - :linenos: - -Running the preceding example, you see the following output: - -.. code-block:: javascript - :copyable: false - - { title: '10 Minutes', imdb: { rating: 7.9, votes: 743, id: 339976 } } - { title: '3x3', imdb: { rating: 6.9, votes: 206, id: 1654725 } } - { title: '7:35 in the Morning', imdb: { rating: 7.3, votes: 1555, id: 406501 } } - { title: '8', imdb: { rating: 7.8, votes: 883, id: 1592502 } } - ... - -The ``sort`` and ``projection`` options can also be specified as methods -(``sort()`` and ``project()``) chained to the ``find()`` method. -The following two commands are equivalent: - -.. code-block:: javascript - - movies.find({ runtime: { $lt: 15 } }, { sort: { title: 1 }, projection: { _id: 0, title: 1, imdb: 1 }}); - movies.find({ runtime: { $lt: 15 } }).sort({ title: 1}).project({ _id: 0, title: 1, imdb: 1 }); diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt deleted file mode 100644 index 94e674155..000000000 --- a/source/usage-examples/findOne.txt +++ /dev/null @@ -1,87 +0,0 @@ -.. _node-usage-findone: - -=============== -Find a Document -=============== - -.. default-domain:: mongodb - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :description: Learn how to retrieve one document from MongoDB by using the Node.js driver. - :keywords: code example, node.js, sample dataset - -You can query for a single document in a collection with the -``collection.findOne()`` method. The ``findOne()`` method uses a query -document that you provide to match only the subset of the documents in the -collection that match the query. If you don't provide a query document or if -you provide an empty document, MongoDB matches all documents in the -collection. The ``findOne()`` operation only returns the first matched -document. For more information on querying MongoDB, see our -:doc:`documentation on query documents `. - -You can also define more query options such as -:doc:`sort ` -and :doc:`projection ` -to configure the returned document. You can specify the more options -in the ``options`` object passed as the second parameter of the -``findOne`` method. For detailed reference documentation, see -`collection.findOne() <{+api+}/classes/Collection.html#findOne>`__. - -Compatibility -------------- - -.. |page-topic| replace:: use the ``findOne()`` method -.. |link-topic-ing| replace:: finding documents in the Atlas UI - -.. |atlas-url| replace:: :atlas:`Create, View, Update, and Delete Documents ` - -.. include:: /includes/fact-atlas-compatible.rst -.. include:: /includes/fact-atlas-link.rst - -Example -------- - -The following snippet finds a single document from the ``movies`` -collection. It uses the following parameters: - -- A **query document** that configures the query to return only - movies with the title of exactly the text ``'The Room'``. - -- A **sort** that organizes matched documents in descending order by - rating, so if our query matches multiple documents the returned - document will be the document with the highest rating. - -- A **projection** that explicitly excludes the ``_id`` field from - returned documents and explicitly includes only the ``title`` and - ``imdb`` object (and its embedded fields). - -.. include:: /includes/connect-guide-note.rst - -.. _node-driver-findone-usage-example-code-snippet: - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/findOne.js - :language: javascript - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/findOne.ts - :language: typescript - - -Running the preceding example, you see the following output: - -.. code-block:: javascript - :copyable: false - - { title: 'The Room', imdb: { rating: 3.5, votes: 25673, id: 368226 } } - diff --git a/source/usage-examples/insert-operations.txt b/source/usage-examples/insert-operations.txt deleted file mode 100644 index e32ff60eb..000000000 --- a/source/usage-examples/insert-operations.txt +++ /dev/null @@ -1,16 +0,0 @@ -================= -Insert Operations -================= - -.. meta:: - :description: Learn by example: how to insert data into MongoDB by using the {+driver-long+}. - -.. toctree:: - :caption: Examples - - Insert a Document - Insert Multiple Documents - -- :doc:`Insert a Document ` - -- :doc:`Insert Multiple Documents ` diff --git a/source/usage-examples/insertMany.txt b/source/usage-examples/insertMany.txt deleted file mode 100644 index 3b89cfa79..000000000 --- a/source/usage-examples/insertMany.txt +++ /dev/null @@ -1,51 +0,0 @@ -.. _node-usage-insertmany: - -========================= -Insert Multiple Documents -========================= - -.. meta:: - :description: Insert multiple documents into a collection using the insertMany() method in the MongoDB Node.js Driver. - -.. default-domain:: mongodb - -You can insert multiple documents using the -`collection.insertMany() <{+api+}/classes/Collection.html#insertMany>`__ method. The ``insertMany()`` takes an array -of documents to insert into the specified collection. - -You can specify more options in the ``options`` object passed as the -second parameter of the ``insertMany()`` method. Specify ``ordered:true`` -to prevent inserting the remaining documents if the insertion failed for a -previous document in the array. - -Specifying incorrect parameters for your ``insertMany()`` operation can -cause problems. Attempting to insert a field with a value that violates -unique index rules results in a ``duplicate key error``. - -Example -------- - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/insertMany.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/insertMany.ts - :language: typescript - :linenos: - -Running the preceding example, you see the following output: - -.. code-block:: none - :copyable: false - - 3 documents were inserted diff --git a/source/usage-examples/insertOne.txt b/source/usage-examples/insertOne.txt deleted file mode 100644 index 1e473972d..000000000 --- a/source/usage-examples/insertOne.txt +++ /dev/null @@ -1,70 +0,0 @@ -.. _node-usage-insert: - -================= -Insert a Document -================= - -.. default-domain:: mongodb - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :description: Learn how to insert a document into MongoDB by using the Node.js driver. - :keywords: code example, node.js, sample dataset - -You can insert a document into a collection using the -`collection.insertOne() <{+api+}/classes/Collection.html#insertOne>`__ method. To -insert a document, define an object that contains the fields and values that -you want to store. If the specified collection does not exist, the -``insertOne()`` method creates the collection. - -You can specify more query options using the ``options`` parameter. -For more information on the method parameters, see the -`insertOne() API documentation <{+api+}/classes/Collection.html#insertOne>`__. -For more information on this method, see the -`insertOne() API documentation <{+api+}/classes/Collection.html#insertOne>`__. - -If the operation successfully inserts a document, it appends an -``insertedId`` field to the object passed in the method call, and sets the -value of the field to the ``_id`` of the inserted document. - -Compatibility -------------- - -.. |page-topic| replace:: use the ``insertOne()`` method -.. |link-topic-ing| replace:: inserting documents in the Atlas UI - -.. |atlas-url| replace:: :atlas:`Create, View, Update, and Delete Documents ` - -.. include:: /includes/fact-atlas-compatible.rst -.. include:: /includes/fact-atlas-link.rst - -Example -------- - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/insertOne.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/insertOne.ts - :language: typescript - :linenos: - -Running the preceding example, you see the following output: - -.. code-block:: none - :copyable: false - - A document was inserted with the _id: diff --git a/source/usage-examples/replaceOne.txt b/source/usage-examples/replaceOne.txt deleted file mode 100644 index fc6d5ee3b..000000000 --- a/source/usage-examples/replaceOne.txt +++ /dev/null @@ -1,64 +0,0 @@ -.. _node-usage-replaceone: - -================== -Replace a Document -================== - -.. meta:: - :description: Replace a single document in a collection using the replaceOne() method in the MongoDB Node.js Driver, with options for upsert and error handling. - -.. default-domain:: mongodb - -You can replace a single document using the -`collection.replaceOne() <{+api+}/classes/Collection.html#replaceOne>`__ method. -``replaceOne()`` accepts a query document and a replacement document. If -the query matches a document in the collection, it replaces the first -document that matches the query with the provided replacement document. -This operation removes all fields and values in the original document and -replaces them with the fields and values in the replacement document. The -value of the ``_id`` field remains the same unless you explicitly specify -a new value for ``_id`` in the replacement document. - -You can specify more options, such as ``upsert``, using the -optional ``options`` parameter. If you set the ``upsert`` option field to -``true`` the method inserts a new document if no document matches the query. - -The ``replaceOne()`` method throws an exception if an error occurs -during execution. For example, if you specify a value that violates a -unique index rule, ``replaceOne()`` throws a ``duplicate key error``. - -.. note:: - - If your application requires the document after updating, - use the `collection.findOneAndReplace() <{+api+}/classes/Collection.html#findOneAndReplace>`__ - method which has a similar interface to ``replaceOne()``. - You can configure ``findOneAndReplace()`` to return either the - original matched document or the replacement document. - -Example -------- - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/replaceOne.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/replaceOne.ts - :language: typescript - :linenos: - -Running the preceding example, you see the following output: - -.. code-block:: none - :copyable: false - - Modified 1 document(s) diff --git a/source/usage-examples/transactions.txt b/source/usage-examples/transactions.txt deleted file mode 100644 index 79277686f..000000000 --- a/source/usage-examples/transactions.txt +++ /dev/null @@ -1,20 +0,0 @@ -.. _node-usage-txns: - -===================== -Perform a Transaction -===================== - -.. meta:: - :description: Explore how to perform transactions using the MongoDB Node.js Driver with both the Convenient Transaction API and the Core API. - -.. toctree:: - :caption: Transaction Usage Examples - - Convenient Transaction API - Core API - -The following usage examples demonstrate how to perform transactions by -using the transaction APIs in the {+driver-short+}: - -- :ref:`node-usage-convenient-txn` -- :ref:`node-usage-core-txn` \ No newline at end of file diff --git a/source/usage-examples/update-and-replace-operations.txt b/source/usage-examples/update-and-replace-operations.txt deleted file mode 100644 index f60402c98..000000000 --- a/source/usage-examples/update-and-replace-operations.txt +++ /dev/null @@ -1,19 +0,0 @@ -=========================== -Update & Replace Operations -=========================== - -.. meta:: - :description: Learn by example: how to update and replace data in MongoDB by using the {+driver-long+}. - -.. toctree:: - :caption: Examples - - Update a Document - Update Multiple Documents - Replace a Document - -- :doc:`Update a Document ` - -- :doc:`Update Multiple Documents ` - -- :doc:`Replace a Document ` diff --git a/source/usage-examples/updateMany.txt b/source/usage-examples/updateMany.txt deleted file mode 100644 index da6329293..000000000 --- a/source/usage-examples/updateMany.txt +++ /dev/null @@ -1,51 +0,0 @@ -.. _node-usage-updatemany: - -========================= -Update Multiple Documents -========================= - -.. meta:: - :description: Update multiple documents in a collection with the MongoDB Node.js Driver by using the updateMany() method with a filter. - -.. default-domain:: mongodb - -You can update multiple documents using the -`collection.updateMany() <{+api+}/classes/Collection.html#updateMany>`__ method. -The ``updateMany()`` method accepts a filter document and an update document. If the query matches documents in the -collection, the method applies the updates from the update document to fields -and values of the matching documents. The update document requires an :manual:`update operator -` to modify a field in a document. - -You can specify more options in the ``options`` object passed in -the third parameter of the ``updateMany()`` method. For more detailed -information, see -`the updateMany() API documentation <{+api+}/classes/Collection.html#updateMany>`__. - - -Example -------- - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/updateMany.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/updateMany.ts - :language: typescript - :linenos: - -Running the preceding example, you see the following output: - -.. code-block:: none - :copyable: false - - Updated 477 documents diff --git a/source/usage-examples/updateOne.txt b/source/usage-examples/updateOne.txt deleted file mode 100644 index 2034b693c..000000000 --- a/source/usage-examples/updateOne.txt +++ /dev/null @@ -1,73 +0,0 @@ -.. _node-usage-updateone: - -================= -Update a Document -================= - -.. meta:: - :description: Update a single document in a MongoDB collection with the in the MongoDB Node.js Driver by using the updateOne() method with options for upserting and handling exceptions. - -.. default-domain:: mongodb - -You can update a single document using the -`collection.updateOne() <{+api+}/classes/Collection.html#updateOne>`__ -method. The ``updateOne()`` method accepts a filter -document and an update document. If the query matches documents in the -collection, the method applies the updates from the update document to fields -and values of them. The update document contains :manual:`update operators -` that instruct the method -on the changes to make to the matches. - -You can specify more query options using the ``options`` object -passed as the second parameter of the ``updateOne()`` method. -Set the ``upsert`` option to ``true`` to create a new document -if no documents match the filter. For more information, see the -`updateOne() API documentation <{+api+}/classes/Collection.html#updateOne>`__. - -``updateOne()`` throws an exception if an error occurs during execution. -If you specify a value in your update document for the immutable field -``_id``, the method throws an exception. If your update document contains -a value that violates unique index rules, the method throws a ``duplicate -key error`` exception. - -.. note:: - - If your application requires the document after updating, - consider using the - `collection.findOneAndUpdate() <{+api+}/classes/Collection.html#findOneAndUpdate>`__. - method, which has a similar - interface to ``updateOne()`` but also returns the original or updated - document. - -Example -------- - -The following example uses the ``$set`` update operator which specifies -update values for document fields. For more information on update operators, -see the :manual:`MongoDB update operator reference documentation -`. - -.. include:: /includes/connect-guide-note.rst - -.. tabs:: - - .. tab:: JavaScript - :tabid: javascript - - .. literalinclude:: /code-snippets/usage-examples/updateOne.js - :language: javascript - :linenos: - - .. tab:: TypeScript - :tabid: typescript - - .. literalinclude:: /code-snippets/usage-examples/updateOne.ts - :language: typescript - :linenos: - -If you run the example above, you see the following output: - -.. code-block:: none - :copyable: false - - 1 document(s) matched the filter, updated 1 document(s) From 86d22d64f8a7c89cb1226d4f46158e01476f68a6 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Tue, 22 Apr 2025 15:05:25 -0400 Subject: [PATCH 21/26] DOCSP-48389 Connection Troubleshooting Revisions (#1068) * DOCSP-48389 Connection Troubleshooting Revisions * tech question * edits * tech review * edit * remov * technical review * security comment * JS review * edit --- source/connect/connection-troubleshooting.txt | 91 ++++++------------- 1 file changed, 27 insertions(+), 64 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index efa64b9ab..ece0d8487 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -27,36 +27,20 @@ using the {+driver-long+} to connect to a MongoDB deployment. with MongoDB or the driver, visit the following resources: - The :ref:`Issues & Help ` page, which has - information about reporting bugs, contributing to the driver, and - finding more resources + information about how to report bugs, contribute to the driver, and + find more resources - The `MongoDB Community Forums `__ for questions, discussions, or general technical support Connection Error ---------------- -The following error message indicates that the driver cannot connect to a server -on the specified hostname or port. Multiple situations can generate this error -message. In this sample error message, the hostname is ``127.0.0.1`` and the -port is ``27017``: - -.. code-block:: none - :copyable: false - - Error: couldn't connect to server 127.0.0.1:27017 +If the driver cannot connect to the specified host, you might get an +``MongoServerSelectionError``. The following sections describe actions you can take to potentially resolve the issue. -.. _node-troubleshooting-connection-string-port: - -Check Your Connection String -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Verify that the hostname and port number in the connection string are both -accurate. The default port value for a MongoDB instance is -``27017``, but you can configure MongoDB to communicate on another port. - .. _node-troubleshooting-connection-firewall: Configure Your Firewall @@ -65,18 +49,28 @@ Configure Your Firewall Verify that the ports your MongoDB deployment listens on are not blocked by a firewall on the same network. MongoDB uses port ``27017`` by default. To learn more about the default ports MongoDB uses and how to change them, see -:manual:`Default MongoDB Port `. +:manual:`Default MongoDB Port ` in the +{+mdb-server+} manual. .. warning:: Do not open a port in your firewall unless you are sure it's the port used by your MongoDB deployment. +Check Your Network Access List +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Verify that your IP Address is listed in the IP Access List for your cluster. +You can find your IP Access List in the Network Access section of +the Atlas UI. To learn more about how to configure your IP Access List, +see the :atlas:`Configure IP Access List Entries ` +guide in the Atlas documentation. + ECONNREFUSED Error ------------------ If the connection is refused when the driver attempts to connect to the MongoDB -instance, it generates this error message: +instance, it generates an error message similar to the following: .. code-block:: none :copyable: false @@ -86,8 +80,8 @@ instance, it generates this error message: The following sections describe actions you can take to potentially resolve the issue. -Ensure MongoDB and Your Client Use the Same Protocol -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Ensure MongoDB and Your Client Use the Same IP Address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both the client and host support both. For example, if MongoDB uses IPv4 and your @@ -113,7 +107,7 @@ ECONNRESET Error ---------------- If the connection is reset when the driver calls ``client.connect()``, it -generates this error message: +generates an error message similar to the following: .. code-block:: none :copyable: false @@ -134,7 +128,9 @@ if the number of connections exceeds this limit. You can set the maximum number of connections by setting ``maxPoolSize``. To resolve this error, you can decrease the number of maximum allowed connections by setting the value of ``maxPoolSize``. Alternatively, you could increase the -file descriptor limit in your operating system. +file descriptor limit in your operating system. To learn more about how to set +``maxPoolSize``, see the API documentation for +`maxPoolSize <{+api+}/interfaces/MongoClientOptions.html#maxPoolSize>`__ . .. warning:: @@ -151,8 +147,7 @@ error message similar to one of the following messages: .. code-block:: none :copyable: false - Command failed with error 18 (AuthenticationFailed): 'Authentication - failed.' on server :. + MongoServerError: bad auth : authentication failed .. code-block:: none :copyable: false @@ -170,12 +165,13 @@ Check Your Connection String ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An invalid connection string is the most common cause of authentication -issues when attempting to connect to MongoDB using ``SCRAM-SHA-256``. +issues when you attempt to connect to MongoDB by using ``SCRAM-SHA-256``. .. tip:: For more information about connection strings, - see :ref:`Connection URI ` in the Connection Guide. + see the :ref:`Connection URI ` section in the Connection + Guide. If your connection string contains a username and password, ensure that they are in the correct format. If the username or password includes any of the @@ -217,10 +213,6 @@ database: const uri = "mongodb://:@:/?authSource=users"; const client = new MongoClient(uri); -You can check if this is the issue by attempting to connect to a MongoDB -instance hosted on the local machine with the same code. A deployment on -the same machine doesn't require any authorization to connect. - Error Sending Message --------------------- @@ -272,27 +264,6 @@ For more information about how connection pooling works, see the :ref:`Connection Pool Overview ` in the Connection Pools page. -Too Many Open Connections -------------------------- - -The driver creates the following error message when it attempts to open a -connection, but it's reached the maximum number of connections: - -.. code-block:: none - :copyable: false - - connection refused because too many open connections - -The following section describes a method that may help resolve the issue. - -Check the Number of Connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create more open connections, increase the value of ``maxPoolSize``. For more -information about checking the number of connections, see -:ref:`Check the Number of Connections ` -in the Error Sending Message section. - Timeout Error ------------- @@ -314,7 +285,7 @@ Set connectTimeoutMS The driver may hang when it's unable to establish a connection because it takes too long attempting to reach unreachable replica set nodes. You can limit the time the driver spends attempting to establish the connection by using the -``connectTimeMS`` setting. To learn more about this setting, see the +``connectTimeoutMS`` setting. To learn more about this setting, see the :manual:`Timeout Options ` in the Server manual. @@ -332,14 +303,6 @@ The following example sets ``connectTimeoutMS`` to 10000 milliseconds. connectTimeoutMS: 10000, }); -Check the Number of Connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The number of connections to the server may exceed ``maxPoolSize``. For more -information about checking the number of connections, see -:ref:`Check the Number of Connections ` -in the Error Sending Message section. - Client Disconnect While Running Operation ----------------------------------------- From 8966992760957882b8efcac9a7cc820d2fd92be8 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Tue, 22 Apr 2025 15:43:05 -0400 Subject: [PATCH 22/26] DOCSP-48707 Standardize cursor chaining methods (#1073) * DOCSP-48707 Standardize cursor chaining methods * tech review * edits * vale check * remove mention of options object * order comment * RR review --- source/crud/query/count.txt | 2 +- source/crud/query/retrieve.txt | 10 +-- .../query/specify-documents-to-return.txt | 88 ++++--------------- 3 files changed, 24 insertions(+), 76 deletions(-) diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index 1299bb121..a567b281a 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -59,7 +59,7 @@ documentation for each method for more information. .. code-block:: javascript - collection.countDocuments({}, { hint: "_id_" }); + collection.countDocuments({}).hint("_id"); countDocuments() Example: Full File ----------------------------------- diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 8b42501b4..dbdedcd14 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -89,18 +89,16 @@ see the :ref:`node-fundamentals-query-document` guide. to the ``findOne()`` method, the operation returns a single document from a collection. - You can specify options in a find operation even when you pass an + You can chain cursor methods to a find operation even when you pass an empty query. For example, the following code shows how you can - specify a projection as an option while executing a find operation + specify a projection while performing a find operation that receives an empty query parameter: .. code-block:: javascript - const options = { - projection: { _id: 0, field1: 1 }, - }; + const projection = { _id: 0, field1: 1 }; - const findResult = await myColl.findOne({}, options); + const findResult = await myColl.findOne().project(projection); For more information about projecting document fields, see the :ref:`node-fundamentals-project` guide. diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index b1f225c15..08dca2fe2 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -27,15 +27,6 @@ operation by using the following methods: - ``limit()``: Specifies the maximum number of documents to return from a query. - ``skip()``: Specifies the number of documents to skip before returning query results. -You can use these methods either by chaining them to your read operation or by specifying them in an -``options`` object in your call to your read operation. - -.. note:: - - If you chain ``sort()``, ``limit()``, or ``skip()`` to a read operation, you must - specify all methods before iterating the cursor. If you specify a method after - iterating the cursor, the method you specified does not apply to the operation. - Sample Data for Examples ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -56,6 +47,13 @@ that describe books into the ``myDB.books`` collection: { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 }, ]); +.. note:: + + You must chain ``FindCursor`` methods such as ``sort()``, ``limit()``, or + ``skip()`` to a read operation before iterating the cursor. If you specify + a ``FindCursor`` method after iterating the cursor, the setting does not + apply to the operation. + .. include:: /includes/access-cursor-note.rst .. _node-fundamentals-sort: @@ -187,19 +185,6 @@ length: myColl.find(query).sort({ length: -1 }).limit(3); myColl.find(query).limit(3).sort({ length: -1 }); -You can also apply ``sort()`` and ``limit()`` by specifying them in an -``options`` object in your call to the ``find()`` method. The following two -calls are equivalent: - -.. code-block:: javascript - - myColl.find(query).sort({ length: -1 }).limit(3); - myColl.find(query, { sort: { length: -1 }, limit: 3 }); - -For more information on the ``options`` settings for the ``find()`` -method, see the -`API documentation on find() <{+api+}/classes/Collection.html#find>`__. - .. _node-fundamentals-skip: Skip @@ -244,21 +229,6 @@ the fifth and sixth highest length documents: { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } -You can also apply ``skip()`` and ``sort()`` by specifying them in an -``options`` object in your call to the ``find()`` method. The following two -calls are equivalent: - -.. code-block:: javascript - - myColl.find(query).sort({ length: -1 }).skip(4); - myColl.find(query, { sort: { length: -1 }, skip: 4}); - -For more information on the ``options`` settings for the ``find()`` -method, see the -`API documentation on find() <{+api+}/classes/Collection.html#find>`__. - -.. _node-fundamentals-combine-lim-sort-skip: - Combine Limit, Sort, and Skip ----------------------------- @@ -270,43 +240,18 @@ The following example returns documents with the ``length`` value of ``"1104"``. The results are sorted in alphabetical order, skipping the first document and includes only the first result: -.. code-block:: javascript - - // define a query to look for length value of 1104 - const query = {length: "1104"}; - const options = { - // sort in alphabetical (1) order by title - sort : { title: 1 }, - // omit the first document - skip : 1, - // returns only the first result - limit: 1, - } - const cursor = myColl.find(query, options); - for await (const doc of cursor) { - console.dir(doc); - } - -.. code-block:: json - :copyable: false - - { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } - -.. note:: - - The order in which you call these methods doesn't change the documents - that are returned. The driver automatically reorders the calls to perform the - sort and skip operations first, and the limit operation afterward. - -You can also limit, sort, and skip results by chaining each method to the ``find`` method. -The following example specifies the same query as the preceding example: - .. io-code-block:: .. input:: :language: javascript - myColl.find(query).sort({ title: 1 }).skip(1).limit(1); + const query = {length: "1104"}; + + const cursor = myColl.find(query).sort({ title: 1 }).skip(1).limit(1); + + for await (const doc of cursor) { + console.dir(doc); + } .. output:: :language: json @@ -314,6 +259,11 @@ The following example specifies the same query as the preceding example: { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } +.. note:: + + The order in which you call these methods doesn't change the documents + that are returned. + Additional Information ---------------------- From d4c28fc140cea5b2dbaeb7e26b94ee8facbea090 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Wed, 23 Apr 2025 15:38:03 -0400 Subject: [PATCH 23/26] DOCSP-48708 Specify cursor limitations (#1094) * DOCSP-48708 Specify cursor limitations * add chaining method to find * edit * edit find ts example * SA review * change cursor chain const names to be more specific --- source/code-snippets/usage-examples/find.js | 11 +++----- source/code-snippets/usage-examples/find.ts | 11 +++----- source/crud/query/project.txt | 14 +++++----- source/crud/query/retrieve.txt | 13 +++------ .../query/specify-documents-to-return.txt | 27 ++++++++----------- source/includes/crud/chain-cursor-methods.rst | 6 +++++ 6 files changed, 35 insertions(+), 47 deletions(-) create mode 100644 source/includes/crud/chain-cursor-methods.rst diff --git a/source/code-snippets/usage-examples/find.js b/source/code-snippets/usage-examples/find.js index 0486e86d2..4a389c291 100644 --- a/source/code-snippets/usage-examples/find.js +++ b/source/code-snippets/usage-examples/find.js @@ -14,16 +14,11 @@ async function run() { // Query for movies that have a runtime less than 15 minutes const query = { runtime: { $lt: 15 } }; - - const options = { - // Sort returned documents in ascending order by title (A->Z) - sort: { title: 1 }, - // Include only the `title` and `imdb` fields in each returned document - projection: { _id: 0, title: 1, imdb: 1 }, - }; + const sortFields = { title: 1 }; + const projectFields = { _id: 0, title: 1, imdb: 1 }; // Execute query - const cursor = movies.find(query, options); + const cursor = movies.find(query).sort(sortFields).project(projectFields); // Print a message if no documents were found if ((await movies.countDocuments(query)) === 0) { diff --git a/source/code-snippets/usage-examples/find.ts b/source/code-snippets/usage-examples/find.ts index 123c1e2af..efab7839a 100644 --- a/source/code-snippets/usage-examples/find.ts +++ b/source/code-snippets/usage-examples/find.ts @@ -25,13 +25,10 @@ async function run() { const movies = database.collection("movies"); const query = { runtime: { $lt: 15 } }; - const cursor = movies.find( - query, - { - sort: { title: 1 }, - projection: { _id: 0, title: 1, imdb: 1 }, - } - ); + const sortFields = { title: 1 }; + const projectFields = { _id: 0, title: 1, imdb: 1 }; + + const cursor = movies.find(query).sort(sortFields).project(projectFields); if ((await movies.countDocuments(query)) === 0) { console.warn("No documents found!"); diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 1581a8cf1..d63c8a089 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -67,8 +67,8 @@ field of each document: :emphasize-lines: 2 // return only* the name field - const projection = { name: 1 }; - const cursor = myColl.find().project(projection); + const projectFields = { name: 1 }; + const cursor = myColl.find().project(projectFields); for await (const doc of cursor) { console.dir(doc); } @@ -104,8 +104,8 @@ returned documents. :emphasize-lines: 2 // return only the name field - const projection = { _id: 0, name: 1 }; - const cursor = myColl.find().project(projection); + const projectFields = { _id: 0, name: 1 }; + const cursor = myColl.find().project(projectFields); for await (const doc of cursor) { console.dir(doc); } @@ -133,8 +133,8 @@ order in which they are returned. .. code-block:: javascript - const projection = { _id: 0, rating: 1, name: 1 }; - const cursor = myColl.find().project(projection); + const projectFields = { _id: 0, rating: 1, name: 1 }; + const cursor = myColl.find().project(projectFields); for await (const doc of cursor) { console.dir(doc); } @@ -152,3 +152,5 @@ the following results: For more projection examples, see the :manual:`MongoDB Manual page on Project Fields to Return from Query `. + +.. include:: /includes/crud/chain-cursor-methods.rst diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index dbdedcd14..d5f8a22eb 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -96,9 +96,9 @@ see the :ref:`node-fundamentals-query-document` guide. .. code-block:: javascript - const projection = { _id: 0, field1: 1 }; + const projectFields = { _id: 0, field1: 1 }; - const findResult = await myColl.findOne().project(projection); + const findResult = await myColl.findOne().project(projectFields); For more information about projecting document fields, see the :ref:`node-fundamentals-project` guide. @@ -235,14 +235,7 @@ Running the preceding example results in the following output: { title: '8', imdb: { rating: 7.8, votes: 883, id: 1592502 } } ... -You can also specify ``sort`` and ``projection`` options by chaining the -``sort()`` and ``projection`` methods to the ``find()`` method. The following -two commands are equivalent: - -.. code-block:: javascript - - movies.find({ runtime: { $lt: 15 } }, { sort: { title: 1 }, projection: { _id: 0, title: 1, imdb: 1 }}); - movies.find({ runtime: { $lt: 15 } }).sort({ title: 1}).project({ _id: 0, title: 1, imdb: 1 }); +.. include:: /includes/crud/chain-cursor-methods.rst Additional Information ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 08dca2fe2..b4cc4538b 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -47,12 +47,7 @@ that describe books into the ``myDB.books`` collection: { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 }, ]); -.. note:: - - You must chain ``FindCursor`` methods such as ``sort()``, ``limit()``, or - ``skip()`` to a read operation before iterating the cursor. If you specify - a ``FindCursor`` method after iterating the cursor, the setting does not - apply to the operation. +.. include:: /includes/crud/chain-cursor-methods.rst .. include:: /includes/access-cursor-note.rst @@ -79,8 +74,8 @@ lengths: // define an empty query document const query = {}; // sort in descending (-1) order by length - const sort = { length: -1 }; - const cursor = myColl.find(query).sort(sort); + const sortFields = { length: -1 }; + const cursor = myColl.find(query).sort(sortFields); for await (const doc of cursor) { console.dir(doc); } @@ -111,8 +106,8 @@ add more fields to the sort document: // define an empty query document const query = {}; // sort in ascending (1) order by length - const sort = { length: 1, author: 1 }; - const cursor = myColl.find(query).sort(sort); + const sortFields = { length: 1, author: 1 }; + const cursor = myColl.find(query).sort(sortFields); for await (const doc of cursor) { console.dir(doc); } @@ -157,9 +152,9 @@ This example performs the following actions: // define an empty query document const query = {}; // sort in descending (-1) order by length - const sort = { length: -1 }; - const limit = 3; - const cursor = myColl.find(query).sort(sort).limit(limit); + const sortFields = { length: -1 }; + const limitNum = 3; + const cursor = myColl.find(query).sort(sortFields).limit(limitNum); for await (const doc of cursor) { console.dir(doc); } @@ -213,9 +208,9 @@ by performing the following actions: // define an empty query document const query = {}; - const sort = { length: -1 }; - const skip = 4; - const cursor = myColl.find(query).sort(sort).skip(skip); + const sortFields = { length: -1 }; + const skipNum = 4; + const cursor = myColl.find(query).sort(sortFields).skip(skipNum); for await (const doc of cursor) { console.dir(doc); } diff --git a/source/includes/crud/chain-cursor-methods.rst b/source/includes/crud/chain-cursor-methods.rst new file mode 100644 index 000000000..716d03511 --- /dev/null +++ b/source/includes/crud/chain-cursor-methods.rst @@ -0,0 +1,6 @@ +.. note:: + + You must chain a cursor method such as ``sort()``, ``limit()``, + ``skip()``, or ``project()`` to a read operation before iterating the cursor. + If you specify a cursor method after iterating the cursor, the setting does + not apply to the read operation. \ No newline at end of file From b3eafb7e2a86d2d21c00db2c41883b7f15733e2c Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Fri, 25 Apr 2025 13:12:45 -0700 Subject: [PATCH 24/26] DOCSP-48497 Comp cov clean up (#1095) --- config/redirects | 1 + source/archive-reference-files/collations.txt | 317 ------------------ .../quick-start/connect-to-mongodb.txt | 81 ----- .../create-a-connection-string.txt | 63 ---- .../quick-start/create-a-deployment.txt | 32 -- .../quick-start/download-and-install.txt | 65 ---- .../quick-start/facets.toml | 3 - .../quick-start/next-steps.txt | 22 -- source/connect/connection-options.txt | 1 - .../connection-options/server-selection.txt | 21 -- source/crud.txt | 14 +- source/crud/gridfs.txt | 10 +- source/crud/pkFactory.txt | 6 +- source/crud/query.txt | 231 +------------ source/crud/query/count.txt | 6 +- source/crud/update.txt | 2 + source/crud/update/replace.txt | 2 +- source/fundamentals.txt | 29 -- source/fundamentals/bson/undefined-values.txt | 130 ------- source/fundamentals/bson/utf8-validation.txt | 121 ------- .../crud/read-operations/limit.txt | 139 -------- .../crud/read-operations/skip.txt | 95 ------ .../crud/read-operations/sort.txt | 119 ------- source/fundamentals/crud/write-operations.txt | 25 -- source/includes/fundamentals-sections.rst | 20 -- source/index.txt | 5 +- .../monitoring-and-logging/change-streams.txt | 2 +- source/{fundamentals => }/promises.txt | 14 +- source/reference/upgrade.txt | 5 +- source/typescript.txt | 6 +- 30 files changed, 53 insertions(+), 1534 deletions(-) delete mode 100644 source/archive-reference-files/collations.txt delete mode 100644 source/archive-reference-files/quick-start/connect-to-mongodb.txt delete mode 100644 source/archive-reference-files/quick-start/create-a-connection-string.txt delete mode 100644 source/archive-reference-files/quick-start/create-a-deployment.txt delete mode 100644 source/archive-reference-files/quick-start/download-and-install.txt delete mode 100644 source/archive-reference-files/quick-start/facets.toml delete mode 100644 source/archive-reference-files/quick-start/next-steps.txt delete mode 100644 source/connect/connection-options/server-selection.txt delete mode 100644 source/fundamentals.txt delete mode 100644 source/fundamentals/bson/undefined-values.txt delete mode 100644 source/fundamentals/bson/utf8-validation.txt delete mode 100644 source/fundamentals/crud/read-operations/limit.txt delete mode 100644 source/fundamentals/crud/read-operations/skip.txt delete mode 100644 source/fundamentals/crud/read-operations/sort.txt delete mode 100644 source/fundamentals/crud/write-operations.txt delete mode 100644 source/includes/fundamentals-sections.rst rename source/{fundamentals => }/promises.txt (95%) diff --git a/config/redirects b/config/redirects index 23238c3bf..bfcecf4cf 100644 --- a/config/redirects +++ b/config/redirects @@ -85,6 +85,7 @@ raw: ${prefix}/stable -> ${base}/current/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/crud/update/embedded-arrays/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/pkFactory/ -> ${base}/crud/pkFactory/ [*-master]: ${prefix}/${version}/security/authentication/enterprise-mechanisms/ -> ${base}/security/authentication +[*-master]: ${prefix}/${version}/fundamentals/promises/ -> ${base}/promises/ # Usage Example Redirects diff --git a/source/archive-reference-files/collations.txt b/source/archive-reference-files/collations.txt deleted file mode 100644 index dc893b7f5..000000000 --- a/source/archive-reference-files/collations.txt +++ /dev/null @@ -1,317 +0,0 @@ -.. _node-fundamentals-collations: - -========== -Collations -========== - -.. meta:: - :description: Learn how to use collations to apply specific sorting rules for string operations based on language and locale preferences with the MongoDB Node.js Driver. - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -*Collations are available in MongoDB 3.4 and later.* - --------- -Overview --------- - -This guide shows you how to use **collations**, a set of sorting rules, to -run operations using string ordering for specific languages and locales (a -community or region that shares common language idioms). - -MongoDB sorts strings using *binary collation* by default. This collation -method uses the `ASCII standard `_ -character values to compare and order strings. Languages and locales -have specific character ordering conventions that differ from the ASCII -standard. - -For example, in Canadian French, the right-most accented character determines -the ordering for strings when the other characters are the same. Consider the -following French words: **cote**, **coté**, **côte**, and **côté**. - -MongoDB sorts them in the following order using the default binary collation: - -.. code-block:: none - - cote - coté - côte - côté - -MongoDB sorts them in the following order using the Canadian French collation: - -.. code-block:: none - - cote - côte - coté - côté - ------ -Usage ------ - -You can specify a collation when you create a new collection or new index. You -can also specify a collation for :doc:`CRUD operations ` -and aggregations. - -When you create a new collection with a collation, you define the default -collation for any of the :manual:`operations that support collation -` called on that -collection. You can override the collation for an operation by specifying a -different one. - -.. note:: - - Currently, you cannot create a collation on an existing collection. To use - collations with an existing collection, create an index with the collation - and specify the same collation in your operations on it. - -When you create an index with a collation, you specify the sort order for -operations that use that index. To use the collation in the index, you -must provide a matching collation in the operation, and the operation must -use the index. While most index types support collation, the following -types support only binary comparison: - -- :manual:`text ` -- :manual:`2d ` -- :manual:`geoHaystack ` - -Collation Parameters -~~~~~~~~~~~~~~~~~~~~ - -The collation object contains the following parameters: - -.. code-block:: javascript - - collation: { - locale: , - caseLevel: , - caseFirst: , - strength: , - numericOrdering: , - alternate: , - maxVariable: , - backwards: - } - -You must specify the ``locale`` field in the collation; all other fields -are optional. For a complete list of supported locales and the default values -for the ``locale`` fields, see :manual:`Supported Languages and Locales -`. -For descriptions of each field, see the :manual:`Collation Document MongoDB -manual entry `. - ------------------- -Collation Examples ------------------- - -Set a Default Collation on a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the following example, we create a new collection called ``souvenirs`` and -assign a default collation with the ``"fr_CA"`` locale. The collation applies -to all :manual:`operations that support collation -` performed on that -collection. - -.. literalinclude:: /code-snippets/collation/collection-collation.js - :language: javascript - :start-after: start collection collation - :end-before: end collection collation - -Any of the operations that support collations automatically apply the collation -defined on the collection. The query below searches the ``souvenirs`` -collection and applies the ``"fr_CA"`` locale collation: - -.. literalinclude:: /code-snippets/collation/collection-auto-collation.js - :language: javascript - :start-after: start auto collation - :end-before: end auto collation - -You can specify a different collation as a parameter in an operation that -supports collations. The following query specifies the ``"is"`` Iceland locale -and ``caseFirst`` optional parameter with the value ``"upper"``: - -.. literalinclude:: /code-snippets/collation/collection-specify-collation.js - :language: javascript - :start-after: start specified collation - :end-before: end specified collation - -Assign a Collation to an Index -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the following example, we create a new index on the ``title`` field of -a collection with a collation set to the ``"en_US"`` locale. - -.. literalinclude:: /code-snippets/collation/index-collation.js - :language: javascript - :start-after: start create index collation - :end-before: end create index collation - -The following query uses the index we created: - -.. literalinclude:: /code-snippets/collation/query-index-collation.js - :language: javascript - :start-after: start query index collation - :end-before: end query index collation - -The following queries **do not** use the index that we created. The first -query does not include a collation and the second contains a different -strength value than the collation on the index. - -.. literalinclude:: /code-snippets/collation/query-not-indexed-collation.js - :language: javascript - :start-after: start not indexed collation - :end-before: end not indexed collation - -.. literalinclude:: /code-snippets/collation/query-index-no-collation.js - :language: javascript - :start-after: start index no collation - :end-before: end index no collation - -Collation Query Examples -~~~~~~~~~~~~~~~~~~~~~~~~ - -Operations that read, update, and delete documents from a collection can use -collations. This section includes examples of a selection of these. See the -MongoDB manual for a full list of :manual:`operations that support collation -`. - -find() and sort() Example -````````````````````````` - -The following example calls both ``find()`` and ``sort()`` on a collection -that uses the default binary collation. We use the German collation by -setting the value of the ``locale`` parameter to ``"de"``. - -.. literalinclude:: /code-snippets/collation/find-sort-collation.js - :language: javascript - :start-after: start find sort collation - :end-before: end find sort collation - -findOneAndUpdate() Example -`````````````````````````` - -The following example calls the ``findOneAndUpdate()`` operation on a -collection that uses the default binary collation. The collection contains the -following documents: - -.. code-block:: none - - { "_id" : 1, "first_name" : "Hans" } - { "_id" : 2, "first_name" : "Gunter" } - { "_id" : 3, "first_name" : "Günter" } - { "_id" : 4, "first_name" : "Jürgen" } - -Consider the following ``findOneAndUpdate()`` operation on this collection -which **does not** specify a collation: - -.. literalinclude:: /code-snippets/collation/findOneAndUpdate-default-order-collation.js - :language: javascript - :start-after: start findOneAndUpdate default order collation - :end-before: end findOneAndUpdate default order collation - -Since "Gunter" is the first sorted result when using a binary collation, none -of the documents come lexically before and match the ``$lt`` comparison -operator in the query document. As a result, the operation does not update any -documents. - -Consider the same operation with a collation specified with the locale set to -``de@collation=phonebook``. This locale specifies the ``collation=phonebook`` -option which contains rules for prioritizing proper nouns, identified by -capitalization of the first letter. The ``de@collation=phonebook`` locale and -option sorts characters with umlauts before the same characters without -umlauts. - -.. literalinclude:: /code-snippets/collation/findOneAndUpdate-collation.js - :language: javascript - :start-after: start findOneAndUpdate collation - :end-before: end findOneAndUpdate collation - -Since "Günter" lexically comes before "Gunter" using the -``de@collation=phonebook`` collation specified in ``findOneAndUpdate()``, -the operation returns the following updated document: - -.. code-block:: none - - { lastErrorObject: { updatedExisting: true, n: 1 }, - value: { _id: 3, first_name: 'Günter' }, - ok: 1 } - -findOneAndDelete() Example -`````````````````````````` - -The following example calls the ``findOneAndDelete()`` operation on a -collection that uses the default binary collation and contains the following -documents: - -.. code-block:: none - - { "_id" : 1, "a" : "16" } - { "_id" : 2, "a" : "84" } - { "_id" : 3, "a" : "179" } - -In this example, we set the ``numericOrdering`` collation parameter to ``true`` -to sort numeric strings based on their numerical order instead of their -lexical order. - -.. literalinclude:: /code-snippets/collation/findOneAndDelete-collation.js - :language: javascript - :start-after: start findOneAndDelete collation - :end-before: end findOneAndDelete collation - -After you run the operation above, the collection contains the following -documents: - -.. code-block:: none - - { "_id" : 1, "a" : "16" } - { "_id" : 2, "a" : "84" } - -If you perform the same operation without collation on the original -collection of three documents, it matches documents based on the lexical value -of the strings (``"16"``, ``"84"``, and ``"179"``), and deletes the first -document it finds that matches the query criteria. - -.. literalinclude:: /code-snippets/collation/findOneAndDelete-no-collation.js - :language: javascript - :start-after: start findOneAndDelete no collation - :end-before: end findOneAndDelete no collation - -Since all the documents contain lexical values in the ``a`` field that -match the criteria (greater than the lexical value of ``"100"``), the operation -removes the first result. After you run the operation above, the collection -contains the following documents: - -.. code-block:: none - - { "_id" : 2, "a" : "84" } - { "_id" : 3, "a" : "179" } - -Aggregation Example -``````````````````` - -To use collation with the `aggregate <{+api+}/classes/Collection.html#aggregate>`__ -operation, pass the collation document in the options field, after the -array of pipeline stages. - -The following example shows an aggregation pipeline on a collection that uses -the default binary collation. The aggregation groups the ``first_name`` field, -counts the total number of results in each group, and sorts the results by -the German phonebook (``"de@collation=phonebook"`` locale) order. - -.. note:: - - You can specify only one collation on an aggregation. - -.. literalinclude:: /code-snippets/collation/aggregation-collation.js - :language: javascript - :start-after: start aggregation collation - :end-before: end aggregation collation diff --git a/source/archive-reference-files/quick-start/connect-to-mongodb.txt b/source/archive-reference-files/quick-start/connect-to-mongodb.txt deleted file mode 100644 index 45a2eb228..000000000 --- a/source/archive-reference-files/quick-start/connect-to-mongodb.txt +++ /dev/null @@ -1,81 +0,0 @@ -.. _node-quick-start-connect-to-mongodb: - -================== -Connect to MongoDB -================== - -.. meta:: - :description: Connect to MongoDB using the MongoDB Node.js Driver by creating an application, assigning a connection string, and running a query to retrieve data. - -.. procedure:: - :style: connected - - .. step:: Create your Node.js Application - - Create a file to contain your application called ``index.js`` in your - ``node_quickstart`` project directory. - - Copy and paste the following code into the ``index.js`` file: - - .. code-block:: js - - const { MongoClient } = require("mongodb"); - - // Replace the uri string with your connection string. - const uri = ""; - - const client = new MongoClient(uri); - - async function run() { - try { - const database = client.db('sample_mflix'); - const movies = database.collection('movies'); - - // Query for a movie that has the title 'Back to the Future' - const query = { title: 'Back to the Future' }; - const movie = await movies.findOne(query); - - console.log(movie); - } finally { - // Ensures that the client will close when you finish/error - await client.close(); - } - } - run().catch(console.dir); - - .. step:: Assign the Connection String - - Replace the ```` placeholder with the - connection string that you copied from the :ref:`node-quick-start-connection-string` - step of this guide. - - .. step:: Run your Node.js Application - - In your shell, run the following command to start this application: - - .. code-block:: none - - node index.js - - The output includes details of the retrieved movie document: - - .. code-block:: none - - { - _id: ..., - plot: 'A young man is accidentally sent 30 years into the past...', - genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], - ... - title: 'Back to the Future', - ... - } - - If you encounter an error or see no output, check whether you specified the - proper connection string in the ``index.js`` file, and that you loaded the - sample data. - -After you complete these steps, you have a working application that -uses the driver to connect to your MongoDB deployment, runs a query on -the sample data, and prints out the result. - -.. include:: /includes/quick-start/troubleshoot.rst diff --git a/source/archive-reference-files/quick-start/create-a-connection-string.txt b/source/archive-reference-files/quick-start/create-a-connection-string.txt deleted file mode 100644 index cc580776c..000000000 --- a/source/archive-reference-files/quick-start/create-a-connection-string.txt +++ /dev/null @@ -1,63 +0,0 @@ -.. _node-quick-start-connection-string: - -========================== -Create a Connection String -========================== - -.. meta:: - :description: Create a connection string for your MongoDB deployment by including the hostname, port, authentication mechanism, and user credentials. - -You can connect to your MongoDB deployment by providing a -**connection URI**, also called a *connection string*, which -instructs the driver on how to connect to a MongoDB deployment -and how to behave while connected. - -The connection string includes the hostname or IP address and -port of your deployment, the authentication mechanism, user credentials -when applicable, and connection options. - -To connect to an instance or deployment not hosted on Atlas, see -:ref:`Other Ways to Connect to MongoDB `. - -.. 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 and click the :guilabel:`Connect` button - for your new deployment. - - .. figure:: /includes/figures/atlas_connect.png - :alt: The connect button in the clusters section of the Atlas UI - - Select the :guilabel:`Drivers` option from the :guilabel:`Connect to your application` - section. Then in the :guilabel:`Connecting with MongoDB Driver` - menu, select "Node.js" from the :guilabel:`Driver` selection menu and the version - that best matches the version you installed from the :guilabel:`Version` - selection menu. - - Select the :guilabel:`Password (SCRAM)` authentication mechanism. - - .. step:: Copy your Connection String - - Click the button on the right of the connection string to copy it to - your clipboard as shown in the following screenshot: - - .. figure:: /includes/figures/atlas_connection_copy_string.png - :alt: The connection string copy button in the Atlas UI - - .. step:: Update the Placeholders - - Paste this connection string into a a file in your preferred text editor - and replace the "" and "" placeholders with - your database user's username and password. - - Save this file to a safe location for use in the next step. - -After completing these steps, you have a connection string that -contains your database username and password. - -.. include:: /includes/quick-start/troubleshoot.rst diff --git a/source/archive-reference-files/quick-start/create-a-deployment.txt b/source/archive-reference-files/quick-start/create-a-deployment.txt deleted file mode 100644 index a1fade2f2..000000000 --- a/source/archive-reference-files/quick-start/create-a-deployment.txt +++ /dev/null @@ -1,32 +0,0 @@ -.. _node-quick-start-create-deployment: - -=========================== -Create a MongoDB Deployment -=========================== - -.. meta:: - :description: Set up a free tier MongoDB deployment on Atlas, including creating an account, saving credentials, and loading sample data. - -You can create a free tier MongoDB deployment on MongoDB Atlas -to store and manage your data. MongoDB Atlas hosts and manages -your MongoDB database in the cloud. - -.. procedure:: - :style: connected - - .. step:: Create a Free MongoDB deployment on Atlas - - Complete the :atlas:`Get Started with Atlas ` - guide to set up a new Atlas account and load sample data into a new free - tier MongoDB deployment. - - .. step:: Save your Credentials - - After you create your database user, save that user's - username and password to a safe location for use in an upcoming step. - -After you complete these steps, you have a new free tier MongoDB -deployment on Atlas, database user credentials, and sample data loaded -in your database. - -.. include:: /includes/quick-start/troubleshoot.rst diff --git a/source/archive-reference-files/quick-start/download-and-install.txt b/source/archive-reference-files/quick-start/download-and-install.txt deleted file mode 100644 index 76c22f2c6..000000000 --- a/source/archive-reference-files/quick-start/download-and-install.txt +++ /dev/null @@ -1,65 +0,0 @@ -.. _node-quick-start-download-and-install: - -==================== -Download and Install -==================== - -.. meta:: - :description: Install Node.js and npm, create a project directory, and install the MongoDB Node.js Driver. - -.. procedure:: - :style: connected - - .. step:: Install Node and npm - - Ensure you have Node.js {+min-node-version+} or later and - npm (Node Package Manager) installed in your development environment. - - For information on how to install Node.js and npm, see - `downloading and installing Node.js and npm `__. - - .. step:: Create a Project Directory - - In your shell, run the following command to create a - directory called ``node_quickstart`` for this project: - - .. code-block:: bash - - mkdir node_quickstart - - Run the following command to navigate into the project - directory: - - .. code-block:: bash - - cd node_quickstart - - Run the following command to initialize your Node.js project: - - .. code-block:: bash - - npm init -y - - When this command successfully completes, you have a ``package.json`` - file in your ``node_quickstart`` directory. - - - .. step:: Install the Node.js Driver - - Run the following command in your shell to install - the driver in your project directory: - - .. code-block:: bash - - npm install mongodb@{+version+} - - This command performs the following actions: - - - Downloads the ``mongodb`` package and the dependencies it requires - - Saves the package in the ``node_modules`` directory - - Records the dependency information in the ``package.json`` file - -After you complete these steps, you have Node.js and npm installed -and a new project directory with the driver dependencies installed. - -.. include:: /includes/quick-start/troubleshoot.rst diff --git a/source/archive-reference-files/quick-start/facets.toml b/source/archive-reference-files/quick-start/facets.toml deleted file mode 100644 index 07bd7b7f7..000000000 --- a/source/archive-reference-files/quick-start/facets.toml +++ /dev/null @@ -1,3 +0,0 @@ -[[facets]] -category = "genre" -value = "tutorial" diff --git a/source/archive-reference-files/quick-start/next-steps.txt b/source/archive-reference-files/quick-start/next-steps.txt deleted file mode 100644 index 55d656e6c..000000000 --- a/source/archive-reference-files/quick-start/next-steps.txt +++ /dev/null @@ -1,22 +0,0 @@ -.. _node-quick-start-next-steps: - -========== -Next Steps -========== - -.. meta:: - :description: Explore further resources to enhance your understanding of the MongoDB Node.js Driver, including CRUD operations and usage examples. - -Congratulations on completing the quick start tutorial! - -In this tutorial, you created a Node.js application that -connects to a MongoDB deployment hosted on MongoDB Atlas -and retrieves a document that matches a query. - -Learn more about the {+driver-long+} from the following resources: - -- Discover how to perform read and write operations in the - :ref:`CRUD Operations ` section. - -- See examples of frequently-used operations in the - :ref:`Usage Examples ` section. diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index eb89bdf0e..fbffaa407 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -17,7 +17,6 @@ Specify Connection Options :maxdepth: 1 Compress Network Traffic - Customize Server Selection Stable API Limit Server Execution Time Connection Pools diff --git a/source/connect/connection-options/server-selection.txt b/source/connect/connection-options/server-selection.txt deleted file mode 100644 index d7798049b..000000000 --- a/source/connect/connection-options/server-selection.txt +++ /dev/null @@ -1,21 +0,0 @@ -.. _node-server-selection: - -========================== -Customize Server Selection -========================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, read preference, write - -Overview --------- \ No newline at end of file diff --git a/source/crud.txt b/source/crud.txt index 6a2ea2af3..5afe449d3 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -31,7 +31,19 @@ CRUD Operations Compound Operations Transactions Configure CRUD Operations + Generate Custom _id Values Store Large Files CRUD (Create, Read, Update, Delete) operations enable you to work with -data stored in MongoDB. \ No newline at end of file +data stored in MongoDB. + +- :ref:`node-insert` +- :ref:`node-query` +- :ref:`node-update` +- :ref:`node-delete` +- :ref:`node-bulk-write` +- :ref:`node-crud-compound-operations` +- :ref:`node-transactions` +- :ref:`node-configure` +- :ref:`node-pkfactory` +- :ref:`node-gridfs` \ No newline at end of file diff --git a/source/crud/gridfs.txt b/source/crud/gridfs.txt index cd7cfc4b5..0f604d50f 100644 --- a/source/crud/gridfs.txt +++ b/source/crud/gridfs.txt @@ -1,8 +1,8 @@ .. _node-gridfs: -====== -GridFS -====== +============================= +Store Large Files with GridFS +============================= .. facet:: :name: genre @@ -167,8 +167,8 @@ see the following resources: - `find() API documentation <{+api+}/classes/GridFSBucket.html#find>`__ - `FindCursor API documentation <{+api+}/classes/FindCursor.html>`__ -- :doc:`Cursor Fundamentals page ` -- :doc:`Query Operations page ` +- :ref:`Access Data From a Cursor guide ` +- :ref:`Find Documents guide ` .. _gridfs-download-files: diff --git a/source/crud/pkFactory.txt b/source/crud/pkFactory.txt index 37456e967..34a71eb44 100644 --- a/source/crud/pkFactory.txt +++ b/source/crud/pkFactory.txt @@ -1,8 +1,8 @@ .. _node-pkfactory: -================================== -Generate Custom Values for ``_id`` -================================== +============================== +Generate Custom Values for _id +============================== .. meta:: :description: Learn how to use the MongoDB Node.js Driver to generate custom _id values with a primary key factory during insert operations. diff --git a/source/crud/query.txt b/source/crud/query.txt index b0d5f9cf7..c21336f17 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -8,6 +8,7 @@ Query Operations .. meta:: :description: Learn how to use {+driver-short+} to read data from MongoDB. :keywords: usage examples, query, find, code example + .. facet:: :name: genre :values: reference @@ -28,226 +29,10 @@ Query Operations Access Data from a Cursor Geospatial Queries -.. _nodejs-driver-retrieve-data-overview: - -Overview --------- - -You can perform find operations to retrieve data from your MongoDB database. -You can perform a find operation to match documents on a set of criteria -by calling the ``find()`` or ``findOne()`` method. - -.. tip:: Interactive Lab - - This page includes a short interactive lab that demonstrates how to - retrieve data by using the ``find()`` method. You can complete this lab - directly in your browser window without installing MongoDB or a code editor. - - To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the - top of the page. To expand the lab to a full-screen format, click the - full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane. - -You can also further specify the information that the find operation -returns by specifying optional parameters or by chaining other methods, -as shown in the following guides: - -- :ref:`node-fundamentals-sort` -- :ref:`node-fundamentals-skip` -- :ref:`node-fundamentals-limit` -- :ref:`node-fundamentals-project` - -You can also use an aggregation operation to retrieve data. This type of -operation allows you to apply an ordered pipeline of transformations to the -matched data. - -If you want to monitor the database for incoming data that matches a set of -criteria, you can use the watch operation to be notified in real-time when -matching data is inserted. - -.. include:: /includes/access-cursor-note.rst - -.. |page-topic| replace:: perform read operations -.. |link-topic-ing| replace:: performing read operations in the Atlas UI - -.. |atlas-url| replace:: :atlas:`View, Filter, and Sort Documents ` - -.. include:: /includes/fact-atlas-compatible.rst -.. include:: /includes/fact-atlas-link.rst - -Find Documents --------------- - -You can call the ``find()`` method on a ``Collection`` object. The -method accepts a query document that describes the documents you want to -retrieve. For more information on how to specify your query document, -see the :ref:`node-fundamentals-query-document` guide. - -.. tip:: No Query Criteria - - To execute a find operation that has no query criteria, you can - pass an empty query or omit the query document in your find - method parameters. - - The following operations both return all documents in the - ``myColl`` collection: - - .. code-block:: javascript - - myColl.find(); // no query - myColl.find({}); // empty query - - If you don't pass a query or pass an empty query - to the ``findOne()`` method, the operation returns a single - document from a collection. - - You can specify options in a find operation even when you pass an - empty query. For example, the following code shows how you can - specify a projection as an option while executing a find operation - that receives an empty query parameter: - - .. code-block:: javascript - - const options = { - projection: { _id: 0, field1: 1 }, - }; - - const findResult = await myColl.findOne({}, options); - - For more information about projecting document fields, see the - :ref:`node-fundamentals-project` guide. - -The ``find()`` method returns a ``Cursor`` instance from which you can -access the matched documents. The ``findOne()`` method returns a ``Promise`` -instance, which you can resolve to access either the matching document or -a ``null`` value if there are no matches. - -.. example:: - - A pizza restaurant wants to find all pizzas ordered by Lemony Snicket - yesterday. They run the following ``find()`` query on the - ``orders`` collection: - - .. literalinclude:: /code-snippets/crud/pizza.js - :language: javascript - :start-after: start find crud example - :end-before: end find crud example - - Once the operation returns, the ``findResult`` variable references a - ``Cursor``. You can print the documents retrieved using the ``for await...of`` - syntax as shown below: - - .. code-block:: javascript - - for await (const doc of findResult) { - console.log(doc); - } - - The output might resemble the following: - - .. code-block:: javascript - :copyable: false - - [ - { name: "Lemony Snicket", type: "horseradish pizza", qty: 1, status: "delivered", date: ... }, - { name: "Lemony Snicket", type: "coal-fired oven pizza", qty: 3, status: "canceled", date: ...}, - ... - ] - -Additional Information -~~~~~~~~~~~~~~~~~~~~~~ - -For runnable code examples that demonstrate find operations, see the following -examples: - -- :ref:`node-usage-findone` -- :ref:`node-usage-find` - -For more information about the ``findOne()`` and ``find()`` methods, see the -following Server manual documentation: - -- :manual:`findOne() ` -- :manual:`find() ` - -Aggregate Data from Documents ------------------------------ - -If you want to run a custom processing pipeline to retrieve data from your -database, you can use the ``aggregate()`` method. This method accepts -aggregation expressions to run in sequence. These expressions let you filter, -group, and arrange the result data from a collection. - -.. example:: - - A pizza restaurant wants to run a status report on-demand to - summarize pizza orders over the past week. They run the following - ``aggregate()`` query on the ``orders`` collection to fetch the - totals for each distinct "status" field: - - .. literalinclude:: /code-snippets/crud/pizza.js - :language: javascript - :start-after: start aggregate crud example - :end-before: end aggregate crud example - - Once the operation returns, the ``aggregateResult`` variable references a - ``Cursor``. You can print the documents retrieved using the ``for await...of`` - syntax as shown below: - - .. code-block:: javascript - - for await (const doc of aggregateResult) { - console.log(doc); - } - - The output might resemble the following: - - .. code-block:: javascript - :copyable: false - - [ - { _id: 'delivering', count: 5 }, - { _id: 'delivered', count: 37 }, - { _id: 'created', count: 9 } - ] - -Additional Information -~~~~~~~~~~~~~~~~~~~~~~ - -For more information on how to construct an aggregation pipeline, see -the :ref:`node-aggregation` guide or :manual:`Aggregation Operations ` -in the Server manual. - -.. _node-fundamentals-watch: - -Monitor Data Changes --------------------- - -You can use the ``watch()`` method to monitor a collection for changes to -a collection that match certain criteria. These changes include inserted, -updated, replaced, and deleted documents. You can pass this method -a pipeline of aggregation commands that sequentially runs on the changed -data whenever write operations are executed on the collection. - -.. example:: - - A pizza restaurant wants to receive a notification whenever a new pizza - order comes in. To accomplish this, they create an aggregation pipeline - to filter on insert operations and return specific fields. They pass - this pipeline to the ``watch()`` method called on the ``orders`` - collection as shown below: - - .. literalinclude:: /code-snippets/crud/pizza.js - :language: javascript - :start-after: start watch crud example - :end-before: end watch crud example - -Additional Information -~~~~~~~~~~~~~~~~~~~~~~ - -For a runnable example of the ``watch()`` method, see the -:ref:`Watch for Changes ` usage example. - -.. _node-retrieve-instruqt-lab: - -.. instruqt:: /mongodb-docs/tracks/find-node?token=em_OVNHWCPNPMLwNOCm - :title: find() Lesson - :drawer: \ No newline at end of file +- :ref:`node-find` +- :ref:`node-specify-documents-to-return` +- :ref:`node-project` +- :ref:`node-count` +- :ref:`node-distinct` +- :ref:`node-cursor` +- :ref:`node-geospatial` \ No newline at end of file diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index a567b281a..f83fe41e1 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -73,9 +73,9 @@ The following example estimates the number of documents in the an accurate count of the number of documents in the ``movies`` collection with ``Canada`` in the ``countries`` field: - .. literalinclude:: /code-snippets/usage-examples/count.js - :language: javascript - :linenos: +.. literalinclude:: /code-snippets/usage-examples/count.js + :language: javascript + :linenos: Running the preceding sample code results in the following output: diff --git a/source/crud/update.txt b/source/crud/update.txt index 80cf3caec..8855761d8 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -79,6 +79,8 @@ If a food truck named "Deli Llama" exists, the method call above updates the document in the collection. However, if there are no food trucks named "Deli Llama" in your collection, no changes are made. +.. _node-upsert: + Performing an Upsert -------------------- diff --git a/source/crud/update/replace.txt b/source/crud/update/replace.txt index 2099e331d..43b7b7ca7 100644 --- a/source/crud/update/replace.txt +++ b/source/crud/update/replace.txt @@ -115,7 +115,7 @@ and the immutable ``_id`` field as follows: If a replace operation fails to match any documents in a collection, it does not make any changes. Replace operations can be configured to perform -an :ref:`upsert ` which +an :ref:`upsert ` which attempts to perform the replacement, but if no documents are matched, it inserts a new document with the specified fields and values. diff --git a/source/fundamentals.txt b/source/fundamentals.txt deleted file mode 100644 index 3010fedcb..000000000 --- a/source/fundamentals.txt +++ /dev/null @@ -1,29 +0,0 @@ -============ -Fundamentals -============ - -.. meta:: - :description: Explore tasks using the MongoDB Node.js Driver, including connecting, authenticating, reading, writing, and managing transactions in MongoDB. - -.. default-domain:: mongodb - -.. toctree:: - - Connection - Stable API - Authentication - CRUD Operations - Promises - Aggregation - Transactions - Run a Command - Indexes - Collations - Logging - GridFS - Time Series - TypeScript - BSON Settings - In-Use Encryption - -.. include:: /includes/fundamentals-sections.rst diff --git a/source/fundamentals/bson/undefined-values.txt b/source/fundamentals/bson/undefined-values.txt deleted file mode 100644 index e1ebbef71..000000000 --- a/source/fundamentals/bson/undefined-values.txt +++ /dev/null @@ -1,130 +0,0 @@ -.. _node-undefined-values: - -================ -Undefined Values -================ - -.. meta:: - :description: Learn to control the serialization of undefined values in MongoDB Node.js Driver by using the ignoreUndefined setting at various levels. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn to control how the driver serializes -``undefined`` values. By default, the driver serializes ``undefined`` values -as ``null`` values during write operations. - -.. _nodejs-specify-ignoreundefined: - -Ignore Undefined Values ------------------------ - -To make the driver ignore fields with -``undefined`` values during serialization, set the -``ignoreUndefined`` setting to ``true``. When you specify this setting, -the driver *does not* serialize fields with ``undefined`` values. - -The following example inserts two documents. The first insert operation has -the ``ignoreUndefined`` setting set to ``true``, so the driver does not -serialize the ``salesTax`` field in that operation. The second operation -inserts a document that has the ``salesTax`` field with a ``null`` value: - -.. code-block:: javascript - :emphasize-lines: 6 - - await myColl.insertOne( - { - state: "Montana", - salesTax: undefined, - }, - { ignoreUndefined: true } - ); - - await myColl.insertOne({ - state: "New Hampshire", - salesTax: undefined, - }); - -The documents appear in the collection as follows: - -.. code-block:: javascript - :copyable: false - - { - _id: ..., - state: "Montana", - }, - { - _id: ..., - state: "New Hampshire", - salesTax: null - } - -.. _nodejs-ignoreundefined-scope: - -Set the Scope for Serializing Undefined Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can specify the ``ignoreUndefined`` setting at the following levels: - -- The client level -- The database level -- The collection level -- The operation level - -The ``ignoreUndefined`` setting automatically applies to the scope of the -object instance in which you specified it and any other objects created -from that instance. - -For example, if you set the ``ignoreUndefined`` setting when -instantiating a database object, any collection instance created from -that object inherits the setting. Furthermore, any operations that you -call on that collection instance also inherit the setting. - -The following example performs an find-and-update operation that -inherits the ``ignoreUndefined`` setting from the ``myDB`` database -object. This operation does not produce any data changes because the -driver ignores the ``gasTax`` field: - -.. code-block:: javascript - - const myDB = client.db("test", { ignoreUndefined: true }); - - // The collection inherits the ignoreUndefined setting - const myColl = myDB.collection("states"); - - // Any write operation will not serialize undefined values - await myColl.findOneAndUpdate( - { state: "Georgia" }, - { $set: { gasTax: undefined } } - ); - -You can specify the ``ignoreUndefined`` setting again at any level to -override any inherited settings. - -For example, if you set ``ignoreUndefined`` to ``true`` on your -collection object, you can override the setting in individual write -operations that you execute on that collection. - -.. code-block:: javascript - :emphasize-lines: 1, 12 - - const myColl = myDB.collection("states", { ignoreUndefined: true }); - - // The insert operation will not serialize undefined values - await myColl.insertOne({ - state: "South Dakota", - capitalGainsTax: undefined, - }); - - // The insert operation will serialize undefined values - await myColl.insertOne( - { state: "Texas", capitalGainsTax: undefined }, - { ignoreUndefined: false } - ); diff --git a/source/fundamentals/bson/utf8-validation.txt b/source/fundamentals/bson/utf8-validation.txt deleted file mode 100644 index a31e7e72f..000000000 --- a/source/fundamentals/bson/utf8-validation.txt +++ /dev/null @@ -1,121 +0,0 @@ -.. _nodejs-utf-8-validation: - -================ -UTF-8 Validation -================ - -.. meta:: - :description: Learn how to enable or disable UTF-8 validation in the MongoDB Node.js Driver to manage data encoding and processing overhead. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn how to enable or disable the {+driver-short+}'s -**UTF-8** validation feature. UTF-8 is a character encoding specification -that ensures compatibility and consistent presentation across most operating -systems, applications, and language character sets. - -If you *enable* validation, the driver throws an error when it attempts to -convert data that contains invalid UTF-8 characters. The validation adds -processing overhead since it needs to check the data. - -If you *disable* validation, your application avoids the validation processing -overhead, but cannot guarantee consistent presentation of invalid UTF-8 data. - -By default, the driver enables UTF-8 validation on data from MongoDB. -It checks incoming documents for any characters that are not encoded in a -valid UTF-8 format when it parses data sent from MongoDB to your application. - -.. note:: - - This version of the {+driver-short+} automatically substitutes invalid - `lone surrogates `__ - with the `replacement character `__ - before validation when you send data to MongoDB. Therefore, the validation - only throws an error when the setting is enabled and the driver - receives invalid UTF-8 document data from MongoDB. - -Read the sections below to learn how to set UTF-8 validation using the -{+driver-short+}. - -.. _nodejs-specify-utf-8-validation: - -Specify the UTF-8 Validation Setting ------------------------------------- - -You can specify whether the driver performs UTF-8 validation by -defining the ``enableUtf8Validation`` setting in the options parameter -when you create a client, reference a database or collection, or call a -CRUD operation. If you omit the setting, the driver enables UTF-8 validation. - -See the following for code examples that demonstrate how to disable UTF-8 -validation on the client, database, collection, or CRUD operation: - -.. code-block:: javascript - - // disable UTF-8 validation on the client - new MongoClient('', { enableUtf8Validation: false }); - - // disable UTF-8 validation on the database - client.db('', { enableUtf8Validation: false }); - - // disable UTF-8 validation on the collection - db.collection('', { enableUtf8Validation: false }); - - // disable UTF-8 validation on a specific operation call - await myColl.findOne({ title: 'Cam Jansen'}, { enableUtf8Validation: false }); - -If your application reads invalid UTF-8 from MongoDB while the -``enableUtf8Validation`` option is enabled, it throws a ``BSONError`` that -contains the following message: - -.. code-block:: - - Invalid UTF-8 string in BSON document - -.. _nodejs-utf-8-validation-scope: - -Set the Validation Scope -~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``enableUtf8Validation`` setting automatically applies to the scope of the -object instance on which you included it, and any other objects created by -calls on that instance. - -For example, if you include the option on the call to instantiate a database -object, any collection instance you construct from that object inherits -the setting. Any operations you call on that collection instance also -inherit the setting. - -.. code-block:: javascript - - const database = client.db('books', { enableUtf8Validation: false }); - - // The collection inherits the UTF-8 validation disabled setting from the database - const myColl = database.collection('mystery'); - - // CRUD operation runs with UTF-8 validation disabled - await myColl.findOne({ title: 'Encyclopedia Brown' }); - -You can override the setting at any level of scope by including it when -constructing the object instance or when calling an operation. - -For example, if you disable validation on the collection object, you can -override the setting in individual CRUD operation calls on that -collection. - -.. code-block:: javascript - - const collection = database.collection('mystery', { enableUtf8Validation: false }); - - // CRUD operation runs with UTF-8 validation enabled - await myColl.findOne({ title: 'Trixie Belden' }, { enableUtf8Validation: true }); - - // CRUD operation runs with UTF-8 validation disabled - await myColl.findOne({ title: 'Enola Holmes' }); diff --git a/source/fundamentals/crud/read-operations/limit.txt b/source/fundamentals/crud/read-operations/limit.txt deleted file mode 100644 index eb15c2694..000000000 --- a/source/fundamentals/crud/read-operations/limit.txt +++ /dev/null @@ -1,139 +0,0 @@ -.. _node-fundamentals-limit: - -==================================== -Limit the Number of Returned Results -==================================== - -.. meta:: - :description: Use the limit() method in the MongoDB Node.js Driver to cap the number of documents returned in a read operation, with examples of combining it with sort and skip options for pagination. - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -Use ``limit`` to cap the number of documents that can be returned from a -read operation. ``limit`` functions as a cap on the maximum number of -documents that the operation can return, but the operation can return -a smaller number of documents if there are not enough documents present -to reach the limit. If ``limit`` is used with the -:doc:`skip ` method, the skip applies -first and the limit only applies to the documents left over after -the skip. - -Sample Documents -~~~~~~~~~~~~~~~~ - -To follow the examples in this guide, use the following code snippet to insert documents -that describe books into the ``myDB.books`` collection: - -.. code-block:: javascript - - const myDB = client.db("myDB"); - const myColl = myDB.collection("books"); - - await myColl.insertMany([ - { "_id": 1, "name": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }, - { "_id": 2, "name": "Les Misérables", "author": "Hugo", "length": 1462 }, - { "_id": 3, "name": "Atlas Shrugged", "author": "Rand", "length": 1088 }, - { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, - { "_id": 5, "name": "Cryptonomicon", "author": "Stephenson", "length": 918 }, - { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 }, - ]); - -.. include:: /includes/access-cursor-note.rst - -Limit ------ - -The following example queries the collection to return the top three -longest books. It matches all documents because the query filter is -empty. Then, it applies a descending ``sort`` on the ``length`` field to -return longer books before shorter books and a ``limit`` to -return only the ``3`` first results: - -.. code-block:: javascript - :emphasize-lines: 4 - - // define an empty query document - const query = {}; - // sort in descending (-1) order by length - const sort = { length: -1 }; - const limit = 3; - const cursor = myColl.find(query).sort(sort).limit(limit); - for await (const doc of cursor) { - console.dir; - } - -The code example above outputs the following three documents, sorted by -length: - -.. code-block:: json - :copyable: false - - { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } - { "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 } - { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } - -.. note:: - - The order in which you call ``limit`` and ``sort`` does not matter - because the driver reorders the calls to apply the sort first and the - limit after it. The following two calls are equivalent: - - .. code-block:: javascript - - myColl.find(query).sort({ length: -1 }).limit(3); - myColl.find(query).limit(3).sort({ length: -1 }); - -You can also apply ``sort`` and ``limit`` by specifying them in an -``options`` object in your call to the ``find()`` method. The following two -calls are equivalent: - -.. code-block:: javascript - - myColl.find(query).sort({ length: -1 }).limit(3); - myColl.find(query, { sort: { length: -1 }, limit: 3 }); - -For more information on the ``options`` settings for the ``find()`` -method, see the -`API documentation on find() <{+api+}/classes/Collection.html#find>`__. - -Skip ----- - -To see the next three books in the results, append the ``skip()`` method, -passing the number of documents to bypass as shown below: - -.. code-block:: javascript - :emphasize-lines: 6,7 - - // define an empty query document - const query = {}; - // sort in descending (-1) order by length - const sort = { length: -1 }; - const limit = 3; - const skip = 3; - const cursor = myColl.find(query).sort(sort).limit(limit).skip(skip); - for await (const doc of cursor) { - console.dir; - } - -This operation returns the documents that describe the fourth through sixth -books in order of longest-to-shortest length: - -.. code-block:: json - :copyable: false - - { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } - { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } - { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } - -You can combine skip and limit in this way to implement paging for your -collection, returning only small "slices" of the collection at once. diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt deleted file mode 100644 index 07e6c2460..000000000 --- a/source/fundamentals/crud/read-operations/skip.txt +++ /dev/null @@ -1,95 +0,0 @@ -.. _node-fundamentals-skip: - -===================== -Skip Returned Results -===================== - -.. meta:: - :description: Use the skip option in MongoDB Node.js Driver read operations to omit a specified number of documents from the beginning of the result set, often combined with the sort option for ordered results. - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -Use ``skip`` to omit documents from the beginning of the list of -returned documents for a read operation. You can combine ``skip`` with -:doc:`sort ` to omit the top -(for descending order) or bottom (for ascending order) results for a -given query. Since the :manual:`order of documents returned -` is not guaranteed in -the absence of a sort, using ``skip`` without using ``sort`` omits -arbitrary documents. - -If the value of ``skip`` exceeds the number of matched documents for -a query, then that query returns no documents. - -Sample Documents -~~~~~~~~~~~~~~~~ - -To follow the examples in this guide, use the following code snippet to insert documents -that describe fruits into the ``myDB.fruits`` collection: - -.. code-block:: javascript - - const myDB = client.db("myDB"); - const myColl = myDB.collection("fruits"); - - await myColl.insertMany([ - { "_id": 1, "name": "apples", "qty": 5, "rating": 3 }, - { "_id": 2, "name": "bananas", "qty": 7, "rating": 1 }, - { "_id": 3, "name": "oranges", "qty": 6, "rating": 2 }, - { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 }, - ]); - -.. include:: /includes/access-cursor-note.rst - -Example -------- - -In the following example, we query the collection with a filter that -matches all the documents and pass options that specifies ``sort`` and -``skip`` commands as query options. The sort option specifies that fruit -documents that have higher ``rating`` values are returned before ones with lower -ratings. The skip option specifies that the first 2 documents are -omitted from the result: - -.. code-block:: javascript - - // define an empty query document - const query = {}; - const options = { - // sort in descending (-1) order by rating - sort : { rating: -1 }, - // omit the first two documents - skip : 2, - } - - const cursor = myColl.find(query, options); - for await (const doc of cursor) { - console.dir(doc); - } - -Since we specified that query skip the first ``2`` documents, the third and fourth highest -rating documents are printed by the code snippet above: - -.. code-block:: json - :copyable: false - - { "_id": 3, "name": "oranges", "qty": 6, "rating": 2 } - { "_id": 2, "name": "bananas", "qty": 7, "rating": 1 } - - -The ``sort`` and ``skip`` options can also be specified as methods chained to -the ``find`` method. The following two commands are equivalent: - -.. code-block:: javascript - - myColl.find(query, { sort: { rating: -1}, skip: 2}); - myColl.find(query).sort({rating: -1}).skip(2); diff --git a/source/fundamentals/crud/read-operations/sort.txt b/source/fundamentals/crud/read-operations/sort.txt deleted file mode 100644 index 889707126..000000000 --- a/source/fundamentals/crud/read-operations/sort.txt +++ /dev/null @@ -1,119 +0,0 @@ -.. _node-fundamentals-sort: - -============ -Sort Results -============ - -.. meta:: - :description: Use the sort function in the MongoDB Node.js Driver to order query results by specified fields and resolve ties with other fields. - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -Use ``sort`` to change the order in which read operations return -documents. ``Sort`` tells MongoDB to order returned documents by the -values of one or more fields in a certain direction. To sort returned -documents by a field in ascending (lowest first) order, use a value of -``1``. To sort in descending (greatest first) order instead, use ``-1``. -If you do not specify a sort, MongoDB does not guarantee the order of -query results. - -Sample Documents -~~~~~~~~~~~~~~~~ - -Follow the instructions in the examples below to insert data into -the ``myDB.books`` collection and perform a sort on the results of a query. -Consider a collection containing documents that describe books. To -insert this data into a collection, run the following operation: - -.. code-block:: javascript - - const myDB = client.db("myDB"); - const myColl = myDB.collection("books"); - - await myColl.insertMany([ - { "_id": 1, "name": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }, - { "_id": 2, "name": "Les Misérables", "author": "Hugo", "length": 1462 }, - { "_id": 3, "name": "Atlas Shrugged", "author": "Rand", "length": 1088 }, - { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 }, - { "_id": 5, "name": "Cryptonomicon", "author": "Stephenson", "length": 918 }, - { "_id": 6, "name": "A Dance with Dragons", "author": "Martin", "length": 1104 }, - ]); - -.. include:: /includes/access-cursor-note.rst - -Example -------- - -Pass the following sort document to a read operation to ensure that the -operation returns books with longer lengths before books with shorter -lengths: - -.. code-block:: javascript - :emphasize-lines: 4 - - // define an empty query document - const query = {}; - // sort in descending (-1) order by length - const sort = { length: -1 }; - const cursor = myColl.find(query).sort(sort); - for await (const doc of cursor) { - console.dir(doc); - } - -In this case, the number ``-1`` tells the read operation to sort the -books in descending order by length. ``find()`` returns the following -documents when this sort is used with an empty query: - -.. code-block:: json - :copyable: false - - { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } - { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } - { "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 } - { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } - { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } - { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } - -Sometimes, the order of two or more documents is ambiguous using a -specified sort. In the above case, both "A Dance with Dragons" and -"Infinite Jest" have ``1104`` pages, so the order in which they are -returned is not guaranteed. To resolve ties in your sorted results in a -repeatable way, add more fields to the sort document: - -.. code-block:: javascript - :emphasize-lines: 4 - - // define an empty query document - const query = {}; - // sort in ascending (1) order by length - const sort = { length: 1, author: 1 }; - const cursor = myColl.find(query).sort(sort); - for await (const doc of cursor) { - console.dir(doc); - } - -With the addition of the ``author`` field to the sort document, the read operation sorts -matching documents first by ``length`` then, if there is a tie, by ``author``. Matched -document fields are compared in the same order as fields are specified in the sort -document. ``find()`` returns the following ordering of documents when this sort is used on -the documents matching the query, sorting ``"Martin"`` before ``"Wallace"`` for the two books with -the same length: - -.. code-block:: json - :copyable: false - - { "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 } - { "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 } - { "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 } - { "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 } - { "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 } - { "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 } diff --git a/source/fundamentals/crud/write-operations.txt b/source/fundamentals/crud/write-operations.txt deleted file mode 100644 index 18b3fd807..000000000 --- a/source/fundamentals/crud/write-operations.txt +++ /dev/null @@ -1,25 +0,0 @@ -================ -Write Operations -================ - -.. meta:: - :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. - - -.. toctree:: - :caption: Write Operations - - Insert - Custom Values for _id - Delete - Modify - Update Arrays - Upsert - Bulk Operations - -- :doc:`/fundamentals/crud/write-operations/pkFactory` -- :doc:`/fundamentals/crud/write-operations/delete` -- :doc:`/fundamentals/crud/write-operations/modify` -- :doc:`/fundamentals/crud/write-operations/embedded-arrays` -- :doc:`/fundamentals/crud/write-operations/upsert` -- :doc:`/fundamentals/crud/write-operations/bulk` diff --git a/source/includes/fundamentals-sections.rst b/source/includes/fundamentals-sections.rst deleted file mode 100644 index c69210ffc..000000000 --- a/source/includes/fundamentals-sections.rst +++ /dev/null @@ -1,20 +0,0 @@ -Learn how to perform the following tasks using the Node.js driver in the -Fundamentals section: - -- :doc:`Connect to MongoDB ` -- :doc:`Use the {+stable-api+} ` -- :doc:`Authenticate with MongoDB ` -- :doc:`Read from and Write to MongoDB ` -- :doc:`Access Return Values ` -- :doc:`Transform your Data ` -- :doc:`Create and Manage Transactions ` -- :doc:`Run a Database Command ` -- :doc:`Create Indexes to Speed Up Queries ` -- :doc:`Sort Using Collations ` -- :doc:`Log Events in the Driver ` -- :doc:`Monitor Driver Events ` -- :doc:`Store and Retrieve Large Files in MongoDB ` -- :doc:`Encrypt Fields from the Client ` -- :doc:`Create and Query Time Series Collection ` -- :doc:`Specify Type Parameters with TypeScript ` -- :doc:`Specify BSON Serialization Settings ` diff --git a/source/index.txt b/source/index.txt index 35236341b..732470635 100644 --- a/source/index.txt +++ b/source/index.txt @@ -20,6 +20,7 @@ MongoDB Node Driver Connect Databases & Collections CRUD Operations + Promises Aggregation Data Formats Indexes @@ -29,7 +30,7 @@ MongoDB Node Driver Monitoring and Logging Security Reference - Typescript + TypeScript API Documentation <{+api+}> Issues & Help View the Source @@ -108,7 +109,7 @@ Monitoring and Logging ---------------------- Learn how to monitor changes to your application and write them to logs in the -:ref:`` section. +:ref:`` section. Secure Your Data ---------------- diff --git a/source/monitoring-and-logging/change-streams.txt b/source/monitoring-and-logging/change-streams.txt index 8aa294c0e..9833a7c1a 100644 --- a/source/monitoring-and-logging/change-streams.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -94,7 +94,7 @@ read events from the change stream: You can attach listener functions to the ``ChangeStream`` object by calling the ``on()`` method. This method is inherited from the - Javascript ``EventEmitter`` class. Pass the string ``"change"`` as + JavaScript ``EventEmitter`` class. Pass the string ``"change"`` as the first parameter and your listener function as the second parameter as shown below: .. code-block:: javascript diff --git a/source/fundamentals/promises.txt b/source/promises.txt similarity index 95% rename from source/fundamentals/promises.txt rename to source/promises.txt index 933ba6bbd..15275c974 100644 --- a/source/fundamentals/promises.txt +++ b/source/promises.txt @@ -1,8 +1,8 @@ .. _node-promises: -======== -Promises -======== +========================================= +Use Promises with Asynchronous JavaScript +========================================= .. facet:: :name: genre @@ -21,15 +21,15 @@ Promises Overview -------- -The Node.js driver uses the asynchronous Javascript API to communicate with +The Node.js driver uses the asynchronous JavaScript API to communicate with your MongoDB cluster. -Asynchronous Javascript allows you to execute operations without waiting for +Asynchronous JavaScript allows you to execute operations without waiting for the processing thread to become free. This helps prevent your application from becoming unresponsive when executing long-running operations. For more information about asynchronous -Javascript, see the MDN web documentation on -`Asynchronous Javascript `_. +JavaScript, see the MDN web documentation on +`Asynchronous JavaScript `_. This section describes ``Promises`` that you can use with the Node.js driver to access the results of your method calls to your MongoDB cluster. diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index c8c4d59f1..369385937 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -133,8 +133,9 @@ Version 6.0 Breaking Changes callback returns. In previous driver versions, this method returns the server command response, which varies depending on the MongoDB Server version or type that the driver connects to. To learn more - about transactions, see the :ref:`node-usage-txns` usage - examples and the :ref:`nodejs-transactions` guide. + about transactions, see the :ref:`Convenient Transaction API + ` and :ref:`Core API ` guides + and the :ref:`nodejs-transactions` guide. - Raised the optional ``kerberos`` dependency minimum version to 2.0.1 and removed support for version 1.x. - Raised the optional ``zstd`` dependency minimum version to 1.1.0. diff --git a/source/typescript.txt b/source/typescript.txt index de1ee0cdc..16418170d 100644 --- a/source/typescript.txt +++ b/source/typescript.txt @@ -1,9 +1,9 @@ .. _node-fundamentals-typescript: .. _node-typescript: -========== -TypeScript -========== +=================================== +TypeScript Features and Limitations +=================================== .. facet:: :name: genre From e8bb90f7a0543423ac63c25e26f6371df28402a0 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 29 Apr 2025 16:27:30 -0400 Subject: [PATCH 25/26] add back old refs --- source/connect.txt | 1 + source/crud/bulk-write.txt | 1 + source/monitoring-and-logging/change-streams.txt | 1 + 3 files changed, 3 insertions(+) diff --git a/source/connect.txt b/source/connect.txt index 7ef488cca..3efe1f3eb 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -1,4 +1,5 @@ .. _node-connect: +.. _node-connection: ================== Connect to MongoDB diff --git a/source/crud/bulk-write.txt b/source/crud/bulk-write.txt index 100204b56..62a65590a 100644 --- a/source/crud/bulk-write.txt +++ b/source/crud/bulk-write.txt @@ -1,4 +1,5 @@ .. _node-bulk-write: +.. _node-fundamentals-bulk: =============== Bulk Operations diff --git a/source/monitoring-and-logging/change-streams.txt b/source/monitoring-and-logging/change-streams.txt index 9833a7c1a..baeb054da 100644 --- a/source/monitoring-and-logging/change-streams.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -1,4 +1,5 @@ .. _node-change-streams: +.. _node-usage-watch: ================================ Monitor Data with Change Streams From eaccf25a4ec3b787c3066783572b1efbcbf31a22 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 29 Apr 2025 16:34:11 -0400 Subject: [PATCH 26/26] get started --- source/get-started.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/get-started.txt b/source/get-started.txt index 9aa18ee8a..70d1b73a5 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -1,8 +1,8 @@ .. _node-get-started: -======================================= -Getting Started with the Node.js Driver -======================================= +=================================== +Get Started with the Node.js Driver +=================================== .. facet:: :name: genre