DOCSP-48384: Atlas search (mongodb#1041)

* DOCSP-48384: Atlas search

* edits

* tech feedback

Author: norareidy

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 </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 </sample-data>`. To learn how to
+create a free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` 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 </atlas-search/tutorials/>`
+   in the Atlas documentation.
+
+Additional Information
+----------------------
+
+To learn more about Atlas Search, see :atlas:`Atlas Search </atlas-search/>`
+in the Atlas documentation.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the ``aggregate()`` method, see the
+`API documentation <{+api+}/classes/Collection.html#aggregate>`__.

source/includes/atlas-search.js

@@ -0,0 +1,41 @@
+const { MongoClient } = require("mongodb");
+
+// Replace the placeholder with your connection string.
+const uri = "<connection string>";
+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);

source/index.txt

@@ -23,6 +23,7 @@ MongoDB Node Driver
   Data Formats </data-formats>
   Indexes </indexes>
   Run a Database Command </run-command>
+  Atlas Search </atlas-search>
   Monitoring and Logging </monitoring-and-logging>
   Security </security>
   Reference </reference>
@@ -85,6 +86,11 @@ Run a Database Command
 
 Learn how to run a database command in the :ref:`<node-run-command>` section.
 
+Atlas Search
+------------
+
+Learn how to run Atlas Search queries in the :ref:`<node-atlas-search>` section.
+
 Monitoring and Logging
 ----------------------