Define Synonym Mappings in Your Atlas Search Index

On this page

Syntax

Options
Synonyms Source Collection Documents
Format of Synonyms Source Collection Documents
Changes to Synonyms Source Collection Documents
mappingType Examples
equivalent
explicit
Example
Collection Example
Synonym Source Collection Example
Index Definition Examples
Static Mapping
Dynamic Mapping

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:

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

Syntax

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   "storedSource": <boolean> | {
11     <stored-source-definition>
12   },
13   "synonyms": [
14     {
15       "name": "<synonym-mapping-name>",
16       "source": {
17         "collection": "<source-collection-name>"
18       },
19       "analyzer": "<synonym-mapping-analyzer>"
20     }
21   ] 
22 }
23

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 any Atlas Search analyzer except the `lucene.kuromoji` language analyzer and the following custom analyzer tokenizers and token filters: nGram Tokenizer edgeGram Tokenizer daitchMokotoffSoundex Token Filter nGram Token Filter edgeGram Token Filter shingle Token Filter Note 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.	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.

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. Note Atlas Search considers each string, regardless of the number of words within, to be a single token. For example, Atlas Search tokenizes the string `sushi chef` as a single term and doesn't return any results for a search for `sushi` or `chef` individually. 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 `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.

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.

`mappingType` Examples

`equivalent`

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.

`explicit`

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.

Example

The examples on this page include:

A sample collection titled user_feedback.comments.
A sample synonyms source collection titled user_feedback.synonyms.
Index definition examples that rely on documents in both of these collections.

Collection Example

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

Synonym Source Collection Example

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"]
}

Index Definition Examples

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.

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 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"
      }
    }
  ]
}

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 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"
      }
    }
  ]
}

← Define Stored Source Fields in Your Atlas Search Index Review Atlas Search Index Syntax →

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	"storedSource": <boolean> \| {
11	<stored-source-definition>
12	},
13	"synonyms": [
14	{
15	"name": "<synonym-mapping-name>",
16	"source": {
17	"collection": "<source-collection-name>"
18	},
19	"analyzer": "<synonym-mapping-analyzer>"
20	}
21	]
22	}
23

Syntax

Options

Synonyms Source Collection Documents

Format of Synonyms Source Collection Documents

Changes to Synonyms Source Collection Documents

mappingType Examples

equivalent

explicit

Example

Collection Example

Synonym Source Collection Example

Index Definition Examples

Static Mapping

Dynamic Mapping

`mappingType` Examples

`equivalent`

`explicit`