facet (MongoDB Search Operator)

The index definition on the sample_mflix.movies collection specifies the following for the fields to index:

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "directors": {
        "type": "token"
      },
      "year": {
        "type": "number"
      },
      "released": {
        "type": "date"
      }
    }
  }
}

The following query searches for movies released between January 01, 2000 and January 31, 2015. It requests metadata on the directors and year field.

1
db.movies.aggregate([
2
  {
3
    "$searchMeta": {
4
      "facet": {
5
        "operator": {
6
          "range": {
7
            "path": "released",
8
            "gte": ISODate("2000-01-01T00:00:00.000Z"),
9
            "lte": ISODate("2015-01-31T00:00:00.000Z")
10
          }
11
        },
12
        "facets": {
13
          "directorsFacet": {
14
            "type": "string",
15
            "path": "directors",
16
            "numBuckets" : 7
17
          },
18
          "yearFacet" : {
19
            "type" : "number",
20
            "path" : "year",
21
            "boundaries" : [2000,2005,2010, 2015]
22
          }
23
        }
24
      }
25
    }
26
  }
27
])

1
[
2
  {
3
    count: { lowerBound: Long('11922') },
4
    facet: {
5
      yearFacet: {
6
        buckets: [
7
          { _id: 2000, count: Long('3064') },
8
          { _id: 2005, count: Long('4035') },
9
          { _id: 2010, count: Long('4553') }
10
        ]
11
      },
12
      directorsFacet: {
13
        buckets: [
14
          { _id: 'Takashi Miike', count: Long('26') },
15
          { _id: 'Johnnie To', count: Long('20') },
16
          { _id: 'Steven Soderbergh', count: Long('18') },
17
          { _id: 'Michael Winterbottom', count: Long('16') },
18
          { _id: 'Ridley Scott', count: Long('15') },
19
          { _id: 'Tyler Perry', count: Long('15') },
20
          { _id: 'Clint Eastwood', count: Long('14') }
21
        ]
22
      }
23
    }
24
  }
25
]

The results show a count of the following in the sample_mflix.movies collection:

• Number of movies from the year 2000, inclusive lower bound, to 2015, exclusive upper bound, that MongoDB Search returned for the query

• Number of movies for each director that MongoDB Search returned for the query

To learn more about these results, see Facet Results.

The index definition on the sample_mflix.movies collection specifies the following for the fields to index:

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

The following query searches for movies released near July 01, 1999 using the $search stage. The query includes a $facet stage to process the input documents using the following sub-pipeline stages:

• $project stage to exclude all fields in the documents except the title and released fields in the docs output field

• $limit stage to do the following:

  • Limit the $search stage output to 2 documents

  • Limit the output to 1 document in the meta output field

  Note

  The limit must be small for the results to fit in a 16 MB document.

• $replaceWith stage to include the metadata results stored in the $$SEARCH_META variable in the meta output field

The query also includes a $set stage to add the meta field.

1
db.movies.aggregate([
2
 {
3
   "$search": {
4
     "facet": {
5
       "operator": {
6
         "near": {
7
           "path": "released",
8
           "origin": ISODate("1999-07-01T00:00:00.000+00:00"),
9
           "pivot": 7776000000
10
         }
11
       },
12
       "facets": {
13
         "genresFacet": {
14
           "type": "string",
15
           "path": "genres"
16
         }
17
       }
18
     }
19
   }
20
 },
21
 { "$limit": 2 },
22
 {
23
   "$facet": {
24
     "docs": [
25
       { "$project":
26
         {
27
           "title": 1,
28
           "released": 1
29
         }
30
       }
31
     ],
32
     "meta": [
33
       {"$replaceWith": "$$SEARCH_META"},
34
       {"$limit": 1}
35
     ]
36
   }
37
 },
38
 {
39
   "$set": {
40
     "meta": {
41
       "$arrayElemAt": ["$meta", 0]
42
     }
43
   }
44
 }
45
])

1
[
2
 {
3
   docs: [
4
     {
5
       _id: ObjectId('573a1393f29313caabcde1ae'),
6
       title: 'Begone Dull Care',
7
       released: ISODate('1999-07-01T00:00:00.000Z')
8
     },
9
     {
10
       _id: ObjectId('573a13a9f29313caabd2048a'),
11
       title: 'Fara'                released: ISODate('1999-07-01T00:00:00.000Z')
12
     }
13
   ],
14
   meta: {
15
     count: { lowerBound: Long('20878') },
16
     facet: {
17
       genresFacet: {
18
         buckets: [
19
           { _id: 'Drama', count: Long('12149') },
20
           { _id: 'Comedy', count: Long('6436') },
21
           { _id: 'Romance', count: Long('3274') },
22
           { _id: 'Crime', count: Long('2429') },
23
           { _id: 'Thriller', count: Long('2400') },
24
           { _id: 'Action', count: Long('2349') },
25
           { _id: 'Adventure', count: Long('1876') },
26
           { _id: 'Documentary', count: Long('1755') },
27
           { _id: 'Horror', count: Long('1432') },
28
           { _id: 'Biography', count: Long('1244') }
29
         ]
30
       }
31
     }
32
   }
33
 }
34
]

