diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 483dc91b..2baccd86 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -2,4 +2,156 @@ ========================= Run an Atlas Search Query -========================= \ No newline at end of file +========================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene + :description: Learn about how to use Atlas Search in the {+driver-long+}. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +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 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. To learn more about +aggregation operations and builders, see the :ref:`kotlin-sync-aggregation` 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. + +.. note:: Only Available on Atlas for MongoDB v4.2 and later + + 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 :atlas:`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 +index, see the :ref:`kotlin-sync-atlas-search-index-create` 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/atlas-search.kt + :start-after: begin-atlas-search + :end-before: end-atlas-search + :language: kotlin + :dedent: + + .. output:: + :language: console + :visible: false + + {"_id": {"$oid": "..."}, "title": "Alabama Moon"} + {"_id": {"$oid": "..."}, "title": "Crazy in Alabama"} + {"_id": {"$oid": "..."}, "title": "Sweet Home Alabama"} + +Atlas Search Metadata +--------------------- + +Use the ``searchMeta()`` method to create a :manual:`$searchMeta +` pipeline stage, which returns +only the metadata from 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. + +The following example shows the ``near`` metadata for an Atlas Search +aggregation stage: + +.. literalinclude:: /includes/aggregation/search-meta-agg.kt + :start-after: // begin atlasSearchMeta + :end-before: // end atlasSearchMeta + :language: kotlin + :dedent: + +.. _kotlin-atlas-search-helpers: + +Create Pipeline Search Stages +----------------------------- + +.. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst + + .. replacement:: as-idx-link + + the :ref:`kotlin-sync-atlas-search-index-create` section of the Indexes guide + + .. replacement:: atlas-query-operators-example + + .. io-code-block:: + + .. input:: /includes/aggregation/aggregation.kt + :language: kotlin + :start-after: // start-atlas-searchoperator-helpers + :end-before: // end-atlas-searchoperator-helpers + :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 +---------------------- + +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: + +- `aggregate() <{+driver-api+}/-mongo-collection/aggregate.html>`__ +- `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__ +- `Aggregates.searchMeta() <{+core-api+}/client/model/Aggregates.html#searchMeta(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 diff --git a/source/includes/aggregation/search-meta-agg.kt b/source/includes/aggregation/search-meta-agg.kt new file mode 100644 index 00000000..0ec67aab --- /dev/null +++ b/source/includes/aggregation/search-meta-agg.kt @@ -0,0 +1,42 @@ +package org.example + +import com.mongodb.ConnectionString +import com.mongodb.kotlin.client.MongoClient +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.Aggregates.searchMeta +import com.mongodb.client.model.search.SearchOperator +import com.mongodb.client.model.search.SearchPath.fieldPath +import com.mongodb.kotlin.client.MongoCollection +import org.bson.Document + +fun runAtlasTextSearchMeta(collection: MongoCollection) { + val textSearchMeta = + // begin atlasSearchMeta + searchMeta( + SearchOperator.near(2010, 1, fieldPath("year")) + ) + // end atlasSearchMeta + + val aggregateStages = listOf(textSearchMeta) + println("aggregateStages: $aggregateStages") + + collection.aggregate(aggregateStages).forEach { result -> + println(result) + } +} + +fun main() { + val uri = "" + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .retryWrites(true) + .build() + + MongoClient.create(settings).use { mongoClient -> + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + + runAtlasTextSearchMeta(collection) + } +} \ No newline at end of file diff --git a/source/includes/atlas-search.kt b/source/includes/atlas-search.kt new file mode 100644 index 00000000..53c0b628 --- /dev/null +++ b/source/includes/atlas-search.kt @@ -0,0 +1,41 @@ +// Runs an Atlas Search query by using the Kotlin sync driver + +package org.example + +import com.mongodb.ConnectionString +import com.mongodb.kotlin.client.MongoClient +import com.mongodb.MongoClientSettings +import com.mongodb.client.model.Aggregates.project +import com.mongodb.client.model.Aggregates.search +import com.mongodb.client.model.Projections +import com.mongodb.client.model.search.SearchOperator +import com.mongodb.client.model.search.SearchPath.fieldPath +import org.bson.Document +import org.bson.conversions.Bson + +fun main() { + val uri = "" + + val settings = MongoClientSettings.builder() + .applyConnectionString(ConnectionString(uri)) + .retryWrites(true) + .build() + + val mongoClient = MongoClient.create(settings) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + + // begin-atlas-search + val pipeline: List = listOf( + search(SearchOperator.text( + fieldPath("title"), "Alabama")), + project(Projections.include("title")) + ) + + val results = collection.aggregate(pipeline) + + results.forEach { doc -> + println(doc.toJson()) + } + // end-atlas-search +} \ No newline at end of file