From 9764ff9a0d969610772e6e50ee871ccb51318a8d Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 23 Jul 2025 15:34:43 -0400 Subject: [PATCH 1/4] atlas search page --- source/atlas-search.txt | 156 +++++++++++++++++- .../includes/aggregation/search-meta-agg.kt | 45 +++++ source/includes/atlas-search.kt | 42 +++++ 3 files changed, 242 insertions(+), 1 deletion(-) create mode 100644 source/includes/aggregation/search-meta-agg.kt create mode 100644 source/includes/atlas-search.kt diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 483dc91b..969b2269 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -2,4 +2,158 @@ ========================= 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 :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 +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 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/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..0410ed15 --- /dev/null +++ b/source/includes/aggregation/search-meta-agg.kt @@ -0,0 +1,45 @@ +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 + +private const val CONNECTION_URI = "" + +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 = CONNECTION_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") + + // Uncomment the methods that correspond to what you're testing + // 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..bb84c40c --- /dev/null +++ b/source/includes/atlas-search.kt @@ -0,0 +1,42 @@ +// 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") + + // Queries for documents that have a "title" value containing the word "Alabama" + // 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 From f031e0db72a0587116eefea71e4ae348f4a7acaa Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 23 Jul 2025 15:41:49 -0400 Subject: [PATCH 2/4] fix link --- 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 969b2269..9d8b1d74 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -51,7 +51,7 @@ parameter. 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. + 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 From 9e8f0de62ae764c3c9dafee530edb9df06afafeb Mon Sep 17 00:00:00 2001 From: Angela Date: Thu, 24 Jul 2025 14:30:06 -0400 Subject: [PATCH 3/4] sa feedback --- source/atlas-search.txt | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 9d8b1d74..2d66d868 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -49,7 +49,7 @@ parameter. 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 `. + 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. @@ -99,11 +99,9 @@ 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 `. + on :atlas:`MongoDB Atlas ` clusters running v4.4.11 and later. -The following example shows the ``near`` metadata for an Atlas search +The following example shows the ``near`` metadata for an Atlas Search aggregation stage: .. literalinclude:: /includes/aggregation/search-meta-agg.kt From b4c8f65d5488afc8003476fd81d85487defe158a Mon Sep 17 00:00:00 2001 From: Angela Date: Fri, 25 Jul 2025 09:59:39 -0400 Subject: [PATCH 4/4] nathan feedback --- source/atlas-search.txt | 2 +- source/includes/aggregation/search-meta-agg.kt | 7 ++----- source/includes/atlas-search.kt | 1 - 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 2d66d868..2baccd86 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -94,7 +94,7 @@ 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. +only the metadata from the Atlas full-text search results. .. tip:: Only Available on Atlas for MongoDB v4.4.11 and later diff --git a/source/includes/aggregation/search-meta-agg.kt b/source/includes/aggregation/search-meta-agg.kt index 0410ed15..0ec67aab 100644 --- a/source/includes/aggregation/search-meta-agg.kt +++ b/source/includes/aggregation/search-meta-agg.kt @@ -9,8 +9,6 @@ import com.mongodb.client.model.search.SearchPath.fieldPath import com.mongodb.kotlin.client.MongoCollection import org.bson.Document -private const val CONNECTION_URI = "" - fun runAtlasTextSearchMeta(collection: MongoCollection) { val textSearchMeta = // begin atlasSearchMeta @@ -28,7 +26,7 @@ fun runAtlasTextSearchMeta(collection: MongoCollection) { } fun main() { - val uri = CONNECTION_URI + val uri = "" val settings = MongoClientSettings.builder() .applyConnectionString(ConnectionString(uri)) @@ -39,7 +37,6 @@ fun main() { val database = mongoClient.getDatabase("sample_mflix") val collection = database.getCollection("movies") - // Uncomment the methods that correspond to what you're testing - // runAtlasTextSearchMeta(collection) + runAtlasTextSearchMeta(collection) } } \ No newline at end of file diff --git a/source/includes/atlas-search.kt b/source/includes/atlas-search.kt index bb84c40c..53c0b628 100644 --- a/source/includes/atlas-search.kt +++ b/source/includes/atlas-search.kt @@ -25,7 +25,6 @@ fun main() { val database = mongoClient.getDatabase("sample_mflix") val collection = database.getCollection("movies") - // Queries for documents that have a "title" value containing the word "Alabama" // begin-atlas-search val pipeline: List = listOf( search(SearchOperator.text(