Run an Atlas Search Query

Overview

In this guide, you can learn how to use the Kotlin Sync driver to run 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 sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide. To learn more about aggregation operations and builders, see the Aggregation Operations 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 MongoDB Atlas clusters running v4.2 or later that are covered by an Atlas Search index. Learn more about the required setup and the functionality of this operator from the 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 Create a Search Index 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

val pipeline: List<Bson> = listOf(
    search(SearchOperator.text(
        fieldPath("title"), "Alabama")),
    project(Projections.include("title"))
)
val results = collection.aggregate(pipeline)
results.forEach { doc ->
    println(doc.toJson())
}

{"_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 $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 MongoDB Atlas clusters running v4.4.11 and later.

The following example shows the near metadata for an Atlas Search aggregation stage:

searchMeta(
    SearchOperator.near(2010, 1, fieldPath("year"))
)

Additional Information

To learn more about Atlas Search, see Atlas Search in the Atlas documentation.

API Documentation

To learn more about the methods mentioned in this guide, see the following API documentation:

Back

Run a Database Command

Atlas Vector Search