diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 0b5d2c5cc..b7d263c2e 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,60 @@ 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 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 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 ``near`` 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)>`__. + +.. _java-atlas-search-helpers: + +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:: + + .. input:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java + :language: java + :start-after: // begin atlasHelperMethods + :end-before: // end atlasHelperMethods + :dedent: + + .. output:: + :language: console + :visible: false + + {"_id": ..., "genres": ["Comedy", "Romance"], "title": "Love at First Bite", "year": 1979} + {"_id": ..., "genres": ["Comedy", "Drama"], "title": "Love Affair", "year": 1994} + Additional Information ---------------------- @@ -105,3 +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>`__ 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 593507042..c39a09230 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,7 +13,8 @@ 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 = ""; @@ -24,14 +24,14 @@ 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 +40,65 @@ 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 runAtlasSearchWithSearchHelperMethods(MongoCollection collection) { + // begin atlasHelperMethods + List pipeline = new ArrayList<>(); + + pipeline.add(Aggregates.search( + SearchOperator.compound() + .filter( + List.of( + SearchOperator.in(fieldPath("genres"), "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") + )); + + AggregateIterable results = collection.aggregate(pipeline); + results.forEach(doc -> System.out.println(doc.toJson())); + // end atlasHelperMethods + } + + /* + * 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,12 +107,12 @@ 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)); @@ -77,7 +129,9 @@ 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); + // runAtlasSearchWithSearchHelperMethods(collection); } } } diff --git a/source/references/whats-new.txt b/source/references/whats-new.txt index d565b6d36..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` guide + the :ref:`java-atlas-search-helpers` section of the Atlas Search guide .. _java-version-5.3: