Join us Sept 17 at .local NYC! Use code WEB50 to save 50% on tickets. Learn more >
MongoDB Event
Docs Menu
Docs Home
/
Atlas
/
Atlas Search
/
Queries & Indexes
/
Index Reference

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:

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

  2. 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) 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:

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

Collection Document 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:

  1. When you select the Configuration Method, select the Visual Editor.

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

Back

Stored Source

Next

Index Partitions

On this page