`$searchMeta`

On this page

Syntax

Fields
Behavior
Metadata Result Types
Example
Troubleshooting

$searchMeta

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

Note

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

Syntax

A $searchMeta pipeline stage has the following prototype form:

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

Fields

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.

Behavior

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

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.

Example

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") } } ]

Troubleshooting

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

Back

$search

2. Use Operators & Collectors