Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

Return Atlas Search Results or Metadata

On this page

  • $search
  • Definition
  • Fields
  • Behavior
  • Aggregation Variable
  • $searchMeta
  • Definition
  • Fields
  • Behavior
  • Metadata Result Types
  • Example
  • Troubleshooting

Atlas Search queries take the form of an aggregation pipeline stage. Based on the pipeline stage that you choose, your query returns either the search results of a full-text search or metadata about your search results:

Aggregation Pipeline Stage
Purpose
Return the search results of a full-text search.
Return metadata about your search results.

The $search stage performs a full-text search on the specified field or fields which must be covered by an Atlas Search index.

$search

A $search pipeline stage has the following prototype form:

{
$search: {
"index": "<index-name>",
"<operator-name>"|"<collector-name>": {
<operator-specification>|<collector-specification>
},
"highlight": {
<highlight-options>
},
"concurrent": true | false,
"count": {
<count-options>
},
"searchAfter"|"searchBefore": "<encoded-token>",
"scoreDetails": true| false,
"sort": {
<fields-to-sort>: 1 | -1
},
"returnStoredSource": true | false,
"tracking": {
<tracking-option>
}
}
}

The $search stage takes a document with the following fields:

Field
Type
Necessity
Description
<collector-name>
object
Conditional
Name of the collector to use with the query. You can provide a document that contains the collector-specific options as the value for this field. Either this or <operator-name> is required.
concurrent
boolean
Optional
Parallelize search across segments on dedicated search nodes. If you don't have separate search nodes on your cluster, Atlas Search ignores this flag. If omitted, defaults to false. To learn more, see Parallelize Query Execution Across Segments.
count
object
Optional
Document that specifies the count options for retrieving a count of the results. To learn more, see Count Atlas Search Results.
highlight
object
Optional
Document that specifies the highlighting options for displaying search terms in their original context.
index
string
Optional

Name of the Atlas Search index to use. If omitted, defaults to default.

Note

If you name your index default, you don't need to specify an index parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the index parameter.

Atlas Search doesn't returns results if you misspell the index name or if the specified index doesn't already exist on the cluster.

<operator-name>
object
Conditional
Name of the operator to search with. You can provide a document that contains the operator-specific options as the value for this field. Either this or <collector-name> is required. Use the compound operator to run a compound query with multiple operators.
returnStoredSource
boolean
Optional
Flag that specifies whether to perform a full document lookup on the backend database or return only stored source fields directly from Atlas Search. If omitted, defaults to false. To learn more, see Return Stored Source Fields.
searchAfter
string
Optional
Reference point for retrieving results. searchAfter returns documents starting immediately following the specified reference point. The reference point must be a Base64-encoded token generated by the $meta keyword searchSequenceToken. To learn more, see Paginate the Results Sequentially. This field is mutually exclusive with the searchBefore field.
searchBefore
string
Optional
Reference point for retrieving results. searchBefore returns documents starting immediately before the specified reference point. The reference point must be a Base64-encoded token generated by the $meta keyword searchSequenceToken. To learn more, see Paginate the Results Sequentially. This field is mutually exclusive with the searchAfter field.
scoreDetails
boolean
Optional
Flag that specifies whether to retrieve a detailed breakdown of the score for the documents in the results. If omitted, defaults to false. To view the details, you must use the $meta expression in the $project stage. To learn more, see Return the Score Details.
sort
object
Optional
Document that specifies the fields to sort the Atlas Search results by in ascending or descending order. You can sort by date, number (integer, float, and double values), and string values. To learn more, see Sort Atlas Search Results.
tracking
object
Optional
Document that specifies the tracking option to retrieve analytics information on the search terms.

$search must be the first stage of any pipeline it appears in. $search cannot be used in:

$search returns only the results of your query. The metadata results of your $search query are saved in the $$SEARCH_META aggregation variable. You can use the $$SEARCH_META variable to view the metadata results for your $search query.

The $$SEARCH_META aggregation variable can be used anywhere after a $search stage in any pipeline, but it can't be used after the $lookup or $unionWith stage in any pipeline. Starting in MongoDB 6.0, the $$SEARCH_META aggregation variable can't be used in any subsequent stage after a $searchMeta stage.

