Docs Menu

How to Use Facets with Atlas Search

On this page

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

Atlas Search facet and count are in preview, but can be used in production applications. If there are any syntax or behavior changes between the preview stage and general availability (GA), we will proactively communicate before introducing any breaking changes. The MongoDB Cloud Support team will help troubleshoot any issues related to using this feature as part of your contract.

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, in addition to the prerequisites listed in the Tutorials page, you must have an Atlas cluster running one of the following versions:

  • MongoDB 4.4.11 or later
  • MongoDB 5.0.4 or later

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
  • For a guided experience, select Visual Editor.
  • To edit the raw index definition, select JSON Editor.
4
  1. In the Index Name field, enter default.

    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.

  2. In the Database and Collection section, find the sample_mflix database, and select the movies collection.
5

The following index definition 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
Note

Atlas Search support for faceting on numeric and date fields using number and date type is being deprecated. Although you can continue using existing facet definitions on the number and date types, make a note of the following:

  • We recommend using the new numberFacet and dateFacet types in all index definitions for faceting on numeric and date fields, respectively.
  • Support for faceting on numeric and date fields using number and date types will be removed in August 2022.

You can use the Visual Editor or the JSON Editor in the Atlas user interface to create the index.

  1. Click Next.
  2. Click Refine Your Index.
  3. Change Dynamic Mapping to Off.
  4. Add the following fields in the Field Mappings section:

    Field Name
    Dynamic Mapping
    Data Type Configuration
    genres
    Change Enable Dynamic Mapping to Off.
    Click Add Data Type, and select StringFacet.
    year
    Change Enable Dynamic Mapping to Off.
    Click Add Data Type, and select NumberFacet.
    released
    Change Enable Dynamic Mapping to Off.
    Click Add Data Type, and select Date.
  1. Replace the default definition with the following:

    {
    "mappings": {
    "dynamic": false,
    "fields": {
    "genres": {
    "type": "stringFacet"
    },
    "year": {
    "type": "numberFacet"
    },
    "released": {
    "type": "date"
    }
    }
    }
    }
  2. Click Next.
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.


Use the Select your language drop-down menu to set the language of the examples in this section.


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.

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
←  How to Run Atlas Search Queries with a Date Range FilterHow to Run Partial Match Atlas Search Queries →

Select your language

Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.