Count Atlas Search Results

The Atlas Search count option adds a field to the metadata results document that displays a count of the search results for the query. You can use count to determine the size of the result set. You can use it in the $search or $searchMeta stage. You must use it in conjunction with the operators or collectors to display either the total number of documents or a lower bound on the number of documents that match the query.

MongoDB recommends using count with the $searchMeta stage to retrieve metadata results only for the query. To retrieve metadata results and query results using the $search stage, you must use the $$SEARCH_META variable. To learn more, see SEARCH_META Aggregation Variable.

Considerations

To use the count option over sharded collections, your cluster must run MongoDB 6.0 or later. On sharded Atlas clusters running MongoDB 7.2.0, $searchMeta might return an error for count.

Atlas Search doesn't include the count results in the results for queries run with count in explain mode.

Syntax

count has the following syntax:

{
  "$searchMeta"|"$search": {
    "index": "<index name>", // optional, defaults to "default"
    "<operator>": {
      <operator-specifications>
    },
    "count": {
      "type": "lowerBound"|"total",
      "threshold": <number-of-documents> //optional
    }
  }
}

Options

Field	Type	Description	Required?
`type`	string	Type of count of the documents in the result set. Value can be one of the following: `lowerBound` - for a lower bound count of the number of documents that match the query. You can set the `threshold` for the lower bound number. `total` - for an exact count of the number of documents that match the query. If the result set is large, Atlas Search might take longer than for `lowerBound` to return the count. If omitted, defaults to `lowerBound`.	no
`threshold`	int	Number of documents to include in the exact count if `type` is `lowerBound`. If omitted, defaults to `1000`, which indicates that any number up to `1000` is an exact count and any number above `1000` is a rough count of the number of documents in the result.	no

Count Results

The count document included in the results document contains the following integer fields:

Option	Description
`lowerBound`	Lower bound for this result set. This is returned by default if you omit the `type` option and when you explicitly request a count of type `lowerBound`.
`total`	Total count for this result set. This is returned only when a count of type `total` is requested.

`SEARCH_META` Aggregation Variable

When you run your query using the $search stage, Atlas Search stores the metadata results in the $$SEARCH_META variable and returns only the search results. You can use the $$SEARCH_META variable in all the supported aggregation pipeline stages to view the metadata results for your $search query.

MongoDB recommends using the $$SEARCH_META variable only if you need both the search results and the metadata results. Otherwise, use the:

$search stage for just the search results.
$searchMeta stage for just the metadata results.

Example

Suppose an index on the released field in the sample_mflix.movies collection:

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

The following query searches for movies released near September 01, 2011 in the movies collection. The query requests a total count of the results. The query includes a:

The sample query uses the following stages:

`$search`	Searches for movies released near September 01, 2011 in the `movies` collection. The query requests a total count of the results and metadata on the `genres` field.
`$project`	Excludes all fields except `title` and `released` from the documents and includes the metadata results stored in the `$$SEARCH_META` variable as the value of a field named `meta`.
`$limit`	Limits the output to `2` documents.

db.movies.aggregate([
  {
    "$search": {
      "near": {
        "path": "released",
        "origin": ISODate("2011-09-01T00:00:00.000+00:00"),
        "pivot": 7776000000
      },
      "count": {
         "type": "total"
      }
    }
  },
  {
    "$project": {
      "meta": "$$SEARCH_META",
      "title": 1,
      "released": 1
    }
  },
  {
    "$limit": 2
  }
])

{
  "_id" : ObjectId("573a13c3f29313caabd6b025"),
  "title" : "Submarino",
  "released" : ISODate("2011-09-01T00:00:00Z"),
  "meta" : {
    "count" : { "total" : NumberLong(23026) }
  }
}
{
  "_id" : ObjectId("573a13c7f29313caabd748f7"),
  "title" : "Devil's Playground",
  "released" : ISODate("2011-09-01T00:00:00Z"),
  "meta" : {
    "count" : { "total" : NumberLong(23026) }
  }
}

Suppose an index on the released and genres fields in the sample_mflix.movies collection:

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

The sample query uses the following stages:

`$search`	Searches for movies released near September 01, 2011 in the `movies` collection. The query requests a total count of the results and metadata on the `genres` field.
`$limit`	Limits the output to `2` documents.
`$facet`	Processes the `$search` results by excluding all fields except `title`, `released`, and `genres` from the documents and including the metadata results stored in the `$$SEARCH_META` variable inside the `meta` array of documents.

db.movies.aggregate([
  {
    "$search": {
      "facet": {
        "operator": {
          "near": {
            "path": "released",
            "origin": ISODate("2011-09-01T00:00:00.000+00:00"),
            "pivot": 7776000000
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      },
      "count": {
        "type": "total"
      }
    }
  },
  {
    "$limit": 2
  },
  {
    "$facet": {
      "results": [
        { "$project":
          {
            "title": 1,
            "released": 1,
            "genres": 1
          }
        }
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  }
])

[
  {
    results: [
      {
        _id: ObjectId('573a13c3f29313caabd6b025'),
        genres: [ 'Drama' ],
        title: 'Submarino',
        released: ISODate('2011-09-01T00:00:00.000Z')
      },
      {
        _id: ObjectId('573a13c7f29313caabd748f7'),
        genres: [ 'Action', 'Horror' ],
        title: "Devil's Playground",
        released: ISODate('2011-09-01T00:00:00.000Z')
      }
    ],
    meta: [
      {
        count: { total: Long('20878') },
        facet: {
          genresFacet: {
            buckets: [
              { _id: 'Drama', count: Long('12149') },
              { _id: 'Comedy', count: Long('6436') },
              { _id: 'Romance', count: Long('3274') },
              { _id: 'Crime', count: Long('2429') },
              { _id: 'Thriller', count: Long('2400') },
              { _id: 'Action', count: Long('2349') },
              { _id: 'Adventure', count: Long('1876') },
              { _id: 'Documentary', count: Long('1755') },
              { _id: 'Horror', count: Long('1432') },
              { _id: 'Biography', count: Long('1244') }
            ]
          }
        }
      }
    ]
  }
]

To learn more about the results, see Count Results.

Examples

The following example uses an index on the year field in the sample_mflix.movies collection:

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

The following query searches for the movies between the years 2010 and 2015 in the movies collection. The query requests a lower bound count of the results:

db.movies.aggregate([
  {
    "$searchMeta": {
      "range": {
        "path": "year",
        "gte": 2010,
        "lte": 2015
      },
      "count": {
        "type": "lowerBound"
      }
    }
  }
])

Atlas Search returns the following results:

{ "count" : { "lowerBound" : NumberLong(1001) } }

The following query searches for the movies between the years 2010 and 2015 in the movies collection. The query requests a total count of the results:

db.movies.aggregate([
  {
    "$searchMeta": {
      "range": {
        "path": "year",
        "gte": 2010,
        "lte": 2015
      },
      "count": {
        "type": "total"
      }
    }
  }
])

Atlas Search returns the following results:

{ "count" : { "total" : NumberLong(5971) } }

To learn more about the results, see Count Results.

Back

highlight

searchSequenceToken