Define Synonym Mappings in Your Atlas Search Index

The synonyms option in an Atlas Search index definition specifies synonym mappings that 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:

Add a collection of synonym documents to your cluster. Ensure that:
- Your collection is in the same database as the index that will reference the collection
- The documents are properly formatted
Reference the synonym source collection in a synonym mapping in the index definition.

A synonym mapping configures an Atlas Search index to support queries that apply synonyms from a synonym source collection in the same database as the collection you are indexing. You can use synonyms only in queries that use the text operator.

Note

Free (M0) and Shared (M2 and M5) Tier Cluster Limitation

An index definition can have only one synonym mapping.

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.

Syntax

synonyms has the following syntax in an index definition:

Syntax

1 { 
2   "synonyms": [
3     {
4       "name": "<synonym-mapping-name>",
5       "source": {
6         "collection": "<source-collection-name>"
7       },
8       "analyzer": "<synonym-mapping-analyzer>"
9     }
10   ] 
11 }

Options

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 a synonym mapping to query only fields analyzed with the same analyzer. To use synonyms with stop words, you must either index the field using the Standard Analyzer or add the synonym entry without the stop word. You can use any Atlas Search analyzer except the following: Language analyzers: `lucene.kuromoji` `lucene.cjk` Custom analyzer tokenizers and token filters: nGram Tokenizer edgeGram Tokenizer daitchMokotoffSoundex Token Filter nGram Token Filter edgeGram Token Filter shingle Token Filter wordDelimiterGraph Token Filter	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

Synonyms Source Collection Documents

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.

Note

On free and shared tier Atlas clusters, the synonyms collection can't exceed 10,000 documents.

Format of Synonyms Source Collection Documents

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. To use synonyms with stop words, you must either add the synonym entry without the stop word or index the field using the Standard Analyzer. For an example of each `mappingType` see Source Collection Document 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.

Changes to Synonyms Source Collection Documents

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.

Examples

Source Collection Document Examples

Atlas provides the documents for the following Atlas Search mapping type examples in a collection named sample_synonyms. You can load these documents on your cluster in the same database as your collection. To load these documents on your cluster, when you create the index for your collection, do the following:

When you select the Configuration Method, select the Visual Editor.
When you Add synonym mapping to your index, select Load sample collection from the Synonym source collection dropdown.

`equivalent` `mappingType`

In the following example source collection document, the mappingType is set to equivalent so that the 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.

`explicit` `mappingType`

In the following example source collection document, mappingType is set to equivalent so that the tokens beer, brew, and pint are configured to be synonyms of the input token beer.

{
  "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.

Synonym Source Collection Example

The following collection named synonymous_terms is an example synonym source collection that can be used with the movies collection in the sample_mflix database.

The sample_mflix.synonymous_terms collection contains the following documents:

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

{
  "mappingType": "explicit",
  "input": ["race"],
  "synonyms": ["contest", "rally"]
}

{
  "mappingType": "equivalent",
  "synonyms": ["dress", "apparel", "attire"]
}

{
  "mappingType": "explicit",
  "input": ["boat"],
  "synonyms": ["vessel", "sail"]
}

Index Definition Examples

The following examples for the sample_mflix.movies collection show the index definitions using static and dynamic mappings.

Static Mapping

The following index:

Configures an index with a single text field and a single synonym mapping definition that uses the mapping configured in the synonymous_terms collection.
Analyzes the plot field with the lucene.english analyzer.
Enables synonyms from the synonymous_terms collection for queries over fields analyzed with the lucene.english analyzer.

You can use the Visual Editor or the JSON Editor in the Atlas UI to configure the following index. To configure this index, after you select your configuration method, select the movies collection in the sample_mflix database.

Click Refine Your Index.
In the Field Mappings section, click Add Field.
Click Customized Configuration.

Configure the following settings in the Add Field Mapping window:

Field Name	Enable Dynamic Mapping	Data Type Configuration
Select `plot`.	Toggle to disable.	Click Add Data Type. Select String from the dropdown. Select `lucene.english` under `lucene.language` from the Index Analyzer dropdown.

Click Add.
In the Synonyms Mappings section, click Add Synonym Mapping.
Configure the following settings in the Add Synonym Mapping window:
Synonym mapping name
Synonym source collection
Analyzer
Enter my_synonyms
Select synonymous_terms.
Select lucene.english under lucene.language from dropdown.
Click Add.

Replace the default index with the following index.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "plot": {
        "type": "string",
        "analyzer": "lucene.english"
      }
    }
  },
  "synonyms": [
    {
      "analyzer": "lucene.english",
      "name": "my_synonyms",
      "source": {
        "collection": "synonymous_terms"
      }
    }
  ]
}

Dynamic Mapping

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 synonymous_terms collection.
Uses the default analyzer, lucene.standard, to analyze all the fields.
Enables synonyms from the synonymous_terms collection for queries over fields analyzed with the lucene.standard analyzer.

Click Refine Your Index.
In the Synonyms Mappings section, click Add Synonym Mapping.
Configure the following settings in the Add Synonym Mapping window:
Synonym mapping name
Synonym source collection
Analyzer
Enter my_synonyms
Select synonymous_terms.
Select lucene.standard from the dropdown if it isn't already selected.
Click Add.

{
  "mappings": {
    "dynamic": true
  },
  "synonyms": [
    {
      "analyzer": "lucene.standard",
      "name": "my_synonyms",
      "source": {
        "collection": "synonymous_terms"
      }
    }
  ]
}

Learn More

To learn how to add a collection that configures words as synonyms to your cluster, and use this collection to create an Atlas Search index and run Atlas Search queries using synonyms, see How to Use Synonyms with Atlas Search.

To see examples of text queries that use synonyms, see Synonyms Examples in the text reference page.

To see an example phrase queries that uses synonyms, see Synonyms Example in the phrase reference page.

Back

Stored Source

Index Partitions

1	{
2	"synonyms": [
3	{
4	"name": "<synonym-mapping-name>",
5	"source": {
6	"collection": "<source-collection-name>"
7	},
8	"analyzer": "<synonym-mapping-analyzer>"
9	}
10	]
11	}

Note

Free (M0) and Shared (M2 and M5) Tier Cluster Limitation

Syntax

Options

Synonyms Source Collection Documents

Note

Format of Synonyms Source Collection Documents

Warning

Changes to Synonyms Source Collection Documents

Examples

Source Collection Document Examples

equivalent mappingType

explicit mappingType

Synonym Source Collection Example

Index Definition Examples

Static Mapping

Dynamic Mapping

Learn More

`equivalent` `mappingType`

`explicit` `mappingType`