Docs Menu

How to use Synonyms with Atlas Search

On this page

  • Load the Sample Synonyms Source Collection
  • Create the Atlas Search Index With Synonym Mapping Definition
  • Search the Collection

This tutorial describes how to add a collection that configures words as synonyms, create an index that defines synonym mappings on the sample_mflix.movies collection, and run Atlas Search queries against the title field using words that are configured as synonyms. It takes you through the following steps:

  1. Load a sample synonyms source collection in the sample_mflix database.
  2. Set up an Atlas Search index with synonym mapping for the sample_mflix.movies collection.
  3. Run Atlas Search queries against the title field in the sample_mflix.movies collection for words configured as synonyms in the synonyms source collection.

Before you begin, ensure that your Atlas cluster meets the requirements described in the Prerequisites.

Each document in the synonyms source collection describe how one or more words map to one or more synonyms of those words. To learn more about the fields and word mapping types in the synonyms source collection documents, see Format of Synonyms Source Collection Documents.

You must begin by creating the synonyms source collection and then add the collection to the database where you intend to use the synonyms source collection. In this section, you will create a sample synonyms source collection in the sample_mflix database, then use that synonyms source collection with an index of the movies collection in the same database.

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. If the Database Deployments page is not already displayed, click Databases in the sidebar.
2
3
  1. Expand the sample_mflix database and click the icon to open the Create Collection modal.
  2. Type sample_synonyms in the Collection name field.
  3. Click Create to create the collection in the sample_mflix database.
4
  1. Select the sample_synonyms collection if it's already not selected.
  2. Click Insert Document for each of the sample documents to add to the collection.
  3. Click the JSON view ({}) to replace the default document.
  4. Copy and paste the following sample documents, one at a time, and click Insert to add the documents, one at a time, to the collection.

    {
    "mappingType": "equivalent",
    "synonyms": ["car", "vehicle", "automobile"]
    }
    {
    "mappingType": "explicit",
    "input": ["boat"],
    "synonyms": ["boat", "vessel", "sail"]
    }

The synonym mapping in a collection's index specifies the synonyms source collection and the analyzer to use with the collection.

In this section, you will create an Atlas Search index that defines a synonym mapping named mySynonyms for the sample_mflix.movies collection. The mySynonyms mapping definition in the index references the synonyms source collection named sample_synonyms that you created in the sample_mflix database and uses the lucene.english language analyzer.

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 synonym mapping definition.

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": {
"title": {
"analyzer": "lucene.english",
"type": "string"
}
}
},
"synonyms": [
{
"analyzer": "lucene.english",
"name": "mySynonyms",
"source": {
"collection": "sample_synonyms"
}
}
]
}

The above index definition specifies:

  • The language analyzer lucene.english as the default analyzer for both indexing and querying the title field.
  • The name mySynonyms as the name for this synonym mapping.
  • The sample_synonyms collection as the source synonyms collection to look for synonyms for queries using mySynonyms mapping. mySynonyms can be used in text queries over any field indexed with the lucene.english analyzer (including the title field, in this example).
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.

Synonyms can be used only in queries that use the text operator. In this section, you will connect to your Atlas cluster and the run the sample queries using the text operator against the title field in the sample_mflix.movies collection. The sample queries use words that are configured as synonyms of different mapping types in the synonyms source collection, which is referenced in the synonyms mapping named mySynonyms that is used by the queries.

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

Atlas Search query results vary based on the type of word mapping defined in the synonyms source collection.

Give Feedback
© 2021 MongoDB, Inc.

About

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