diff --git a/config/redirects b/config/redirects index 33fb30c3c..f7f8c8a3c 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 d54cc2af3..000000000 --- a/source/archive-reference-files/collations.txt +++ /dev/null @@ -1,314 +0,0 @@ -.. _node-fundamentals-collations: - -========== -Collations -========== - -.. 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 94f8b753a..000000000 --- a/source/archive-reference-files/quick-start/connect-to-mongodb.txt +++ /dev/null @@ -1,78 +0,0 @@ -.. _node-quick-start-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 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 148e2bae4..000000000 --- a/source/archive-reference-files/quick-start/create-a-connection-string.txt +++ /dev/null @@ -1,62 +0,0 @@ -.. _node-quick-start-connection-string: - -========================== -Create a Connection String -========================== - -You can connect to your MongoDB deployment by providing a -**connection URI**, also called a *connection string*, which -instructs the driver on how to connect to a MongoDB deployment -and how to behave while connected. - -The connection string includes the hostname or IP address and -port of your deployment, the authentication mechanism, user credentials -when applicable, and connection options. - -To connect to an instance or deployment not hosted on Atlas, see -:ref:`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:`Database` section and click the :guilabel:`Connect` button - for your new deployment. - - .. figure:: /includes/figures/atlas_connection_select_cluster.png - :alt: The connect button in the clusters section of the Atlas UI - - Proceed to the :guilabel:`Connect your application` section and select - "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. - - Deselect the :guilabel:`Include full driver code example` to view - the connection string. - - .. step:: Copy your Connection String - - Click the button on the right of the connection string to copy it to - your clipboard as shown in the following screenshot: - - .. figure:: /includes/figures/atlas_connection_copy_string_node.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 2bd33caff..000000000 --- a/source/archive-reference-files/quick-start/create-a-deployment.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. _node-quick-start-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 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 afd316859..000000000 --- a/source/archive-reference-files/quick-start/download-and-install.txt +++ /dev/null @@ -1,62 +0,0 @@ -.. _node-quick-start-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 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 f15672dff..000000000 --- a/source/archive-reference-files/quick-start/next-steps.txt +++ /dev/null @@ -1,19 +0,0 @@ -.. _node-quick-start-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. diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 9d0eb1ff3..827cf40fa 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -16,7 +16,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 fe1e2566d..4175bbacf 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 @@ -166,8 +166,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 504c91f67..f4e4be24b 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 +============================== .. default-domain:: mongodb 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 d35adc51d..a72a47703 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -78,6 +78,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 e60f2a685..000000000 --- a/source/fundamentals.txt +++ /dev/null @@ -1,26 +0,0 @@ -============ -Fundamentals -============ - -.. 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 d1801ba0b..000000000 --- a/source/fundamentals/bson/undefined-values.txt +++ /dev/null @@ -1,127 +0,0 @@ -.. _node-undefined-values: - -================ -Undefined Values -================ - -.. 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 1e2adc7a8..000000000 --- a/source/fundamentals/bson/utf8-validation.txt +++ /dev/null @@ -1,118 +0,0 @@ -.. _nodejs-utf-8-validation: - -================ -UTF-8 Validation -================ - -.. 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 c728a2040..000000000 --- a/source/fundamentals/crud/read-operations/limit.txt +++ /dev/null @@ -1,136 +0,0 @@ -.. _node-fundamentals-limit: - -==================================== -Limit the Number of Returned Results -==================================== - -.. 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 edb983124..000000000 --- a/source/fundamentals/crud/read-operations/skip.txt +++ /dev/null @@ -1,92 +0,0 @@ -.. _node-fundamentals-skip: - -===================== -Skip Returned 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 d67c6b437..000000000 --- a/source/fundamentals/crud/read-operations/sort.txt +++ /dev/null @@ -1,116 +0,0 @@ -.. _node-fundamentals-sort: - -============ -Sort Results -============ - -.. 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 51cdbfbac..4aa926ac3 100644 --- a/source/monitoring-and-logging/change-streams.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -91,7 +91,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 94% rename from source/fundamentals/promises.txt rename to source/promises.txt index c20e0fc43..dc2b21c49 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 @@ -20,15 +20,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 05be1daac..fd34594df 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -132,8 +132,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 417a17e22..ef6b93f1d 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