To learn more about these results, see Facet Results.

The index definition on the sample_training.companies collection indexes the funding_rounds field as the embeddedDocuments type. It dynamically indexes all fields in the funding_rounds array of objects and stores the raised_currency_code and raised_amount fields in the funding_rounds array of objects using the storedSource option.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "funding_rounds": {
        "type": "embeddedDocuments",
        "dynamic": true,
        "storedSource": {
          "include": [
            "raised_currency_code",
            "raised_amount"
          ]
        }
      }
    }
  }
}

The following query:

• Uses the text (MongoDB Search Operator) to search for funds raised in USD .

• Uses returnScope options to set the query context to the embeddedDocuments field named funding_rounds. To use returnScope, the query:

  • Specifies the returnStoredSource option, which is required, to return the stored source fields.

• Facets on the raised_amount field in the funding_rounds array of objects. The query specifies three buckets:

  • 5000000, inclusive lower bound for this bucket

  • 5250000, exclusive upper bound for the 5000000 bucket and inclusive lower bound for this bucket

  • 5500000, exclusive upper bound for the 5250000 bucket

1
db.companies.aggregate([
2
 {
3
   "$searchMeta": {
4
     "returnStoredSource": true,
5
     "returnScope": {
6
       "path": "funding_rounds"
7
     },
8
     "facet": {
9
       "operator": {
10
         "text": {
11
           "path": "funding_rounds.raised_currency_code",
12
           "query": "USD"
13
         }
14
       },
15
       "facets": {
16
         "raisedAmountFacet": {
17
           "type": "number",
18
           "path": "funding_rounds.raised_amount",
19
           "boundaries": [5000000, 5250000, 5500000]
20
         }
21
       }
22
     }
23
   }
24
 }
25
])

1
[
2
  {
3
    count: { lowerBound: Long('5329') },
4
    facet: {
5
      raisedAmountFacet: {
6
        buckets: [
7
          { _id: 5000000, count: Long('251') },
8
          { _id: 5250000, count: Long('32') }
9
        ]
10
      }
11
    }
12
  }
13
]

In the preceding MongoDB Search results, the facet counts are based on the embedded child documents and not the parents.

The following index definition on the sample_airbnb.listingsAndReviews collection automatically indexes all dynamically indexable fields and configures the cancellation_policy, room_type, and price fields for faceted search.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "cancellation_policy": {
        "type": "token"
      },
      "room_type": {
        "type": "token"
      },
      "accommodates": {
        "type": "number"
      }
    }
  }
}

The following query uses the $searchMeta stage to perform the following actions:

• Facet on the cancellation_policy, roomType and accommodates fields.

  The cancellation_policy facet has the following buckets:

  • "strict_14_with_grace_period"

  • "moderate"

  • "flexible"

  • "super_strict_30"

  • "super_strict_60"

  The room_type facet has the following buckets:

  • "Entire home/apt"

  • "Private room"

  • "Shared room"

  The query breaks the accommodates facet into buckets for:

  • 1, inclusive lower bound for this bucket

  • 2, exclusive upper bound for the 1 bucket and inclusive lower bound for this bucket.

  • 4, exclusive upper bound for the 2 bucket and inclusive lower bound for this bucket.

  • 8, exclusive upper bound for the 4 bucket

• Perform a compound Operator search for listings that must contain the text new york city in the description and filters the results for listings with a moderate cancellation_policy. The doesNotAffect setting ensures that filtering by a moderate cancellation_policy doesn't alter the counts of other buckets in the facet; the counts for "strict_14_with_grace_period", "flexible", "super_strict_30", and "super_strict_60" are non-zero values.