Example

Suppose the following index on the sample_mflix.movies collection.

{
"mappings": {
"dynamic": false,
"fields": {
"released": {
"type": "date"
}
}
}
}

The following query searches for movies released near September 01, 2011 using the $search stage. The query includes a:

  • $project stage to exclude all fields in the documents except title and released.

  • $facet stage that outputs a:

    • docs field with an array of the top 5 search results

    • meta field with the value of $$SEARCH_META variable

db.movies.aggregate([
{
"$search": {
"near": {
"path": "released",
"origin": ISODate("2011-09-01T00:00:00.000+00:00"),
"pivot": 7776000000
}
}
},
{
$project: {
"_id": 0,
"title": 1,
"released": 1
}
},
{ "$limit": 5 },
{
"$facet": {
"docs": [],
"meta": [
{"$replaceWith": "$$SEARCH_META"},
{"$limit": 1}
]
}
}
])
{
"docs" : [
{
"title" : "Submarino",
"released" : ISODate("2011-09-01T00:00:00Z")
},
{
"title" : "Devil's Playground",
"released" : ISODate("2011-09-01T00:00:00Z")
},
{
"title" : "Bag It",
"released" : ISODate("2011-09-01T00:00:00Z")
},
{
"title" : "Dos",
"released" : ISODate("2011-09-01T00:00:00Z")
},
{
"title" : "We Were Here",
"released" : ISODate("2011-09-01T00:00:00Z")
}
],
"meta" : [
{ "count" : { "lowerBound" : NumberLong(17373) } }
]
}

To learn more about the $$SEARCH_META variable and its usage, see:

Note

To run $searchMeta queries over sharded collections, your cluster must run MongoDB v6.0 or later.

The $searchMeta stage returns different types of metadata result documents.

$searchMeta

A $searchMeta pipeline stage has the following prototype form:

{
$searchMeta: {
"index": "<index-name>",
"<collector-name>"|"<operator-name>": {
<collector-specification>|<operator-specification>
},
"count": {
<count-options>
}
}
}

The $searchMeta stage takes a document with the following fields:

Field
Type
Necessity
Description
<collector-name>
object
Conditional
Name of the collector to use with the query. You can provide a document that contains the collector-specific options as the value for this field. Value must be facet to retrieve a mapping of the defined facet names to an array of buckets for that facet. To learn more, see facet. You must specify this or <operator-name>.
count
object
Optional
Document that specifies the count options for retrieving a count of the results. To learn more, see Count Atlas Search Results.
index
string
Optional

Name of the Atlas Search index to use. If omitted, defaults to default.

Atlas Search doesn't return results if you misspell the index name or if the specified index doesn't already exist on the cluster.

<operator-name>
object
Conditional
Name of the operator to search with. You can provide a document that contains the operator-specific options as the value for this field. You must specify this or <collector-name>. $searchMeta returns the default count metadata only.

The $searchMeta stage must be the first stage in any pipeline.

The structure of the metadata results document that is returned by the $searchMeta stage varies based on the type of results. Atlas Search supports the following result types:

Type
Result Structure
count
The count result included in the results indicate whether the count returned in the results is a total count of the search results, or a lower bound. To learn more, see Count Results.
facet
The result to a facet query is a mapping of the defined facet names to an array of buckets for that facet. To learn more, see Facet Results.

Suppose the following index on the sample_mflix.movies collection.

{
"mappings": {
"dynamic": false,
"fields": {
"year": {
"type": "number"
}
}
}
}

The following query searches for the number of movies released in 1998 using the $searchMeta stage.

db.movies.aggregate([
{
"$searchMeta": {
"range": {
"path": "year",
"gte": 1998,
"lt": 1999
},
"count": {
"type": "total"
}
}
}
])
[ { count: { total: Long("552") } } ]

If you are experiencing issues with your Atlas Search $search queries, see Troubleshoot Atlas Search Errors.

←  Create and Run Atlas Search QueriesUse Operators and Collectors in Atlas Search Queries →