diff --git a/source/atlas-search.txt b/source/atlas-search.txt index a21049881..1190644a2 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -18,4 +18,90 @@ 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 {+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 +~~~~~~~~~~~ + +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 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 ` + 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 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..bfe8b0304 --- /dev/null +++ b/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 = ""; + + 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())); + // end-atlas-search + + } + } +}