1
db.listingsAndReviews.aggregate([
2
  {
3
    $searchMeta: {
4
      facet: {
5
        facets: {
6
          accommodatesFacet: {
7
            path: "accommodates",
8
            type: "number",
9
            boundaries: [1,2,4,8],
10
          },
11
          cancellationFacet: {
12
            path: "cancellation_policy",
13
            type: "string",
14
          },
15
          roomTypeFacet: {
16
            path: "room_type",
17
            type: "string",
18
          }
19
        },
20
        operator: {
21
          compound: {
22
            must: [
23
              {
24
                text: {
25
                  path: "description",
26
                  query: "new york city",
27
                },
28
              },
29
            ],
30
            filter: [
31
              {
32
                equals: {
33
                  path: "cancellation_policy",
34
                  value: "moderate",
35
                  doesNotAffect:
36
                    "cancellationFacet",
37
                },
38
              },
39
            ],
40
          },
41
        },
42
      },
43
    }
44
  },
45
]

1
[
2
  {
3
    count: { lowerBound: Long('531') },
4
    facet: {
5
      accomodatesFacet: {
6
        buckets: [
7
          { _id: "1", count: Long('25') },
8
          { _id: "2", count: Long('270') },
9
          { _id: "4", count: Long('204') },
10
        ]
11
      },
12
      cancellationFacet: {
13
        buckets: [
14
          { _id: "strict_14_with_grace_period", count: Long('849') },
15
          { _id: "moderate", count: Long('531') },
16
          { _id: "flexible", count: Long('380') },
17
          { _id: "super_strict_60", count: Long('25') }
18
          { _id: "super_strict_30", count: Long('380') }
19
        ]
20
      },
21
      roomTypeFacet: {
22
        buckets: [
23
          { _id: "Entire home/apt", count: Long('369') },
24
          { _id: "Private room", count: Long('159') },
25
          { _id: "Shared room", count: Long('3') },
26
        ]
27
      }
28
    }
29
  }
30
]

Observe that the counts for buckets in cancellationFacet are not reduced to zero despite the query filtering on a value of moderate.

The following index definition on the sample_airbnb.listingsAndReviews collection indexes the cancellation_policy, room_type, and price fields, enabling faceted search on them.

{
  "mappings": {
    "dynamic": true,
    "fields": {
      "cancellation_policy": {
        "type": "token"
      },
      "room_type": {
        "type": "token"
      },
      "accommodates": {
        "type": "number"
      }
    }
  }
}

The following query:

• Searches for listings that include the text new york city in their description and which have a cancellation_policy of moderate.

• Facets on the cancellation_policy, roomType and accommodates fields.

  Each of the cancellation_policy and roomType facets have three buckets, corresponding to the three unique values of these fields across the collection. The query breaks the accommodates facet into buckets for:

  • 1, inclusive lower bound for this bucket

  • 2, exclusive upper bound for the 1 bucket and inclusive lower bound for this bucket.

  • 4, exclusive upper bound for the 2 bucket and inclusive lower bound for this bucket.

  • 8, exclusive upper bound for the 4 bucket

• Sets the doesNotAffect property in the equals operator of the compound.filter to accommodatesFacet. This excludes the buckets within the accommodates facet from filtering. As a result, filtering on the moderate cancellation_policy reduces the counts of other buckets in the cancellation_policy facet to 0, and reduces the counts of buckets in the roomType facet, but the counts of buckets in the accommodates facet are unchanged. This allows you to compare the impact of filtering on different facets.

1
db.listingsAndReviews.aggregate([
2
  {
3
    $searchMeta: {
4
      facet: {
5
        facets: {
6
          accommodatesFacet: {
7
            path: "accommodates",
8
            type: "number",
9
            boundaries: [1,2,4,8],
10
          },
11
          cancellationFacet: {
12
            path: "cancellation_policy",
13
            type: "string",
14
          },
15
          roomTypeFacet: {
16
            path: "room_type",
17
            type: "string",
18
          }
19
        },
20
        operator: {
21
          compound: {
22
            must: [
23
              {
24
                text: {
25
                  path: "description",
26
                  query: "new york city",
27
                },
28
              },
29
            ],
30
            filter: [
31
              {
32
                equals: {
33
                  path: "cancellation_policy",
34
                  value: "moderate",
35
                  doesNotAffect:
36
                    "accommodatesFacet",
37
                },
38
              },
39
            ],
40
          },
41
        },
42
      },
43
    },
44
  },
45
]

1
[
2
  {
3
    count: { lowerBound: Long('531') },
4
    facet: {
5
      accomodatesFacet: {
6
        buckets: [
7
          { _id: "1", count: Long('25') },
8
          { _id: "2", count: Long('270') },
9
          { _id: "4", count: Long('204') },
10
        ]
11
      },
12
      cancellationFacet: {
13
        buckets: [
14
          { _id: "flexible", count: Long('XXX') },
15
          { _id: "moderate", count: Long('531') },
16
          { _id: "strict_14_with_grace_period", count: Long('XXX') },
17
        ]
18
      },
19
      roomTypeFacet: {
20
        buckets: [
21
          { _id: "Entire home/apt", count: Long('369') },
22
          { _id: "Private room", count: Long('159') },
23
          { _id: "Shared room", count: Long('3') },
24
        ]
25
      }
26
    }
27
  }
28
]