From c03459893130690822953cace31f642b726b7a00 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 19 Mar 2025 11:10:51 -0400 Subject: [PATCH 01/15] atlas search operators --- source/atlas-search.txt | 24 ++++++++ .../AggregateSearchBuilderExample.java | 56 ++++++++++++++----- source/references/whats-new.txt | 4 ++ 3 files changed, 69 insertions(+), 15 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 0b5d2c5cc..dbf69f6a0 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -105,3 +105,27 @@ the following API documentation: - `MongoCollection.aggregate() <{+driver-api+}/MongoCollection.html#aggregate(java.util.List)>`__ - `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__ - `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ + +In this guide, you can learn how to use Atlas Search +in the {+driver-short+}. For more information about Atlas Search and its +benefits, see the :atlas:`Atlas Search ` guide. + +Atlas Search enables advanced search functionality for your applications without any additional management or +separate search system alongside your database. Atlas Search queries take the +form of an :ref:`aggregation pipeline ` stage. + +The following operators: + + - ``phrase`` + + - ``regex`` + + - ``queryString`` + + - ``equals`` + + - ``moreLikeThis`` + + - ``in`` + + - ``wildcard`` diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index 593507042..adb398604 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -1,6 +1,5 @@ -package fundamentals.builders; +package org.example; -import java.util.Arrays; import java.util.List; import org.bson.Document; @@ -14,24 +13,26 @@ import com.mongodb.client.model.Filters; import com.mongodb.client.model.Projections; import com.mongodb.client.model.search.SearchOperator; -import com.mongodb.client.model.search.SearchPath; + +import static com.mongodb.client.model.search.SearchPath.fieldPath; + public class AggregateSearchBuilderExample { - private static final String CONNECTION_URI = ""; + private static final String CONNECTION_URI = ""; // Match aggregation private static void runMatch(MongoCollection collection) { Bson matchStage = Aggregates.match(Filters.eq("title", "Future")); Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released"))); - List aggregateStages = Arrays.asList(matchStage, projection); + List aggregateStages = List.of(matchStage, projection); System.out.println("aggregateStages: " + aggregateStages); collection.aggregate( aggregateStages - ).forEach(result -> System.out.println(result)); + ).forEach(result -> System.out.println(result)); } - /* + /* * Atlas text search aggregation * Requires Atlas cluster and full text search index * See https://www.mongodb.com/docs/atlas/atlas-search/tutorial/ for more info on requirements @@ -40,13 +41,37 @@ private static void runAtlasTextSearch(MongoCollection collection) { // begin atlasTextSearch Bson textSearch = Aggregates.search( SearchOperator.text( - SearchPath.fieldPath("title"), "Future")); + fieldPath("title"), "Future")); // end atlasTextSearch // To condense result data, add this projection into the pipeline // Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released"))); - List aggregateStages = Arrays.asList(textSearch); + List aggregateStages = List.of(textSearch); + System.out.println("aggregateStages: " + aggregateStages); + + System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain()); + collection.aggregate(aggregateStages).forEach(result -> System.out.println(result)); + } + + /* + * Atlas search aggregation + * Requires Atlas cluster and full text search index + * See https://www.mongodb.com/docs/atlas/atlas-search/tutorial/ for more info on requirements + */ + private static void runAtlasSearch(MongoCollection collection) { + // begin atlasSearch + Bson search_stage = Aggregates.search( + SearchOperator.compound() + .filter(List.of(SearchOperator.text(fieldPath("genres"), "Drama"))) + .must(List.of(SearchOperator.phrase(fieldPath("cast"), "keanu reeves"))) + ); + // end atlasSearch + + // To condense result data, add this projection into the pipeline + // Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released"))); + + List aggregateStages = List.of(search_stage); System.out.println("aggregateStages: " + aggregateStages); System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain()); @@ -55,19 +80,19 @@ private static void runAtlasTextSearch(MongoCollection collection) { private static void runAtlasTextSearchMeta(MongoCollection collection) { Bson textSearchMeta = - // begin atlasSearchMeta - Aggregates.searchMeta( - SearchOperator.near(2010, 1, SearchPath.fieldPath("year"))); + // begin atlasSearchMeta + Aggregates.searchMeta( + SearchOperator.near(2010, 1, fieldPath("year"))); // end atlasSearchMeta - List aggregateStages = Arrays.asList(textSearchMeta); + List aggregateStages = List.of(textSearchMeta); System.out.println("aggregateStages: " + aggregateStages); collection.aggregate(aggregateStages).forEach(result -> System.out.println(result)); } public static void main(String[] args) { - String uri = CONNECTION_URI; + String uri = CONNECTION_URI; try (MongoClient mongoClient = MongoClients.create(uri)) { MongoDatabase database = mongoClient.getDatabase("sample_mflix"); @@ -77,7 +102,8 @@ public static void main(String[] args) { // Uncomment the methods that correspond to what you're testing // runMatch(collection); // runAtlasTextSearch(collection); - runAtlasTextSearchMeta(collection); + runAtlasSearch(collection); + // runAtlasTextSearchMeta(collection); } } } diff --git a/source/references/whats-new.txt b/source/references/whats-new.txt index 197fd8e7e..85b20fd3c 100644 --- a/source/references/whats-new.txt +++ b/source/references/whats-new.txt @@ -54,7 +54,11 @@ and features: .. replacement:: atlas-query-operators +<<<<<<< HEAD the :ref:`java-atlas-search` guide +======= + the :ref:`java-atlas-search` page +>>>>>>> e82dac4 (atlas search operators) .. _java-version-5.3: From c19a62144c74ab5f6ce88f11ca1ecda11b201415 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 10:57:36 -0400 Subject: [PATCH 02/15] aggregation page --- source/atlas-search.txt | 119 +++++++++++++++++- source/builders/aggregates.txt | 8 +- .../AggregateSearchBuilderExample.java | 28 +++++ 3 files changed, 143 insertions(+), 12 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index dbf69f6a0..74902f138 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -30,10 +30,11 @@ search and which fields to index. Sample Data ~~~~~~~~~~~ -The example in this guide uses the ``movies`` collection in the ``sample_mflix`` +The examples in this guide use 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:`Get Started with Atlas ` guide. To learn more about +aggregation operations and builders, see the :ref:`java-aggregation` guide. Run an Atlas Search Query ------------------------- @@ -41,12 +42,16 @@ 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. +criteria. Then, call the ``aggregate()`` method and pass your pipeline as a +parameter. -.. tip:: +.. note:: Only Available on Atlas for MongoDB v4.2 and later - To learn more about aggregation operations and builders, see the :ref:`java-aggregation` - guide. + This aggregation pipeline operator is only available for collections hosted + on :atlas:`MongoDB Atlas ` clusters running v4.2 or later that are + covered by an :atlas:`Atlas search index `. + Learn more about the required setup and the functionality of this operator + from the :ref:`Atlas Search ` documentation. 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 @@ -90,6 +95,107 @@ following actions: Search queries, see :atlas:`Atlas Search Tutorials ` in the Atlas documentation. +Atlas Search Metadata +--------------------- + +Use the ``searchMeta()`` method to create a +:manual:`$searchMeta ` +pipeline stage which returns only the metadata part of the results from +Atlas full-text search queries. + +.. tip:: Only Available on Atlas for MongoDB v4.4.11 and later + + This aggregation pipeline operator is only available + on :atlas:`MongoDB Atlas ` clusters running v4.4.11 and later. For a + detailed list of version availability, see the MongoDB Atlas documentation + on :atlas:`$searchMeta `. + +The following example shows the ``count`` metadata for an Atlas search +aggregation stage: + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java + :start-after: // begin atlasSearchMeta + :end-before: // end atlasSearchMeta + :language: java + :dedent: + +Learn more about this helper from the +`searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__. + +SearchOperator Helper Methods +----------------------------- + +To make building pipeline stages easier, the {+driver-short+} provides helper methods +for the following operations: + +- :atlas:`autocomplete `: Performs a search for a + word or phrase that contains a sequence of characters from an incomplete + input string. + +- :atlas:`compound `: Combines two or more operators + into a single query. + +- :atlas:`equals ` (``equals()`` and ``equalsNull()``): Checks + whether a field matches a value you specify. + +- :atlas:`exists `: Tests if a path to a specified + indexed field name exists in a document. + +- :atlas:`in `: Performs a search for an array of BSON + number, date, boolean, objectId, uuid, or string values at the given path + and returns documents where the value of the field equals any value in the + specified array. + +- :atlas:`moreLikeThis `: Returns documents similar + to input documents. + +- :atlas:`near `: Supports querying and scoring numeric, + date, and GeoJSON point values. + +- :atlas:`phrase `: Performs a search for documents + containing an ordered sequence of terms using the analyzer specified in the + index configuration. + +- :atlas:`queryString `: Supports querying a + combination of indexed fields and values. + +- :atlas:`range ` (``numberRange()`` and ``dateRange()``): Supports + querying and scoring numeric, date, and string values. + +- :atlas:`regex `: Interprets the query field as a regular + expression. + +- :atlas:`text `: Performs a full-text search using the + analyzer that you specify in the index configuration. + +- :atlas:`wildcard `: Enables queries which use special + characters in the search string that can match any character. + +Example Pipeline Search Stage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: Atlas Sample Dataset + + This example uses the MongoDB Atlas sample dataset. Specifically, the + ``movies`` collection in the ``sample_mflix`` database. You can learn how + to set up your own free-tier Atlas cluster and how to load the sample dataset + in our :ref:`quick start guide `. + +The following code creates a search stage for a pipeline with the following filters: + +- Movies in the drama genre +- Movies that include Sylvester Stallone in the cast, accounting for possible misspellings +- Movies made between 1980 and 1989, inclusive +- Movies with titles that begin with the word ``"Rocky"`` + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java + :start-after: // begin atlasHelperMethods + :end-before: // end atlasHelperMethods + :language: java + :dedent: + +To learn more about the helper methods, see the `SearchOperator Interface API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/SearchOperator.html>`__. + Additional Information ---------------------- @@ -105,6 +211,7 @@ the following API documentation: - `MongoCollection.aggregate() <{+driver-api+}/MongoCollection.html#aggregate(java.util.List)>`__ - `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__ - `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ +- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__ In this guide, you can learn how to use Atlas Search in the {+driver-short+}. For more information about Atlas Search and its diff --git a/source/builders/aggregates.txt b/source/builders/aggregates.txt index 484ddfbb7..b4900d8d6 100644 --- a/source/builders/aggregates.txt +++ b/source/builders/aggregates.txt @@ -17,10 +17,6 @@ Aggregates Builders :depth: 2 :class: singlecol -.. toctree:: - - Atlas Vector Search - Overview -------- @@ -931,8 +927,8 @@ by the aggregate stage: See the `fill package API documentation <{+core-api+}/client/model/fill/package-summary.html>`__ for more information. -Atlas Full-Text Search ----------------------- +Atlas Search +------------ Use the ``search()`` method to create a :manual:`$search ` pipeline stage that specifies a full-text search of one or more fields. diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index adb398604..715ade748 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -54,6 +54,34 @@ private static void runAtlasTextSearch(MongoCollection collection) { collection.aggregate(aggregateStages).forEach(result -> System.out.println(result)); } + /* + * Atlas search aggregation + * Requires Atlas cluster and full text search index + * See https://www.mongodb.com/docs/atlas/atlas-search/tutorial/ for more info on requirements + */ + private static void runAtlasSearchWithSearchHelperMethods(MongoCollection collection) { + // begin atlasHelperMethods + Bson search_stage = Aggregates.search( + SearchOperator.compound() + .filter( + List.of( + SearchOperator.text(fieldPath("genres"), "Drama"), + SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"), + SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989), + SearchOperator.wildcard("Rocky *", fieldPath("title")) + ))); + // end atlasHelperMethods + + // To condense result data, add this projection into the pipeline + // Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released"))); + + List aggregateStages = List.of(searchStageFilters); + System.out.println("aggregateStages: " + aggregateStages); + + System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain()); + collection.aggregate(aggregateStages).forEach(result -> System.out.println(result)); + } + /* * Atlas search aggregation * Requires Atlas cluster and full text search index From d73ffcb6d6968b144480eff416055c1e3ab24ce7 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 11:00:19 -0400 Subject: [PATCH 03/15] formatting --- .../builders/AggregateSearchBuilderExample.java | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index 715ade748..82565eff6 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -13,12 +13,11 @@ import com.mongodb.client.model.Filters; import com.mongodb.client.model.Projections; import com.mongodb.client.model.search.SearchOperator; - import static com.mongodb.client.model.search.SearchPath.fieldPath; public class AggregateSearchBuilderExample { - private static final String CONNECTION_URI = ""; + private static final String CONNECTION_URI = ""; // Match aggregation private static void runMatch(MongoCollection collection) { @@ -120,7 +119,7 @@ private static void runAtlasTextSearchMeta(MongoCollection collection) } public static void main(String[] args) { - String uri = CONNECTION_URI; + String uri = CONNECTION_URI; try (MongoClient mongoClient = MongoClients.create(uri)) { MongoDatabase database = mongoClient.getDatabase("sample_mflix"); From 9bdca5918fc5e67c55557d1444d4c20dc50e88d0 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 11:59:39 -0400 Subject: [PATCH 04/15] table format --- source/atlas-search.txt | 69 +++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 30 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 74902f138..27dbcdb1a 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -128,48 +128,57 @@ SearchOperator Helper Methods To make building pipeline stages easier, the {+driver-short+} provides helper methods for the following operations: -- :atlas:`autocomplete `: Performs a search for a - word or phrase that contains a sequence of characters from an incomplete - input string. +.. list-table:: + :widths: 40 60 + :header-rows: 1 -- :atlas:`compound `: Combines two or more operators - into a single query. + * - Operation + - Description -- :atlas:`equals ` (``equals()`` and ``equalsNull()``): Checks - whether a field matches a value you specify. + * - :atlas:`autocomplete ` + - Performs a search for a word or phrase that contains a sequence of + characters from an incomplete input string. -- :atlas:`exists `: Tests if a path to a specified - indexed field name exists in a document. + * - :atlas:`compound ` + - Combines two or more operators into a single query. -- :atlas:`in `: Performs a search for an array of BSON - number, date, boolean, objectId, uuid, or string values at the given path - and returns documents where the value of the field equals any value in the - specified array. + * - :atlas:`equals ` (``equals()`` and ``equalsNull()``) + - Checks whether a field matches a value you specify. -- :atlas:`moreLikeThis `: Returns documents similar - to input documents. + * - :atlas:`exists ` + - Tests if a path to a specified indexed field name exists in a document. -- :atlas:`near `: Supports querying and scoring numeric, - date, and GeoJSON point values. + * - :atlas:`in ` + - Performs a search for an array of BSON number, date, boolean, objectId, + uuid, or string values at the given path and returns documents where the + value of the field equals any value in the specified array. -- :atlas:`phrase `: Performs a search for documents - containing an ordered sequence of terms using the analyzer specified in the - index configuration. + * - :atlas:`moreLikeThis ` + - Returns documents similar to input documents. -- :atlas:`queryString `: Supports querying a - combination of indexed fields and values. + * - :atlas:`near ` + - Supports querying and scoring numeric, date, and GeoJSON point values. -- :atlas:`range ` (``numberRange()`` and ``dateRange()``): Supports - querying and scoring numeric, date, and string values. + * - :atlas:`phrase ` + - Performs a search for documents containing an ordered sequence of terms + using the analyzer specified in the index configuration. -- :atlas:`regex `: Interprets the query field as a regular - expression. + * - :atlas:`queryString ` + - Supports querying a combination of indexed fields and values. -- :atlas:`text `: Performs a full-text search using the - analyzer that you specify in the index configuration. + * - :atlas:`range ` (``numberRange()`` and ``dateRange()``) + - Supports querying and scoring numeric, date, and string values. -- :atlas:`wildcard `: Enables queries which use special - characters in the search string that can match any character. + * - :atlas:`regex ` + - Interprets the query field as a regular expression. + + * - :atlas:`text ` + - Performs a full-text search using the analyzer that you specify in the + index configuration. + + * - :atlas:`wildcard ` + - Enables queries which use special characters in the search string that + can match any character. Example Pipeline Search Stage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From dfec015ac6a5c80ca6792e2079b82e4d111f292a Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 21 Mar 2025 12:08:29 -0400 Subject: [PATCH 05/15] references --- source/atlas-search.txt | 12 ++++++++---- source/references/whats-new.txt | 4 ---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 27dbcdb1a..bb5834c08 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -122,6 +122,8 @@ aggregation stage: Learn more about this helper from the `searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__. +.. _java-atlas-search-helpers: + SearchOperator Helper Methods ----------------------------- @@ -142,8 +144,9 @@ for the following operations: * - :atlas:`compound ` - Combines two or more operators into a single query. - * - :atlas:`equals ` (``equals()`` and ``equalsNull()``) - - Checks whether a field matches a value you specify. + * - :atlas:`equals ` + - Checks whether a field matches a value you specify. + Maps to the ``equals()`` and ``equalsNull()`` methods * - :atlas:`exists ` - Tests if a path to a specified indexed field name exists in a document. @@ -166,8 +169,9 @@ for the following operations: * - :atlas:`queryString ` - Supports querying a combination of indexed fields and values. - * - :atlas:`range ` (``numberRange()`` and ``dateRange()``) - - Supports querying and scoring numeric, date, and string values. + * - :atlas:`range ` + - Supports querying and scoring numeric, date, and string values. + Maps to the ``numberRange()`` and ``dateRange()`` methods * - :atlas:`regex ` - Interprets the query field as a regular expression. diff --git a/source/references/whats-new.txt b/source/references/whats-new.txt index 85b20fd3c..6063a5a20 100644 --- a/source/references/whats-new.txt +++ b/source/references/whats-new.txt @@ -54,11 +54,7 @@ and features: .. replacement:: atlas-query-operators -<<<<<<< HEAD - the :ref:`java-atlas-search` guide -======= the :ref:`java-atlas-search` page ->>>>>>> e82dac4 (atlas search operators) .. _java-version-5.3: From ae9e97746b92389c76a1431aaf92dd5410a6c912 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 24 Mar 2025 15:40:00 -0400 Subject: [PATCH 06/15] JS feedback --- source/atlas-search.txt | 14 ++++++-------- .../builders/AggregateSearchBuilderExample.java | 2 +- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index bb5834c08..0c653f519 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -98,19 +98,18 @@ following actions: Atlas Search Metadata --------------------- -Use the ``searchMeta()`` method to create a -:manual:`$searchMeta ` -pipeline stage which returns only the metadata part of the results from -Atlas full-text search queries. +Use the ``searchMeta()`` method to create a :manual:`$searchMeta +` pipeline stage, which returns +only the metadata from of the Atlas full-text search results. .. tip:: Only Available on Atlas for MongoDB v4.4.11 and later - This aggregation pipeline operator is only available + This aggregation pipeline operator is available only on :atlas:`MongoDB Atlas ` clusters running v4.4.11 and later. For a detailed list of version availability, see the MongoDB Atlas documentation on :atlas:`$searchMeta `. -The following example shows the ``count`` metadata for an Atlas search +The following example shows the ``near`` metadata for an Atlas search aggregation stage: .. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -127,8 +126,7 @@ Learn more about this helper from the SearchOperator Helper Methods ----------------------------- -To make building pipeline stages easier, the {+driver-short+} provides helper methods -for the following operations: +The {+driver-short+} provides helper methods for the following operations: .. list-table:: :widths: 40 60 diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index 82565eff6..b5286bd93 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -67,7 +67,7 @@ private static void runAtlasSearchWithSearchHelperMethods(MongoCollection Date: Thu, 27 Mar 2025 16:06:06 -0400 Subject: [PATCH 07/15] use shared doc --- source/atlas-search.txt | 89 +++++++---------------------------------- 1 file changed, 14 insertions(+), 75 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 0c653f519..ff9499ade 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -126,86 +126,25 @@ Learn more about this helper from the SearchOperator Helper Methods ----------------------------- -The {+driver-short+} provides helper methods for the following operations: +.. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst -.. list-table:: - :widths: 40 60 - :header-rows: 1 + .. replacement:: atlas-query-operators-example - * - Operation - - Description + .. code-block:: java - * - :atlas:`autocomplete ` - - Performs a search for a word or phrase that contains a sequence of - characters from an incomplete input string. + Bson searchStageFilters = Aggregates.search( + SearchOperator.compound() + .filter( + List.of( + SearchOperator.text(fieldPath("genres"), "Drama"), + SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"), + SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989), + SearchOperator.wildcard(fieldPath("title"),"Rocky *") + ))); - * - :atlas:`compound ` - - Combines two or more operators into a single query. + .. replacement:: searchoperator-interface-api-docs - * - :atlas:`equals ` - - Checks whether a field matches a value you specify. - Maps to the ``equals()`` and ``equalsNull()`` methods - - * - :atlas:`exists ` - - Tests if a path to a specified indexed field name exists in a document. - - * - :atlas:`in ` - - Performs a search for an array of BSON number, date, boolean, objectId, - uuid, or string values at the given path and returns documents where the - value of the field equals any value in the specified array. - - * - :atlas:`moreLikeThis ` - - Returns documents similar to input documents. - - * - :atlas:`near ` - - Supports querying and scoring numeric, date, and GeoJSON point values. - - * - :atlas:`phrase ` - - Performs a search for documents containing an ordered sequence of terms - using the analyzer specified in the index configuration. - - * - :atlas:`queryString ` - - Supports querying a combination of indexed fields and values. - - * - :atlas:`range ` - - Supports querying and scoring numeric, date, and string values. - Maps to the ``numberRange()`` and ``dateRange()`` methods - - * - :atlas:`regex ` - - Interprets the query field as a regular expression. - - * - :atlas:`text ` - - Performs a full-text search using the analyzer that you specify in the - index configuration. - - * - :atlas:`wildcard ` - - Enables queries which use special characters in the search string that - can match any character. - -Example Pipeline Search Stage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: Atlas Sample Dataset - - This example uses the MongoDB Atlas sample dataset. Specifically, the - ``movies`` collection in the ``sample_mflix`` database. You can learn how - to set up your own free-tier Atlas cluster and how to load the sample dataset - in our :ref:`quick start guide `. - -The following code creates a search stage for a pipeline with the following filters: - -- Movies in the drama genre -- Movies that include Sylvester Stallone in the cast, accounting for possible misspellings -- Movies made between 1980 and 1989, inclusive -- Movies with titles that begin with the word ``"Rocky"`` - -.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java - :start-after: // begin atlasHelperMethods - :end-before: // end atlasHelperMethods - :language: java - :dedent: - -To learn more about the helper methods, see the `SearchOperator Interface API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/SearchOperator.html>`__. + the `SearchOperator Interface API documentation <{+core-api+}/com/mongodb/client/model/search/SearchOperator.html>`__ Additional Information ---------------------- From c27bb180a0bf3fdef1f3ef30338382df8dde78f1 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Thu, 27 Mar 2025 16:18:57 -0400 Subject: [PATCH 08/15] fix for new core-api variable --- 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 ff9499ade..23f8cfc17 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -144,7 +144,7 @@ SearchOperator Helper Methods .. replacement:: searchoperator-interface-api-docs - the `SearchOperator Interface API documentation <{+core-api+}/com/mongodb/client/model/search/SearchOperator.html>`__ + the `SearchOperator Interface API documentation <{+core-api+}/client/model/search/SearchOperator.html>`__ Additional Information ---------------------- From 1bc361748f7598b57734ee5f7e5cc182c9d6ca43 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 28 Mar 2025 16:07:53 -0400 Subject: [PATCH 09/15] eg updates --- source/atlas-search.txt | 26 +++++++++++-------- .../AggregateSearchBuilderExample.java | 24 +++++++++++------ 2 files changed, 31 insertions(+), 19 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 23f8cfc17..fd8546e50 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -130,17 +130,21 @@ SearchOperator Helper Methods .. replacement:: atlas-query-operators-example - .. code-block:: java - - Bson searchStageFilters = Aggregates.search( - SearchOperator.compound() - .filter( - List.of( - SearchOperator.text(fieldPath("genres"), "Drama"), - SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"), - SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989), - SearchOperator.wildcard(fieldPath("title"),"Rocky *") - ))); + .. io-code-block:: + + .. input:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java + :language: java + :start-after: // begin atlasHelperMethods + :end-before: // end atlasHelperMethods + :language: java + :dedent: + + .. output:: + :language: console + :visible: false + + Document{{_id=573a1397f29313caabce86db, genres=[Drama, Sport], cast=[Sylvester Stallone, Talia Shire, Burt Young, Carl Weathers], title=Rocky III, year=1982}} + Document{{_id=573a1398f29313caabce9af0, genres=[Drama, Sport], cast=[Sylvester Stallone, Talia Shire, Burt Young, Carl Weathers], title=Rocky IV, year=1985}} .. replacement:: searchoperator-interface-api-docs diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index b5286bd93..46a8f708e 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -60,15 +60,23 @@ private static void runAtlasTextSearch(MongoCollection collection) { */ private static void runAtlasSearchWithSearchHelperMethods(MongoCollection collection) { // begin atlasHelperMethods - Bson search_stage = Aggregates.search( + Bson searchStageFilters = Aggregates.search( SearchOperator.compound() - .filter( - List.of( - SearchOperator.text(fieldPath("genres"), "Drama"), - SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"), - SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989), - SearchOperator.wildcard(fieldPath("title"),"Rocky *") - ))); + .filter( + List.of( + SearchOperator.text(fieldPath("genres"), "Drama"), + SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"), + SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989), + SearchOperator.wildcard(fieldPath("title"),"Rocky *") + ))); + + Bson projection = Aggregates.project(Projections.fields( + Projections.include("title", "year", "genres", "cast") + )); + + List aggregateStages = List.of(searchStageFilters, projection); + collection.aggregate(aggregateStages).forEach(System.out::println); + // end atlasHelperMethods // To condense result data, add this projection into the pipeline From 904accdf646ccd0b770a449b1592be30fb1a2941 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 28 Mar 2025 22:25:35 -0400 Subject: [PATCH 10/15] rebase --- source/atlas-search.txt | 26 +------------------------- 1 file changed, 1 insertion(+), 25 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index fd8546e50..5995199f7 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -165,28 +165,4 @@ the following API documentation: - `MongoCollection.aggregate() <{+driver-api+}/MongoCollection.html#aggregate(java.util.List)>`__ - `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__ - `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ -- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__ - -In this guide, you can learn how to use Atlas Search -in the {+driver-short+}. For more information about Atlas Search and its -benefits, see the :atlas:`Atlas Search ` guide. - -Atlas Search enables advanced search functionality for your applications without any additional management or -separate search system alongside your database. Atlas Search queries take the -form of an :ref:`aggregation pipeline ` stage. - -The following operators: - - - ``phrase`` - - - ``regex`` - - - ``queryString`` - - - ``equals`` - - - ``moreLikeThis`` - - - ``in`` - - - ``wildcard`` +- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__ \ No newline at end of file From 99b53d4e9b93ffde5f1689f823293ddf2e759b48 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 28 Mar 2025 22:39:54 -0400 Subject: [PATCH 11/15] eg format --- source/atlas-search.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 5995199f7..cf0032849 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -123,8 +123,8 @@ Learn more about this helper from the .. _java-atlas-search-helpers: -SearchOperator Helper Methods ------------------------------ +Building a Pipeline Search Stage +-------------------------------- .. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst @@ -148,7 +148,7 @@ SearchOperator Helper Methods .. replacement:: searchoperator-interface-api-docs - the `SearchOperator Interface API documentation <{+core-api+}/client/model/search/SearchOperator.html>`__ + the `SearchOperator Interface API documentation <{+core-api+}/client/model/search/SearchOperator.html>`__ Additional Information ---------------------- From 9a81190187af10c58d857323e2d3e938e87b0d17 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 28 Mar 2025 22:49:08 -0400 Subject: [PATCH 12/15] format --- source/atlas-search.txt | 1 - source/builders/aggregates.txt | 8 ++++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index cf0032849..e20e5f13b 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -136,7 +136,6 @@ Building a Pipeline Search Stage :language: java :start-after: // begin atlasHelperMethods :end-before: // end atlasHelperMethods - :language: java :dedent: .. output:: diff --git a/source/builders/aggregates.txt b/source/builders/aggregates.txt index b4900d8d6..484ddfbb7 100644 --- a/source/builders/aggregates.txt +++ b/source/builders/aggregates.txt @@ -17,6 +17,10 @@ Aggregates Builders :depth: 2 :class: singlecol +.. toctree:: + + Atlas Vector Search + Overview -------- @@ -927,8 +931,8 @@ by the aggregate stage: See the `fill package API documentation <{+core-api+}/client/model/fill/package-summary.html>`__ for more information. -Atlas Search ------------- +Atlas Full-Text Search +---------------------- Use the ``search()`` method to create a :manual:`$search ` pipeline stage that specifies a full-text search of one or more fields. From 8a0d5b3848bc055e55b1771c70f06a048c57ed1d Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Sat, 29 Mar 2025 01:13:30 -0400 Subject: [PATCH 13/15] release reference --- source/references/whats-new.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/references/whats-new.txt b/source/references/whats-new.txt index 6063a5a20..dbf7bba3b 100644 --- a/source/references/whats-new.txt +++ b/source/references/whats-new.txt @@ -54,7 +54,7 @@ and features: .. replacement:: atlas-query-operators - the :ref:`java-atlas-search` page + the :ref:`java-atlas-search-helpers` section of the Atlas Search page. .. _java-version-5.3: From e71942e5111505d193332853053da0235ab765d6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 1 Apr 2025 16:14:56 -0400 Subject: [PATCH 14/15] WIP --- source/atlas-search.txt | 20 +++++----- source/crud/read-write-config.txt | 14 +++---- .../AggregateSearchBuilderExample.java | 39 ++++++++----------- source/references/whats-new.txt | 2 +- 4 files changed, 34 insertions(+), 41 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index e20e5f13b..b7d263c2e 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -123,11 +123,15 @@ Learn more about this helper from the .. _java-atlas-search-helpers: -Building a Pipeline Search Stage --------------------------------- +Create Pipeline Search Stages +----------------------------- .. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst + .. replacement:: as-idx-link + + the :ref:`java-search-indexes` section of the Indexes guide + .. replacement:: atlas-query-operators-example .. io-code-block:: @@ -141,13 +145,9 @@ Building a Pipeline Search Stage .. output:: :language: console :visible: false - - Document{{_id=573a1397f29313caabce86db, genres=[Drama, Sport], cast=[Sylvester Stallone, Talia Shire, Burt Young, Carl Weathers], title=Rocky III, year=1982}} - Document{{_id=573a1398f29313caabce9af0, genres=[Drama, Sport], cast=[Sylvester Stallone, Talia Shire, Burt Young, Carl Weathers], title=Rocky IV, year=1985}} - - .. replacement:: searchoperator-interface-api-docs - - the `SearchOperator Interface API documentation <{+core-api+}/client/model/search/SearchOperator.html>`__ + + {"_id": ..., "genres": ["Comedy", "Romance"], "title": "Love at First Bite", "year": 1979} + {"_id": ..., "genres": ["Comedy", "Drama"], "title": "Love Affair", "year": 1994} Additional Information ---------------------- @@ -164,4 +164,4 @@ the following API documentation: - `MongoCollection.aggregate() <{+driver-api+}/MongoCollection.html#aggregate(java.util.List)>`__ - `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__ - `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ -- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__ \ No newline at end of file +- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__ diff --git a/source/crud/read-write-config.txt b/source/crud/read-write-config.txt index b4172ed9c..dfcea8045 100644 --- a/source/crud/read-write-config.txt +++ b/source/crud/read-write-config.txt @@ -333,10 +333,10 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__ -- `MongoClientSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ -- `TransactionOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/TransactionOptions.html>`_ -- `startTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#startTransaction()>`_ -- `MongoDatabase <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html>`__ -- `MongoCollection <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html>`__ -- `TagSet <{+api+}/apidocs/mongodb-driver-core/com/mongodb/TagSet.html>`_ \ No newline at end of file +- `MongoClient <{+driver-api+}/MongoClient.html>`__ +- `MongoClientSettings <{+core-api+}/MongoClientSettings.html>`__ +- `TransactionOptions <{+core-api+}/TransactionOptions.html>`_ +- `startTransaction() <{+driver-api+}/ClientSession.html#startTransaction()>`_ +- `MongoDatabase <{+driver-api+}/MongoDatabase.html>`__ +- `MongoCollection <{+driver-api+}/MongoCollection.html>`__ +- `TagSet <{+core-api+}/TagSet.html>`_ diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index 46a8f708e..655d9eb3c 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -60,33 +60,25 @@ private static void runAtlasTextSearch(MongoCollection collection) { */ private static void runAtlasSearchWithSearchHelperMethods(MongoCollection collection) { // begin atlasHelperMethods - Bson searchStageFilters = Aggregates.search( + List pipeline = new ArrayList<>(); + + pipeline.add(Aggregates.search( SearchOperator.compound() .filter( - List.of( - SearchOperator.text(fieldPath("genres"), "Drama"), - SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"), - SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989), - SearchOperator.wildcard(fieldPath("title"),"Rocky *") - ))); - - Bson projection = Aggregates.project(Projections.fields( - Projections.include("title", "year", "genres", "cast") + Arrays.asList( + SearchOperator.in(fieldPath("genres"), Arrays.asList("Comedy")), + SearchOperator.phrase(fieldPath("fullplot"), "new york"), + SearchOperator.numberRange(fieldPath("year")).gtLt(1950, 2000), + SearchOperator.wildcard(fieldPath("title"), "Love *") + )))); + + pipeline.add(Aggregates.project( + Projections.include("title", "year", "genres") )); - List aggregateStages = List.of(searchStageFilters, projection); - collection.aggregate(aggregateStages).forEach(System.out::println); - + AggregateIterable results = collection.aggregate(pipeline); + results.forEach(doc -> System.out.println(doc.toJson())); // end atlasHelperMethods - - // To condense result data, add this projection into the pipeline - // Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released"))); - - List aggregateStages = List.of(searchStageFilters); - System.out.println("aggregateStages: " + aggregateStages); - - System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain()); - collection.aggregate(aggregateStages).forEach(result -> System.out.println(result)); } /* @@ -137,8 +129,9 @@ public static void main(String[] args) { // Uncomment the methods that correspond to what you're testing // runMatch(collection); // runAtlasTextSearch(collection); - runAtlasSearch(collection); + // runAtlasSearch(collection); // runAtlasTextSearchMeta(collection); + // runAtlasSearchWithSearchHelperMethods(collection); } } } diff --git a/source/references/whats-new.txt b/source/references/whats-new.txt index aad279a83..f8b290d27 100644 --- a/source/references/whats-new.txt +++ b/source/references/whats-new.txt @@ -58,7 +58,7 @@ and features: .. replacement:: atlas-query-operators - the :ref:`java-atlas-search-helpers` section of the Atlas Search page. + the :ref:`java-atlas-search-helpers` section of the Atlas Search guide .. _java-version-5.3: From 7b36f9fd40d319ba4ccb3aee87e801ef582ca95e Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 2 Apr 2025 10:28:27 -0400 Subject: [PATCH 15/15] use List.of() --- .../code-snippets/builders/AggregateSearchBuilderExample.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java index 655d9eb3c..c39a09230 100644 --- a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java +++ b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java @@ -65,8 +65,8 @@ private static void runAtlasSearchWithSearchHelperMethods(MongoCollection