facet (MongoDB Search Operator)

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

facet (MongoDB Search Operator)

Definition

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](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search and [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stages. MongoDB recommends using facet with the [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage to retrieve metadata results only for the query. To retrieve metadata results and query results using the [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search stage, you must use the $$SEARCH_META aggregation variable. See [SEARCH_META Aggregation Variable](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-aggregation-variable to learn more.

If you define [storedSource](https://www.mongodb.com/docs/search/indexes/stored-source-definition.md#std-label-fts-stored-source-definition in your [embeddedDocuments](https://www.mongodb.com/docs/search/indexes/field-types/embedded-documents-type.md#std-label-bson-data-types-embedded-documents field type definition, you can use [returnScope](https://www.mongodb.com/docs/search/query/return-scope.md#std-label-fts-return-scope with [returnStoredSource](https://www.mongodb.com/docs/search/query/return-stored-source.md#std-label-fts-return-stored-source-option to facet on nested fields inside an array of objects. Otherwise, you can only facet on the root [embeddedDocuments](https://www.mongodb.com/docs/search/indexes/field-types/embedded-documents-type.md#std-label-bson-data-types-embedded-documents type field. For an example of faceting on:

• Nested fields inside an array of objects, see [returnScope Example.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-egs

• Matching children of an embeddedDocuments array using embeddedDocument, see [Embedded-Scoped Facet Example.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-embedded-scoped-egs

• Root embeddedDocuments type field, see [Facet Query.](https://www.mongodb.com/docs/search/query/operators-collectors/embedded-document.md#std-label-embedded-document-query-examples

Syntax

facet has the following syntax:

{
  "$searchMeta"|"$search": {
    "index": <index name>, // optional, defaults to "default"
    "facet": {
      "operator": {
        <operator-specifications>
      },
      "facets": {
        <facet-definitions>
      }
    },
    "returnScope": {
      "path": "<embedded-documents-field-to-query>"
    },
    "returnStoredSource": true
  }
}

Fields

Memory Requirements

Facet queries are memory-intensive, regardless of your cluster tier. Queries that specify [Facet Aggregations](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-aggregation or [nested facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-nested require more memory and disk than other facet queries. Before you use facets in production, confirm that your cluster has enough memory for your workload. To learn more, see [Search Memory Management](https://www.mongodb.com/docs/search/performance/index-performance.md#std-label-fts-search-memory-management. To get sizing guidance for your workload, [request support.](https://www.mongodb.com/docs/atlas/support.md#std-label-atlas-support

The memory that a facet query requires depends on the number of unique values in the field that you facet on, not the number of buckets that you request using numBuckets or boundaries. For example, a facet that requests 20 buckets on a field with five million unique values still counts every unique value to determine the top 20 buckets.

For [nested facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-nested, the total unique values computed in a query multiply based on the unique values across each level of nesting. Even when each individual field has low cardinality, the combination of values across nested paths can produce a large number of unique buckets. To learn more about how nested facets multiply buckets, see [Nested Facets.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-nested

MongoDB Search tracks bucket counts separately for each query, so total memory use scales with the number of concurrent facet queries. On a sharded cluster, MongoDB Search also requires memory to merge the buckets from each shard, which scales with the number of shards and the number of buckets.

Facet Definition

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

• [String Facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-string-facet

• [Numeric Facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-numeric-facet

• [Date Facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-date-facet

String Facets

Important:

[stringFacet](https://www.mongodb.com/docs/search/indexes/field-types/string-facet-type.md#std-label-bson-data-types-string-facet is now outdated. Use [token](https://www.mongodb.com/docs/search/indexes/field-types/token-type.md#std-label-bson-data-types-token instead, which provides improved faceting.

To learn more about the differences between the updated and outdated field types for facet, see [Comparing Field Types for Facet.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-type-differences

String facets allow you to narrow down MongoDB Search results based on the most frequent string values in the specified string field. The string field must be indexed as [token](https://www.mongodb.com/docs/search/indexes/field-types/token-type.md#std-label-bson-data-types-token. To facet on string fields in embedded documents, you must also index the parent fields as the [document](https://www.mongodb.com/docs/search/indexes/field-types/document-type.md#std-label-bson-data-types-document type. When you facet on strings in arrays or embedded documents, MongoDB Search returns facet counts based on the number of matching root documents.

Syntax

String facets have the following syntax:

{
  "$searchMeta": {
    "facet":{
      "operator": {
        <operator-specification>
      },
      "facets": {
        "<facet-name>" : {
          "type" : "string",
          "path" : "<field-path>",
          "numBuckets" : <number-of-categories>,
          "embeddedDocument": { <embedded-document-scope> } // optional
        }
      }
    }
  }
}

Options

Example

Example:

The following example uses an index named default on the sample_mflix.movies collection. The genres field in the collection is indexed as the [token](https://www.mongodb.com/docs/search/indexes/field-types/token-type.md#std-label-bson-data-types-token type and the year field is indexed as the [number](https://www.mongodb.com/docs/search/indexes/field-types/number-type.md#std-label-bson-data-types-number type.

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

The query uses the [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage to search the year field in the movies collection for movies from 2000 to 2015 and retrieve a count of the number of movies in each genre.

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

Output:

[
  {
    count: { lowerBound: Long('12568') },
    facet: {
      genresFacet: {
        buckets: [
          { _id: 'Drama', count: Long('7079') },
          { _id: 'Comedy', count: Long('3689') },
          { _id: 'Romance', count: Long('1764') },
          { _id: 'Thriller', count: Long('1584') },
          { _id: 'Documentary', count: Long('1472') },
          { _id: 'Action', count: Long('1471') },
          { _id: 'Crime', count: Long('1367') },
          { _id: 'Adventure', count: Long('1056') },
          { _id: 'Horror', count: Long('866') },
          { _id: 'Biography', count: Long('796') }
        ]
      }
    }
  }
]

To learn more about these results, see [Facet Results.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-results

Numeric Facets

Important:

[numberFacet](https://www.mongodb.com/docs/search/indexes/field-types/number-facet-type.md#std-label-bson-data-types-number-facet is now outdated. Use [number](https://www.mongodb.com/docs/search/indexes/field-types/number-type.md#std-label-bson-data-types-number instead, which provides improved faceting.

To learn more about the differences between the updated and outdated field types for facet, see [Comparing Field Types for Facet.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-type-differences

Numeric facets allow you to determine the frequency of numeric values in your search results by breaking the results into separate ranges of numbers. When you facet on numbers in arrays or embedded documents, MongoDB Search returns facet counts based on the number of matching root documents.

Syntax

Numeric facets have the following syntax:

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

Options

Example

Example:

The following example uses an index named default on the sample_mflix.movies collection. The year field in the collection is indexed as the [number](https://www.mongodb.com/docs/search/indexes/field-types/number-type.md#std-label-bson-data-types-number type.

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

The query uses the [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage to search the year field in the movies collection for movies between the years 1980 and 2000 and retrieve metadata results for the query. The query specifies three buckets:

• 1980, inclusive lower bound for this bucket

• 1990, exclusive upper bound for the 1980 bucket and inclusive lower bound for this bucket

• 2000, exclusive upper bound for the 1990 bucket

The query also specifies a default bucket named other to retrieve results of the query that don't fall under any of the specified boundaries.

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

Output:

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

To learn more about these results, see [Facet Results.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-results

Date Facets

Important:

[dateFacet](https://www.mongodb.com/docs/search/indexes/field-types/date-facet-type.md#std-label-bson-data-types-date-facet is now outdated. Use [date](https://www.mongodb.com/docs/search/indexes/field-types/date-type.md#std-label-bson-data-types-date instead, which provides improved faceting.

To learn more about the differences between the updated and outdated field types for facet, see [Comparing Field Types for Facet.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-type-differences

Date facets allow you to narrow down search results based on a date. When you facet on dates in arrays or embedded documents, MongoDB Search returns facet counts based on the number of matching root documents.

Syntax

Date facets have the following syntax:

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

Options

Example

Example:

The following example uses an index named default on the sample_mflix.movies collection. The released field in the collection is indexed as the [date](https://www.mongodb.com/docs/search/indexes/field-types/date-type.md#std-label-bson-data-types-date type.

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

The query uses the [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage to search the released field in the movies collection for movies between the years 2000 and 2015 and retrieve metadata results for the query. The query specifies four buckets:

• 2000-01-01, inclusive lower bound for this bucket

• 2005-01-01, exclusive upper bound for the 2000-01-01 bucket and inclusive lower bound for this bucket

• 2010-01-01, exclusive upper bound for the 2005-01-01 bucket and inclusive lower bound for this bucket

• 2015-01-01, exclusive upper bound for the 2010-01-01 bucket

The query also specifies a default bucket named other to retrieve results of the query that don't fall under any of the specified boundaries.

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

Output:

[
  {
    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') }
        ]
      }
    }
  }
]

To learn more about these results, see [Facet Results.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-results

Comparing Field Types for Facet

The updated MongoDB Search field types provide improved functionality to support faceting compared to the outdated types (stringFacet, numberFacet, dateFacet). The following table outlines the key differences in functionality:

Note:

When both the outdated and updated field types are defined for the same field, the outdated facet types take precedence. For example, if both token and stringFacet are defined for a field, the facet calculation uses the stringFacet mapping.

Facet on Matching Children of an Embedded Documents Array

Each facet definition can include an optional embeddedDocument field that scopes the facet's bucket counts to only the child documents in an [embeddedDocuments](https://www.mongodb.com/docs/search/indexes/field-types/embedded-documents-type.md#std-label-bson-data-types-embedded-documents array that match a query predicate. If you omit the embeddedDocument field, the facet is document-indexed.

Without embeddedDocument, a root document counts in a bucket if it has any child document that falls into that bucket, even if that child doesn't match the query defined in the facet.operator block. The embeddedDocument field restricts bucket contributions to only the children that match the specified embeddedDocument.operator. It counts each root document at most once per bucket.

The embeddedDocument field takes the following fields:

For a [number](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-numeric-facet or [date](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-date-facet facet, a matching child whose value falls outside the configured boundaries counts in the default bucket, if you specify one, using the same rule as a document-indexed facet. A root document with no matching child doesn't contribute to the embeddedDocument-scoped facet, but can still contribute to any other, unscoped facet in the same query.

Important:

You can't combine an embeddedDocument-scoped facet with several other faceting options. To learn more, see [Limitations.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-limitations

For an example, see the [Embedded-Scoped Facet Example.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-embedded-scoped-egs

Facet Aggregations

Important:

Facet aggregations is in Preview. The feature and corresponding documentation might change at any time during the Preview period. To learn more, see Preview Features.

To compute metrics for each facet bucket, add an aggregations document to a facet definition. MongoDB Search computes the metrics from the MongoDB Search index, so it is much more efficient than running a [$group](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group stage later in your pipeline.

For each facet bucket, aggregations allows you to compute the following values:

• sum

• average

• minimum

• maximum

• first

• last

When using aggregations, you must:

• Index the field that you specify in the path for each metric as token, number, or date.

• Explicitly include the count metric if you want the bucket count.

• Only specify aggregations at the leaf-level of nested facets.

If you want to compute metrics for an intermediate grouping, specify that grouping as a separate top-level facet with aggregations and no nested facet.

MongoDB Search computes aggregations over the data in the MongoDB Search index, which is [eventually consistent.](https://www.mongodb.com/docs/search/performance/index-performance.md#std-label-index-perf

Note: Memory Requirements

Facet queries that specify aggregations or [nested facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-nested increase the memory and disk that your MongoDB Search index requires beyond the requirements for other facet queries. To learn more, see [Memory Requirements.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-memory

Syntax

aggregations has the following syntax:

{
  "$searchMeta": {
    "facet": {
      "facets": {
        "<facet-name>": {
          "type": "<facet-type>",
          "path": "<field-path>",
          "aggregations": {
            "<aggregation-name>": {
              "type": "sum" | "min" | "max" | "avg" | "first" | "last",
              "path": "<field-path>"
            }
          }
        }
      }
    }
  }
}

Each key in the aggregations document is an aggregation name that you specify. MongoDB Search returns each aggregation in the bucket documents under the name that you specify.

Options

Metric Types

Important:

min and max support all field types, including token. When MongoDB Search computes these metrics, it skips any document in which the field resolves to an unsupported type. MongoDB Search doesn't return an error when it skips a document. To determine whether MongoDB Search skipped documents in a bucket, add a count metric to the same aggregations document and compare it to the number of documents that you expect.

For values that MongoDB Search doesn't skip, min selects the smallest value in the bucket and max selects the largest. If the values aren't all of the same type, MongoDB Search applies [BSON type comparison order](https://www.mongodb.com/docs/manual/reference/bson-type-comparison-order.md#std-label-bson-types-comparison-order to determine which value is smallest or largest.

Array Considerations

Each metric type handles a field that resolves to more than one value, such as an array, differently:

• sum and avg skip the document.

• min and max select the lowest and highest value in the array to use as a representative element for the document.

• first and last return all of the values as an array.

For first and last, the returned array differs from the source document in the following ways:

• The order of the values might differ. MongoDB Search reads the values from the index, which doesn't preserve the order of the source document. For example, if a document contains [“red”, “blue”, “green”], MongoDB Search might return [“blue”, “green”, “red”].

• MongoDB Search returns only one instance of a duplicate value.

• MongoDB Search returns every value at the path, including values of a type that you can't facet on. For example, if an array contains both strings and a boolean, MongoDB Search returns the boolean with the strings.

To return the values exactly as the source document contains them, define [storedSource](https://www.mongodb.com/docs/search/indexes/stored-source-definition.md#std-label-fts-stored-source-definition for the field in your index definition and set [returnStoredSource](https://www.mongodb.com/docs/search/query/return-stored-source.md#std-label-fts-return-stored-source-option to true in your query.

Nested Facets

Important:

Nested facets is in Preview. The feature and corresponding documentation might change at any time during the Preview period. To learn more, see Preview Features.

To group the documents in each bucket by additional fields, add a facets document to an existing facet definition. Each nested facet definition uses the same syntax as a top-level facet definition, so you can nest facets to build a tree of groupings. MongoDB Search returns the buckets for a nested facet inside each bucket of its parent facet.

For each bucket of a facet that contains a nested facet, MongoDB Search also returns a count field with the number of documents in the bucket. You don't need to specify a count metric for these intermediate buckets.

You can nest facets without limit on the number of levels. However, the following restrictions apply:

• You can specify aggregations only on a leaf facet in a nested facet tree. A facet definition that specifies facets can't also specify aggregations. To compute metrics for an intermediate grouping, specify that grouping as a separate top-level facet with aggregations and no nested facet.

• You can't name a nested facet count. MongoDB Search reserves count for the document count of intermediate buckets.

• The total number of unique buckets that a query can return can't exceed 100000. To calculate the buckets that one facet tree produces, multiply the number of buckets at each level of its nesting branch. The number of buckets at a level is numBuckets for a string facet or the number of buckets that boundaries and default define for a number or date facet. For example, a facet that requests 20 buckets and contains a nested facet that requests 20 buckets produces 400 unique buckets. Because each level multiplies this total, requesting more buckets at each level reduces the number of levels that you can nest.

Facet Results

For a facet query, MongoDB 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:

If the facet definition specifies [Facet Aggregations](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-aggregation, each bucket document contains the metrics that you name in the aggregations document instead of the count field. If the facet definition specifies [nested facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-nested, each bucket document contains a count field with the number of documents in the bucket, and the results for the nested facet.

Multi-Select Facets

MongoDB Search allows you to view and select multiple buckets within the same facet simultaneously. Typically, selecting a bucket within a facet filters search results according to that selection and alters counts for all facets.

Example:

Suppose an index definition for the sample_airbnb.listings collection specifies facets for the following fields:

• cancellation_policy

• room_type

• accommodates

The cancellation_policy facet has the following buckets:

• flexible

• moderate

• strict_14_with_grace_period

• super_strict_30

• super_strict_60

Each bucket has its own result count. When you search for the moderate cancellation_policy, the counts for the four other buckets go to 0. Additionally, the counts for buckets in the room_type and accommodates facets reduce to the number of results in each bucket that also have a flexible cancellation_policy.

In scenarios where you need more granular control of how facets affect search result counts, enable multi-select faceting with the doesNotAffect property in your faceted queries. These facets still filter results, but the query doesn't alter their result counts.

You can specify doesNotAffect in the following operators:

• [compound](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref

• [equals](https://www.mongodb.com/docs/search/query/operators-collectors/equals.md#std-label-equals-ref

• [in](https://www.mongodb.com/docs/search/query/operators-collectors/in.md#std-label-in-ref

• [range](https://www.mongodb.com/docs/search/query/operators-collectors/range.md#std-label-range-ref

To exclude multiple facets, specify an array of facet names. Most use cases exclude only the facet that shares a path with the filter. For example, an equals filter on the rating field specifies the name of the facet that uses rating as its path.

Note:

The doesNotAffect option doesn't work with facets that specify [aggregations](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-aggregation. To learn more, see [Limitations.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-limitations

Example:

Consider a query against the sample_airbnb.listingsAndReviews collection for documents with a moderate cancellation_policy. If you specify a doesNotAffect value of cancellation_policy, the counts for buckets in the cancellation_policy facet don't change, but the result counts for the buckets of other facets reduce to the number of results in each bucket that also have a moderate cancellation_policy.

For more information, see the [Multi-Select Faceting example.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-egs

You can't combine doesNotAffect with an embeddedDocument-scoped facet. To learn more, see [Facet on Matching Children of an Embedded Documents Array.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-embedded-scoped

Finally, for use cases with many facets, you can limit which other filters affect a given facet. You can do this by specifying any facet in the doesNotAffect property of any filter, including facets on other fields. This allows you to observe at a glance which selections narrow options more or less quickly.

Example:

Consider a query against the sample_airbnb.listingsAndReviews collection for documents with an accommodates value of 3. If you specify a doesNotAffect value of cancellation_policy, the result counts for the room_type buckets reduce to the number of results in each bucket that also accommodate 3 people, but the result counts for the buckets in cancellation_policy are unaffected.

For more information, see the [Inter-Facet Filter Exclusion example.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-egs

SEARCH_META Aggregation Variable

When you run your query using the [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search stage, MongoDB 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](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search query. You can also use the $$SEARCH_META variable with [facet.aggregations.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-aggregation

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

• [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search stage for just the search results.

• [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage for just the metadata results.

Limitations

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

Limitations for Embedded-Scoped Facets

The following limitations apply to [Facet on Matching Children of an Embedded Documents Array:](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-embedded-scoped

• You can't combine a top-level returnScope option with an embeddedDocument-scoped facet in the same query.

• An embeddedDocument-scoped facet returns only a count.

• You can't combine drill-sideways faceting (doesNotAffect) with an embeddedDocument-scoped facet in the same query.

Limitations for Facet Aggregations

The following limitations apply to [Facet Aggregations:](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-aggregation

• You can't use the following options with aggregations:

• [returnScope](https://www.mongodb.com/docs/search/query/return-scope.md#std-label-fts-return-scope

• doesNotAffect for [Multi-Select Facets](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-multi-select

• You can't facet or compute aggregations on the following [BSON types:](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types

• binData

• bool

• decimal

• null

• objectId

• timestamp

To compute metrics over one of these types, use a [view](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page to convert the field to a supported type before you index it.

Examples

The following examples use the [sample data](https://www.mongodb.com/docs/atlas/import/load-sample-data.md#std-label-sample-data. The metadata results example demonstrates how to run a [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta query with facet to retrieve only the metadata in the results. The metadata and search results example demonstrates how to run a [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search query with facet and the $SEARCH_META aggregation variable to retrieve both the search and metadata results. The returnScope example demonstrates how to facet on nested fields in an array of objects dynamically indexed using the embeddedDocuments type. The embedded-scoped facet example demonstrates how to facet on only the matching children of an embeddedDocuments array. The multi-select and inter-facet filter exclusion examples demonstrate how to use doesNotAffect to control how facets affect each other's counts. The aggregation example demonstrates how to

（本文超出站点单文档体积上限，已截断）