$searchMeta

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

$searchMeta

The [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage returns different [types of metadata result](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#std-label-fts-metadata-results documents.

Note:

To run [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-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](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise deployments running version 8.2 or later with the [Kubernetes Operator.](https://www.mongodb.com/docs/kubernetes/current.md#std-label-k8s-operator

  • [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition 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](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-collectors-ref 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)](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-ref. You must specify this or <operator-name>.
concurrent boolean Optional Parallelize search across segments on dedicated search nodesf
count object Optional Document that specifies the [count](https://www.mongodb.com/docs/search/query/counting.md#std-label-count-ref options for retrieving a count of the results. To learn more, see [Count MongoDB Search Results.](https://www.mongodb.com/docs/search/query/counting.md#std-label-count-ref
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](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-operators-ref 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](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-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.](https://www.mongodb.com/docs/search/query/return-stored-source.md#std-label-fts-return-stored-source-option

Behavior

The [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-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](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-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.](https://www.mongodb.com/docs/search/query/counting.md#std-label-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.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-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](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage.

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

Output:

[ { count: { total: Long("552") } } ]

Troubleshooting

If you are experiencing issues with your MongoDB Search [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search queries, see [Troubleshoot Queries.](https://www.mongodb.com/docs/search/query/query-ref.md#std-label-fts-troubleshooting