/ /

/ /

`$searchMeta`

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

Compatibility

The $searchMeta stage is available in the following environments:

MongoDB Atlas
MongoDB Enterprise deployments running version 8.2 or later with the Kubernetes Operator.
MongoDB Community deployments running version 8.2 or later

Syntax

A $searchMeta pipeline stage has the following prototype form:

{
  $searchMeta: {
    "index": "<index-name>",
    "<collector-name>"|"<operator-name>": {
      <collector-specification>|<operator-specification>
    },
    "concurrent": true | false,
    "count": {
      <count-options>
    },
    "returnScope": {
      "path": "<embedded-documents-field-to-retrieve>"
    }
    "returnStoredSource": true | false
  }
}

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` (MongoDB Search Operator). You must specify this or `<operator-name>`.
`concurrent`	boolean	Optional	Parallelize search across segments on dedicated search nodes. If you don't have separate search nodes on your cluster, MongoDB 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 MongoDB Search Results.
`index`	string	Optional	Name of the MongoDB Search index to use. If omitted, defaults to `default`. MongoDB 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.
`returnScope`	object	Optional	Object that sets the context of the query to the specified embedded document field. You must also specify `returnStoredSource` and set it to `true` if your cluster MongoDB version is less than 8.2.
`returnStoredSource`	boolean	Conditional	Flag that specifies whether to perform a full document lookup on the backend database or return only stored source fields directly from MongoDB Search. If omitted, defaults to `false`. Must be `true` to if you specify `returnScope` and your cluster MongoDB version is less than 8.2. To learn more, see Return Stored Source Fields.

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. MongoDB 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 MongoDB Search $search queries, see Troubleshoot Queries.

Back

Documents: $search

Operators & Collectors