From 246c0991e43d55e8242619cbd75c45d3f0fa7198 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 25 Feb 2025 16:11:52 -0500 Subject: [PATCH 1/6] DOCSP-47824: Atlas search --- source/atlas-search.txt | 81 +++++++++++++++++++++++++++++++- source/includes/AtlasSearch.java | 36 ++++++++++++++ 2 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 source/includes/AtlasSearch.java diff --git a/source/atlas-search.txt b/source/atlas-search.txt index a21049881..fc870e4b4 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -18,4 +18,83 @@ Atlas Search :depth: 2 :class: singlecol -See :atlas:`Atlas Search ` in the MongoDB Atlas documentation. \ No newline at end of file +Overview +-------- + +In this guide, you can learn how to use the **Atlas Search** feature 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. + +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 ``Aggregates.search`` builder to +create a ``$search`` pipeline stage and specify your search. 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. + +Sample Data +~~~~~~~~~~~ + +The example in this section 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. + +Atlas Search Example +~~~~~~~~~~~~~~~~~~~~ + +This example performs an Atlas Search query by calling the +``aggregate()`` method and passing the following pipeline stages: + +- ``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 ` + 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 methods and pipeline stages 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)>`__ diff --git a/source/includes/AtlasSearch.java b/source/includes/AtlasSearch.java new file mode 100644 index 000000000..1ecc0b31a --- /dev/null +++ b/source/includes/AtlasSearch.java @@ -0,0 +1,36 @@ +// Creates and uses Atlas Search indexes 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 = ""; + + try (MongoClient mongoClient = MongoClients.create(uri)) { + MongoDatabase database = mongoClient.getDatabase("sample_mflix"); + MongoCollection collection = database.getCollection("movies"); + + // 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 + + } + } +} From 7e6600aa059a2770b41d082824ba81add9434f18 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 25 Feb 2025 16:21:00 -0500 Subject: [PATCH 2/6] fixes --- source/atlas-search.txt | 33 ++++++++++++++++---------------- source/includes/AtlasSearch.java | 21 ++++++++++---------- 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index fc870e4b4..d0dcdc3fd 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -25,12 +25,20 @@ In this guide, you can learn how to use the **Atlas Search** feature on a collec 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 on a collection. You can use ``Aggregates.search`` builder to -create a ``$search`` pipeline stage and specify your search. Then, call +Atlas Search on a collection. You can use the ``Aggregates.search()`` builder +method to create a ``$search`` pipeline stage and specify your search. Then, call the ``aggregate()`` method and pass your pipeline as a parameter. .. tip:: @@ -42,23 +50,16 @@ 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. -Sample Data -~~~~~~~~~~~ - -The example in this section 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. - Atlas Search Example ~~~~~~~~~~~~~~~~~~~~ This example performs an Atlas Search query by calling the -``aggregate()`` method and passing the following pipeline stages: +``aggregate()`` method and passing the following pipeline stage +builders: -- ``Aggregates.search``: Specifies a search query for documents in which +- ``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 +- ``Aggregates.project()``: Projects the ``title`` field of each matching document .. io-code-block:: :copyable: @@ -92,9 +93,9 @@ in the Atlas documentation. API Documentation ~~~~~~~~~~~~~~~~~ -To learn more about the methods and pipeline stages mentioned in this guide, see +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)>`__ +- `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)>`__ diff --git a/source/includes/AtlasSearch.java b/source/includes/AtlasSearch.java index 1ecc0b31a..bfe8b0304 100644 --- a/source/includes/AtlasSearch.java +++ b/source/includes/AtlasSearch.java @@ -1,4 +1,4 @@ -// Creates and uses Atlas Search indexes by using the Java driver +// Runs an Atlas Search query by using the Java driver package org.example; @@ -15,22 +15,23 @@ public class AtlasSearch { public static void main(String[] args) { - String uri = ""; + String uri = ""; try (MongoClient mongoClient = MongoClients.create(uri)) { MongoDatabase database = mongoClient.getDatabase("sample_mflix"); MongoCollection 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())); + 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 - + } } } From 03b11fc2ba039ac59670150699e4e4a2f1b15e3b Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 25 Feb 2025 16:25:16 -0500 Subject: [PATCH 3/6] reword --- source/atlas-search.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index d0dcdc3fd..207e35f9a 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -38,8 +38,8 @@ 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 and specify your search. Then, call -the ``aggregate()`` method and pass your pipeline as a parameter. +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:: From 27f00b397b9059b1ea203c8745379c732048a4c4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 26 Feb 2025 16:07:43 -0500 Subject: [PATCH 4/6] SA feedback --- source/atlas-search.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 207e35f9a..128b2315f 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -21,9 +21,11 @@ Atlas Search Overview -------- -In this guide, you can learn how to use the **Atlas Search** feature 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. +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 ~~~~~~~~~~~ From e2c533202ea388f4ddfa36e79246b13d7867a124 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 26 Feb 2025 16:13:08 -0500 Subject: [PATCH 5/6] typo --- source/atlas-search.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 128b2315f..1898e1f37 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -21,7 +21,7 @@ Atlas Search Overview -------- -In this guide, you can learn how to use the {+driver-short} to +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 From 7b58d7a647a4561f326a6945aadb7501f2eef79c Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 19 Mar 2025 16:35:35 -0400 Subject: [PATCH 6/6] tech review --- source/atlas-search.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 1898e1f37..1190644a2 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -39,7 +39,7 @@ 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 +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. @@ -55,13 +55,17 @@ 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: +This example runs an Atlas Search query by performing the +following actions: -- ``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 +- 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: