DOCSP-47824: Atlas search

source/atlas-search.txt

@@ -18,4 +18,86 @@ 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 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 performs an Atlas Search query by calling the
+``aggregate()`` method and passing the following pipeline stage
+builders:
+
+- ``Aggregates.search()``: Specifies a search query for documents in which
+  the ``title`` field contains the word ``"Alabama"``
+- ``Aggregates.project()``: Projects the ``title`` field of each matching document
+
+.. 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
+
+        }
+    }
+}