Synonyms API quick start

This interactive notebook will introduce you to the Synonyms API (blog post, API documentation) using the official Elasticsearch Python client. Synonyms allow you to enhance search relevancy by defining relationships between terms that have the similar meanings. In this notebook, you'll create & update synonyms sets, configure an index to use synonyms, and run queries that leverage synonyms for enhanced relevancy.

Create Elastic Cloud deployment

If you don't have an Elastic Cloud deployment, sign up here for a free trial.

Once logged in to your Elastic Cloud account, go to the Create deployment page and select Create deployment. Leave all settings with their default values.

Install packages and import modules

To get started, we'll need to connect to our Elastic deployment using the Python client. Because we're using an Elastic Cloud deployment, we'll use the Cloud ID to identify our deployment.

First we need to install the elasticsearch Python client.

Initialize the Elasticsearch client

Now we can instantiate the Elasticsearch python client, providing the cloud id and password in your deployment.

If you're running Elasticsearch locally or self-managed, you can pass in the Elasticsearch host instead. Read more on how to connect to Elasticsearch locally.

Enable Telemetry

Knowing that you are using this notebook helps us decide where to invest our efforts to improve our products. We would like to ask you that you run the following code to let us gather anonymous usage statistics. See telemetry.py for details. Thank you!

Test the Client

Before you continue, confirm that the client has connected with this test.

Configure & populate the index

Our client is set up and connected to our Elastic deployment. Now we need to configure the index that will store our test data and populate it with some documents. We'll use a small index of books with the following fields:

• title
• authors
• publish_date
• num_reviews
• publisher

Create synonyms set

Let's create our initial synonyms set first.

Configure the index

Ensure that you do not have a previously created index with the name book_index.

🔐 NOTE: at any time you can come back to this section and run the delete function above to remove your index and start from scratch.

In order to use synonyms, we need to define a custom analyzer that uses the synonym or synonym_graph token filter. Let's create an index that's configured to use an appropriate custom analyzer.

There are a few things to note in the configuration:

• We are using the synonym_graph token filter.
• We have defined two analyzers: my_custom_index_analyzer and my_custom_search_analyzer. my_custom_search_analyzer is used as a search analyzer.
• my_synonym_filter is used only in my_custom_search_analyzer.

The synonym_graph token filter allows us to use multi-word synonyms. However, it is important to apply this filter only at search time, hence why we use it only in my_custom_search_analyzer. And since synonyms are only applied at search time, we can update them without reindexing.

See The same, but different: Boosting the power of Elasticsearch with synonyms for more background information about search-time synonyms.

Populate the index

Run the following command to upload some test data, containing information about 10 popular programming books from this dataset.

Aside: Pretty printing Elasticsearch search results

Your search API calls will return hard-to-read nested JSON. We'll create a little function called pretty_search_response to return nice, human-readable outputs from our examples.

Run queries

Let's use our synonyms in some Elasticsearch queries. We'll start by searching for books about Javascript.

Notice that even though we searched for the term "java script", we got results containing the terms "JS" and "JavaScript". Our synonyms are working!

Now let's try searching for books about AI.

We didn't get any results! There are some books that use the terms "artificial intelligence", but not "AI". Let's try using the Synonyms API to add a new synonym rule for "AI" so the previous query returns results.

If we run the query again, we should now get some results.

Conclusion

The Synonyms API allows you to dynamically create & modify the synonyms used in your search index in real time. After reading this notebook, you should have all you need to start integrating the Synonyms API into your search experience!