1# Synonyms Support
2
3## Overview
4
5RediSearch supports synonyms - that is searching for synonyms words defined by the synonym data structure.
6
7The synonym data structure is a set of groups, each group contains synonym terms. For example, the following synonym data structure contains three groups, each group contains three synonym terms:
8
9```
10{boy, child, baby}
11{girl, child, baby}
12{man, person, adult}
13```
14
15When these three groups are located inside the synonym data structure, it is possible to search for 'child' and receive documents contains 'boy', 'girl', 'child' and 'baby'.
16
17## The synonym search technique
18
19We use a simple HashMap to map between the terms and the group ids. During building the index, we check if the current term appears in the synonym map, and if it does we take all the group ids that the term belongs to.
20
21For each group id, we add another record to the inverted index called "\~\<id\>" that contains the same information as the term itself. When performing a search, we check if the searched term appears in the synonym map, and if it does we take all the group ids the term is belong to. For each group id, we search for "\~\<id\>" and return the combined results. This technique ensures that we return all the synonyms of a given term.
22
23## Handling concurrency
24
25Since the indexing is performed in a separate thread, the synonyms map may change during the indexing, which in turn may cause data corruption or crashes during indexing/searches. To solve this issue, we create a read-only copy for indexing purposes. The read-only copy is maintained using ref count.
26
27As long as the synonyms map does not change, the original synonym map holds a reference to its read-only copy so it will not be freed. Once the data inside the synonyms map has changed, the synonyms map decreses the reference count of its read only copy. This ensures that when all the indexers are done using the read only copy, then the read only copy will automatically freed. Also it ensures that the next time an indexer asks for a read-only copy, the synonyms map will create a new copy (contains the new data) and return it.
28
29## Quick example
30
31```
32# Create an index
33> FT.CREATE idx schema t text
34
35# Create a synonym group
36> FT.SYNUPDATE idx group1 hello world
37
38# Insert documents
39> HSET foo t hello
40(integer) 1
41> HSET bar t world
42(integer) 1
43
44# Search
45> FT.SEARCH idx hello
461) (integer) 2
472) "foo"
483) 1) "t"
49   2) "hello"
504) "bar"
515) 1) "t"
52   2) "world"
53```
54