Docs Menu

Atlas Search Aggregation Pipeline Stagesicons/link.png

On this page

  • $search
  • Definition
  • Fields
  • Behavior
  • Aggregation Variable
  • $searchMeta
  • Definition
  • Fields
  • Metadata Result Types
  • Troubleshoot Errors
  • Initial Sync
  • mongot Process Not Installed or Running
Important

Looking for $searchBeta? Use $search instead, the official aggregation stage for running search queries.

Atlas Search queries take the form of an aggregation pipeline stage. This page describes the following pipeline stages:

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

A $search pipeline stage has the following prototype form:

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

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

Field
Type
Necessity
Description
<collector-name>
document
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.
highlight
document
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.
<operator-name>
document
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.

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

Note
Preview

Atlas Search facet and count are in preview. The features and the corresponding documentation may change at any time in the preview stage.

$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.

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
}
},
{
"$facet": {
"docs": [
{"$limit": 5}
],
"meta": [
{"$replaceWith": "$$SEARCH_META"},
{"$limit": 1}
]
}
}
])

The query returns the following results:

{
"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
Preview

Atlas Search facet and count are in preview. The features and the corresponding documentation may change at any time in the preview stage.

Important

The Atlas Search $searchMeta stage is not available on shared clusters. $searchMeta is available only on dedicated clusters.

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

$searchMeta

A $searchMeta pipeline stage has the following prototype form:

{
$searchMeta: {
"index": "<index-name>",
"<result-type>": {
<result-type-specification>
}
}
}

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

Field
Type
Necessity
Description
index
string
Optional
Name of the Atlas Search index to use. If omitted, defaults to default.
<result-type>
document
Required

Type of result to return. You can provide a document as the value for this field. Value can be one of the following:

  • count - for a count of the results. To learn more, see Counting.
  • facet - for a mapping of the defined facet names to an array of buckets for that facet. To learn more, see facet.

To learn more, see Metadata Result Types.

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.

Atlas Search can't perform $search queries against an Atlas cluster during an initial sync process. An initial sync process occurs when you create a new cluster or perform certain upgrades on a cluster. The process includes the following steps:

  1. The mongod performs an initial sync.
  2. The mongot performs an initial sync, which rebuilds the search indexes.

As a result, you may receive an error when running a $search query against a node that you recently created or upgraded. Try your query again after the initial syncs complete and mongot rebuilds the indexes. You can check the status of the mongot initial sync using the following steps:

  1. Click the Search tab for your database deployment.
  2. In the index's Status column, click View Status Details.
  3. Check the state of the index for the node. During mongot initial sync, the status is INITIAL SYNC. When mongot finishes rebuilding the index, the status is ACTIVE.

The following error is returned if you run $search queries when the Atlas Search mongot process isn't installed or running:

MongoError: Remote error from mongot :: caused by :: Error connecting to localhost:28000.

The mongot process is installed only when the first Atlas Search index is defined. If you don't have any Atlas Search index in your Atlas cluster, create at least one Atlas Search index to resolve this error.

Tip
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.