DOCSP-47824: Atlas search (#625)

* DOCSP-47824: Atlas search

* fixes

* reword

* SA feedback

* typo

* tech review

Author: norareidy

source/atlas-search.txt

@@ -18,4 +18,90 @@ Atlas Search
    :depth: 2
    :class: singlecol
 
-See :atlas:`Atlas Search </atlas-search/>` in the MongoDB Atlas documentation.
+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. You can use the ``Aggregates.search()`` builder
+method to create a ``$search`` pipeline stage, which specifies the search
+criteria. Then, call the ``aggregate()`` method and pass your pipeline as a parameter.
+
+.. tip:: 
+
+   To learn more about aggregation operations and builders, see the :ref:`java-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:`java-search-indexes` section in the Indexes guide. 
+
+Atlas Search Example
+~~~~~~~~~~~~~~~~~~~~
+
+This example runs an Atlas Search query by performing the
+following actions:
+
+- Constructs a ``$search`` stage by using the ``Aggregates.search()`` builder method,
+  instructing the driver to query for documents in which the ``title``
+  field contains the word ``"Alabama"``
+
+- Constructs a ``$project`` stage by using the ``Aggregates.project()`` builder method,
+  instructing 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/AtlasSearch.java
+      :start-after: begin-atlas-search
+      :end-before: end-atlas-search
+      :language: java
+      :dedent:
+
+   .. output:: 
+      :language: console
+      :visible: false
+
+      {"_id": {"$oid": "..."}, "title": "Alabama Moon"}
+      {"_id": {"$oid": "..."}, "title": "Crazy in Alabama"}
+      {"_id": {"$oid": "..."}, "title": "Sweet Home Alabama"}
+
+.. tip:: Java 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 methods mentioned in this guide, see
+the following API documentation:
+
+- `MongoCollection.aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__
+- `Aggregates.search() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__
+- `Aggregates.project() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__

source/includes/AtlasSearch.java

@@ -0,0 +1,37 @@
+// Runs an Atlas Search query by using the Java driver
+
+package org.example;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+import com.mongodb.client.model.Aggregates;
+import com.mongodb.client.model.Projections;
+import com.mongodb.client.model.search.SearchOperator;
+import com.mongodb.client.model.search.SearchPath;
+import org.bson.Document;
+import java.util.Arrays;
+
+public class AtlasSearch {
+    public static void main(String[] args) {
+        String uri = "<connection string>";
+
+        try (MongoClient mongoClient = MongoClients.create(uri)) {
+            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
+            MongoCollection<Document> collection = database.getCollection("movies");
+        
+        // Queries for documents that have a "title" value containing the word "Alabama"
+        // begin-atlas-search
+        collection.aggregate(
+            Arrays.asList(
+            	Aggregates.search(SearchOperator.text(
+                              SearchPath.fieldPath("title"), "Alabama")),
+                Aggregates.project(Projections.include("title"))
+            )
+        ).forEach(doc -> System.out.println(doc.toJson()));
+        // end-atlas-search
+        
+        }
+    }
+}