facet

Compatibility

facet is only available on Atlas clusters running one of the following versions:

• MongoDB 5.0.4+

• MongoDB 6.0+

• MongoDB 7.0+

  Note

  To run facet queries over sharded collections, your cluster must run MongoDB v6.0 or higher.

You can't run facet queries with explain.

Definition

facet

The facet collector groups results by values or ranges in the specified faceted fields and returns the count for each of those groups.

You can use facet with both the $search and $searchMeta stages. MongoDB recommends using facet 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 aggregation variable. See SEARCH_META Aggregation Variable to learn more.

Syntax

facet has the following syntax:

{
  "$searchMeta"|"$search": {
    "index": <index name>, // optional, defaults to "default"
    "facet": {
      "operator": {
        <operator-specifications>
      },
      "facets": {
        <facet-definitions>
      }
    }
  }
}

Fields

Facet Definition

The facet definition document contains the facet name and options specific to a type of facet. Atlas Search supports the following types of facets:

• String Facets

• Numeric Facets

• Date Facets

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "string",
          "path" : "<field-path>",
          "numBuckets" : <number-of-categories>,
        }
      }
    }
  }
}

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

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "year",
            "gte": 2000,
            "lte": 2015
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      }
    }
  }
])

[
  {
    count: { lowerBound: Long("13718") },
    facet: {
      genresFacet: {
        buckets: [
          { _id: 'Drama', count: Long("7759") },
          { _id: 'Comedy', count: Long("3937") },
          { _id: 'Romance', count: Long("1916") },
          { _id: 'Thriller', count: Long("1705") },
          { _id: 'Documentary', count: Long("1703") },
          { _id: 'Action', count: Long("1558") },
          { _id: 'Crime', count: Long("1475") },
          { _id: 'Adventure', count: Long("1111") },
          { _id: 'Horror', count: Long("1008") },
          { _id: 'Biography', count: Long("877") }
        ]
      }
    }
  }
]

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "number",
          "path" : "<field-path>",
          "boundaries" : <array-of-numbers>,
          "default": "<bucket-name>"
        }
      }
    }
  }
}

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

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "year",
            "gte": 1980,
            "lte": 2000
          }
        },
        "facets": {
          "yearFacet": {
            "type": "number",
            "path": "year",
            "boundaries": [1980,1990,2000],
            "default": "other"
          }
        }
      }
    }
  }
])

[
  {
    count: { lowerBound: Long('6095') },
    facet: {
      yearFacet: {
        buckets: [
          { _id: 1980, count: Long('1956') },
          { _id: 1990, count: Long('3558') },
          { _id: 'other', count: Long('581') }
        ]
      }
    }
  }
]

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "date",
          "path" : "<field-path>",
          "boundaries" : <array-of-dates>,
          "default": "<bucket-name>"
        }
      }
    }
  }
}

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

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "released",
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
            "lte": ISODate("2015-01-31T00:00:00.000Z")
          }
        },
        "facets": {
          "yearFacet": {
            "type": "date",
            "path": "released",
            "boundaries": [ISODate("2000-01-01"), ISODate("2005-01-01"), ISODate("2010-01-01"), ISODate("2015-01-01")],
            "default": "other"
          }
        }
      }
    }
  }
])

[
  {
    count: { lowerBound: Long('11922') },
    facet: {
      yearFacet: {
        buckets: [
          {
            _id: ISODate('2000-01-01T00:00:00.000Z'),
            count: Long('3028')
          },
          {
            _id: ISODate('2005-01-01T00:00:00.000Z'),
            count: Long('3953')
          },
          {
            _id: ISODate('2010-01-01T00:00:00.000Z'),
            count: Long('4832')
          },
          { _id: 'other', count: Long('109') }
        ]
      }
    }
  }
]

Facet Results

For a facet query, Atlas Search returns a mapping of the defined facet names to an array of buckets for that facet in the results. The facet result document contains the buckets option, which is an array of resulting buckets for the facet. Each facet bucket document in the array has the following fields:

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.

Limitations

The following limitations apply:

• You can run facet queries on a single field only. You can't run facet queries on groups of fields.

• You can run facet queries over sharded collections on clusters running MongoDB v6.0 only.

Examples

The following examples use the sample_mflix.movies collection. The metadata results example demonstrates how to run a $searchMeta query with facet to retrieve only the metadata in the results. The metadata and search results example demonstrates how to run a $search query with facet and the $SEARCH_META aggregation variable to retrieve both the search and metadata results.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "directors": {
        "type": "stringFacet"
      },
      "year": {
        "type": "numberFacet"
      },
      "released": {
        "type": "date"
      }
    }
  }
}

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "range": {
            "path": "released",
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
            "lte": ISODate("2015-01-31T00:00:00.000Z")
          }
        },
        "facets": {
          "directorsFacet": {
            "type": "string",
            "path": "directors",
            "numBuckets" : 7
          },
          "yearFacet" : {
            "type" : "number",
            "path" : "year",
            "boundaries" : [2000,2005,2010, 2015]
          }
        }
      }
    }
  }
])

[
  {
    "count" : { "lowerBound" : NumberLong(13064) },
    "facet" : {
      "yearFacet" : {
        "buckets" : [
          { "_id" : 2000, "count" : NumberLong(3283) },
          { "_id" : 2005, "count" : NumberLong(4365) },
          { "_id" : 2010, "count" : NumberLong(5123) }
        ]
      },
      "directorsFacet" : {
        "buckets" : [
         { "_id" : "Takashi Miike", "count" : NumberLong(29) },
          { "_id" : "Johnnie To", "count" : NumberLong(23) },
          { "_id" : "Steven Soderbergh", "count" : NumberLong(21) },
          { "_id" : "Michael Winterbottom", "count" : NumberLong(19) },
          { "_id" : "Ken Loach", "count" : NumberLong(16) },
          { "_id" : "Ki-duk Kim", "count" : NumberLong(16) },
          { "_id" : "Ridley Scott", "count" : NumberLong(15) }
        ]
      }
    }
  }
]

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

db.movies.aggregate([
  {
    "$search": {
      "facet": {
        "operator": {
          "near": {
            "path": "released",
            "origin": ISODate("1999-07-01T00:00:00.000+00:00"),
            "pivot": 7776000000
          }
        },
        "facets": {
          "genresFacet": {
            "type": "string",
            "path": "genres"
          }
        }
      }
    }
  },
  { "$limit": 2 },
  {
    "$facet": {
      "docs": [
        { "$project":
          {
            "title": 1,
            "released": 1
          }
        }
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  },
  {
    "$set": {
      "meta": {
        "$arrayElemAt": ["$meta", 0]
      }
    }
  }
])

[
  {
    docs: [
      {
        _id: ObjectId("573a1393f29313caabcde1ae"),
        title: 'Begone Dull Care',
        released: ISODate("1999-07-01T00:00:00.000Z")
      },
      {
        _id: ObjectId("573a13a9f29313caabd2048a"),
        title: 'Fara',
        released: ISODate("1999-07-01T00:00:00.000Z")
      }
    ],
    meta: {
      count: { lowerBound: 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 these results, see Facet Results.