Docs Menu

Define Synonym Mappings in Your Atlas Search Index

On this page

synonyms allow you to index and search your collection for words that have the same or nearly the same meaning. To configure an Atlas Search index with synonym mappings, you must:

  1. Create a new collection with properly formatted synonym documents in it. Ensure that:

    • Your collection is in the same database as the index that will reference the collection.
    • You format the documents in the collection as described in the Synonyms Source Collection Documents.
  2. Reference the synonym source collection in a synonym mapping in the index definition.

This page describes the format of the synonyms source collection and how to define synonym mappings that reference the synonym source collection in your Atlas Search index. A synonym mapping configures an Atlas Search index to support queries that apply synonyms from a separate synonym source collection. You can use the JSON Editor view in the Atlas User Interface or the Atlas Search API to create the index. Synonyms can be used only in queries that use the text operator.

synonyms has the following syntax in an index definition:

1{ 
2  "name": "<index-name>", 
3  "analyzer": "<analyzer-for-index>", 
4  "searchAnalyzer": "<analyzer-for-query>", 
5  "mappings": { 
6    "dynamic": <boolean>, 
7    "fields": { <field-definition> } 
8  }, 
9  "analyzers": [ <custom-analyzer> ],
10  "synonyms": [
11    {
12      "name": "<synonym-mapping-name>",
13      "source": {
14        "collection": "<source-collection-name>"
15      },
16      "analyzer": "<synonym-mapping-analyzer>"
17    }
18  ] 
19}

synonyms takes the following fields in an index definition:

Field
Type
Description
Necessity
analyzer
string

Name of the analyzer to use with this synonym mapping. You can use any Atlas Search analyzer except the lucene.kuromoji language analyzer and the following custom analyzer tokenizers and token filters:

Required
name
string
Name of the synonym mapping. Name must be unique in the index definition. Value can't be an empty string.
Required
source
document
Source collection for synonyms. The source option takes the collection field.
Required
source.collection
string
Name of the MongoDB collection that is in the same database as the Atlas Search index. Documents in this collection must be in the format described in the Synonyms Source Collection Documents.
Required

Each document in the collection specified as the source for the synonyms describe how one or more words map to one or more synonyms of those words.

You must configure each document with the following fields:

Field
Type
Description
Necessity
input
array of strings

Required for mappingType: explicit mappings.

For explicit mappings, synonyms values are synonyms of each input token. Value can't be an empty or all-whitespace string. You can specify the same input value in multiple documents.

Conditional
mappingType
string

Type of mapping. Value can be one of the following:

  • equivalent - describes a set of tokens that are equivalent to one another. For an example of this mappingType, see Example.
  • explicit - matches input tokens and replaces them with all alternative synonyms tokens. For an example of this mappingType, see Example.
Required
synonyms
array of strings

Words that are synonyms of one another if mappingType is equivalent or synonyms of input tokens if mappingType is explicit. synonyms must have at least one value.

For an example of each mappingType see mappingType Examples.

Required

The documents in the collection can contain other fields. The documents in the collection are additive, and mappings are deduplicated. Atlas Search synonyms are stored as a separate Atlas collection, which counts against the same storage quota as any other collection in Atlas. Atlas Search might use more compute resources to apply synonyms from larger synonyms source collections.

Warning

Don't include invalid synonym documents in the synonym source collection. Atlas Search doesn't create indexes if the indexes use synonym mappings that reference collections with invalid documents. Only include synonym documents that are properly formatted in your synonym source collection.

MongoDB doesn't recommend adding synonym documents to synonym source collections in a production environment without first validating that they are properly formatted and behave as expected in a test environment.

If you make changes to your synonyms source collection:

  • You don't need to reindex because Atlas Search watches for changes and automatically updates its internal synonym map.
  • The time it takes Atlas Search to update the synonym mappings increases with the synonym source collection size. Note that the changes to synonym documents are reflected in your Atlas Search query results eventually.
Example

In this equivalent mapping type example, the synonyms tokens car, vehicle, and automobile are configured to be synonyms of one another:

{
  "mappingType": "equivalent",
  "synonyms": ["car", "vehicle", "automobile"]
}

For a text query for car, vehicle, or automobile applying a synonym mapping that includes such a document, Atlas Search returns documents that contain the term car, vehicle, or automobile.

Example

In this explicit mapping type example, input token beer is configured to consider beer, brew, and pint as synonyms:

{
  "mappingType": "explicit",
  "input": ["beer"],
  "synonyms": ["beer", "brew", "pint"]
}

For a text query for beer applying a synonym mapping that includes such a document, Atlas Search returns documents that contain the terms "beer", "brew", or "pint" because the input token beer is explicitly mapped to all these synonyms tokens. However, for a query for pint, Atlas Search does not find documents that contain beer because pint is not explicitly mapped to beer.

The examples on this page include:

user_feedback.comments contains the following documents:

{
  "type": "car dealer",
  "comments": "Blue four-door sedan, lots of trunk space in the car."
}
{
  "type": "winery",
  "comments": "Beer and skittles for all."
}
{
  "type": "apparel store",
  "comments": "Beautiful apparel for the bride."
}
{
  "type": "recreation rental",
  "comments": "Sails as well as the day it was made."
}

The following collection titled user_feedback.synonyms is an example synonym source collection for the user_feedback.comments collection.

Note

To learn how to format the documents in the collection, see Synonyms Source Collection Documents.

user_feedback.synonyms contains the following documents:

{
  "mappingType": "equivalent",
  "synonyms": ["car", "vehicle", "automobile"]
}
{
  "mappingType": "explicit",
  "input": ["beer"],
  "synonyms": ["beer", "brew", "pint"]
}
{
  "mappingType": "equivalent",
  "synonyms": ["dress", "apparel", "attire"]
}
{
  "mappingType": "explicit",
  "input": ["boat"],
  "synonyms": ["boat", "vessel", "sail"]
}

The following examples for the user_feedback.comments collection show the index definitions using static and dynamic mappings.

Note

For sample queries on the user_feedback.comments collection using the following indexes, see examples in the text operator.

The following index:

  • Configures an index with a single text field and a single synonym mapping definition that uses the mapping configured in the user_feedback.synonyms collection.
  • Analyzes the comments field with the lucene.english analyzer.
  • Enables synonyms from synonyms collection for queries over fields analyzed with the lucene.english analyzer.
{
  "mappings": {
    "dynamic": false,
    "fields": {
      "comments": {
        "type": "string",
        "analyzer": "lucene.english"
      }
    }
  },
  "synonyms": [
    {
      "analyzer": "lucene.english",
      "name": "mySynonyms",
      "source": {
        "collection": "synonyms"
      }
    }
  ]
}

The following index:

  • Configures an index for all the fields in the documents and a single synonym mapping definition that uses the mapping configured in the user_feedback.synonyms collection.
  • Uses the default analyzer, lucene.standard, to analyze all the fields.
  • Enables synonyms from synonyms collection for queries over fields analyzed with the lucene.standard analyzer.
{
  "mappings": {
    "dynamic": true
  },
  "synonyms": [
    {
      "analyzer": "lucene.standard",
      "name": "mySynonyms",
      "source": {
        "collection": "synonyms"
      }
    }
  ]
}

On this page

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center

Support

Social

© 2021 MongoDB, Inc.