Docs Menu

How to use Facets with Atlas Search

On this page

  • Prerequisites
  • Create the Atlas Search Index for Facet
  • Search the Collection

This tutorial describes how to create an index with a facet definition on string, date, and numeric fields in the sample_mflix.movies collection. It shows how to run an Atlas Search query against those fields for results grouped by values for the string field and by ranges for the date and numeric fields, including the count for each of those groups. It takes you through the following steps:

  1. Set up an Atlas Search index with facet definition on the genres, released, and year fields in the sample_mflix.movies collection.
  2. Run Atlas Search query against the released field in the sample_mflix.movies collection for results grouped by values for the genres field and by ranges for the year field.

To complete these tutorials, you must have the following:

  • An Atlas cluster running MongoDB v4.4 or higher.
  • The sample datasets loaded into your Atlas cluster. You will use a collection with movie data from the Atlas sample dataset.
  • mongosh on your local machine.
  • The enableSearchMeta flag enabled for your v4.4 cluster and featureFlagSearchMeta flag enabled for v5.0.0 or higher cluster. To verify that the flag is set on your cluster, connect to your cluster and run the following command:

    • For cluster running MongoDB v4.4:

      db.adminCommand( { getParameter : 1, "enableSearchMeta" : 1 } )
    • For cluster running MongoDB v5.0.0 or higher:

      db.adminCommand( { getParameter : 1, "featureFlagSearchMeta" : 1 } )

In this section, you will create an Atlas Search index on the genres, year, and released fields in the sample_mflix.movies collection.

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
  3. Click your cluster's name.
  4. Click the Search tab.
2
3

The Visual Editor Configuration Method doesn't support stringFacet.

4
  1. In the Index Name field, enter default.

    The index name defaults to default. You can leave the default name in place or choose one of your own.

    Note

    If you name your index default, you don't need to specify an index parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the index parameter.

    Index names must be unique within their namespace.

  2. In the Database and Collection section, find the sample_mflix database, and select the movies collection.
5
{
"mappings": {
"dynamic": false,
"fields": {
"genres": {
"type": "stringFacet"
},
"year": {
"type": "number"
},
"released": {
"type": "date"
}
}
}
}

The index definition above uses lucene.standard as the default analyzer for both indexing and querying the fields and specifies the following for the fields to index:

Field Name
Data Type
genres
year
released
6
7

A modal window appears to let you know your index is building. Click the Close button.

8

The index should take about one minute to build. While it is building, the Status column reads Build in Progress. When it is finished building, the Status column reads Active.

You can use facet in queries that use the $search and $searchMeta stages. In this section, connect to your Atlas cluster and the run the sample query against the sample_mflix.movies collection using the $searchMeta stage. MongoDB recommends using the $searchMeta stage to retrieve metadata results only.

1

Open mongosh in a terminal window and connect to your cluster. For detailed instructions on connecting, see Connect via mongosh.

2

Run the following command at mongosh prompt:

use sample_mflix
3

The following query searches for movies released near November 11, 1921. It specifies a pivot distance from origin of approximately three months. It requests metadata on the genres and year field. The query requests a count of the:

  • Number of movies in each genre in the genres string array field
  • Number of movies in the years 1910 to 1939, inclusive
db.movies.aggregate([
{
"$searchMeta": {
"facet": {
"operator": {
"near": {
"path": "released",
"origin": ISODate("1921-11-01T00:00:00.000+00:00"),
"pivot": 7776000000
}
},
"facets": {
"genresFacet": {
"type": "string",
"path": "genres"
},
"yearFacet" : {
"type" : "number",
"path" : "year",
"boundaries" : [1910,1920,1930,1940]
}
}
}
}
}
])

The query returns the following results:

1{
2 "count" : {
3 "lowerBound" : NumberLong(23026)
4 },
5 "facet" : {
6 "genresFacet" : {
7 "buckets" : [
8 { "_id" : "Drama", "count" : NumberLong(13527) },
9 { "_id" : "Comedy", "count" : NumberLong(6922) },
10 { "_id" : "Romance", "count" : NumberLong(3615) },
11 { "_id" : "Crime", "count" : NumberLong(2649) },
12 { "_id" : "Thriller", "count" : NumberLong(2603) },
13 { "_id" : "Action", "count" : NumberLong(2505) },
14 { "_id" : "Documentary", "count" : NumberLong(2041) },
15 { "_id" : "Adventure", "count" : NumberLong(2016) },
16 { "_id" : "Horror", "count" : NumberLong(1662) },
17 { "_id" : "Biography", "count" : NumberLong(1373) }
18 ]
19 },
20 "yearFacet" : {
21 "buckets" : [
22 { "_id" : 1910, "count" : NumberLong(23) },
23 { "_id" : 1920, "count" : NumberLong(89) },
24 { "_id" : 1930, "count" : NumberLong(308) }
25 ]
26 }
27 }
28}

The results show metadata results for two types of facet search. The genresFacet document shows the number of movies in each genre and the yearFacet document shows a count of the number of movies within the boundaries:

  • 1910, inclusive lower bound the 1910 bucket
  • 1920, exclusive upper bound for the 1910 bucket and inclusive lower bound for the 1920 bucket
  • 1930, exclusive upper bound for the 1920 bucket and inclusive lower bound for the 1930 bucket
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.