How to Change Elasticsearch Index Name to Contain Locale

Overview

If you created you project with 5.26.0 or greater, this article is not for you.

Prior to the 5.26.0 version of Webiny, we did not add locale code to the Elasticsearch index names of File Manager, Form Builder and Page Builder applications.

In the 5.26.0 we added an environment variable WEBINY_ELASTICSEARCH_INDEX_LOCALE which serves as a feature flag to insert the locale code into each of the Elasticsearch index names created.

When Would You Need to Change the Elasticsearch Index Name to Contain Locale Code?

Answers is actually quite simple: when you want to have different mappings for different locales, eg. Japanese. With old setup, all the data, in all locales, is stored in the same Elasticsearch index.

With new setup, each of the tenant/locale combination has its own index, so you can have different mappings for different locales.

Steps on How to Change the Elasticsearch Index Name to Contain Locale Code

There are different options on how to approach this problem. If you use one option, no need to use another.

Option 1: Renaming the Original Elasticsearch Index

This will cover cloning the existing Elasticsearch index to another one (with name which contains the locale code).

This will NOT change the Elasticsearch index mappings or settings for the new index.

We will use the Clone index API.

1. Backup

Make sure you do a backup the index you are cloning.

2. Update Your Environment Variables to Contain Feature Flag

You need to set the WEBINY_ELASTICSEARCH_INDEX_LOCALE environment variable to true.

3. Lock Your Original Index

This will produce errors on the input side, so make sure your users know not to touch anything, but this is required for clone to work.

4. Figure Out the Name for Your New Elasticsearch Index

The article How To Customize Elasticsearch Index contains the information on how we create the index names.

Page Builder Index Name Example

We will work with the tenant root, so the name of existing index is root-page-builder. The new Elasticsearch index name will contain the locale your system is on. Let’s say if the system is on en-GB locale, then the new Elasticsearch index name would be root-en-gb-page-builder. Note that GB is in lower case - it is because the Elasticsearch does not support index names with upper case.

5. Execute the Cloning Process via Kibana

… or what ever tool you are using to access the Elasticsearch.

The action to be executed:

It might take a while to clone the original index, if you have a lot of data. The Elasticsearch documentation has example on how to monitor the cloning process.

6. Verify That New Index Is Working and It Contains All the Data

Use what ever tool or script you have at your disposal.

7. Repeat Previous Steps for All the Indexes

You MUST repeat previous steps for of the indexes you have (except Headless CMS ones, of course) because the environment variable you add will affect all the applications.

8. Verify That Newly Created Elasticsearch Index Is Not Locked for Writing

9. Deploy the Code for Environment Variable to Have Effect

… or set the required environment variable if you have skipped step 2.

Option 2: Add the Alias to the Original Elasticsearch Index

We will use the Create or update alias API.

1. Backup

Make sure you do a backup the index you are changing.

2. Figure Out the Name for Your New Elasticsearch Index

The article How To Customize Elasticsearch Index contains the information on how we create the index names.

Page Builder Index Name Example

We will work with the tenant root, so the name of existing index is root-page-builder. The new Elasticsearch index name will contain the locale your system is on. Let’s say if the system is on en-GB locale, then the new Elasticsearch index name would be root-en-gb-page-builder. Note that GB is in lower case - it is because the Elasticsearch does not support index names with upper case.

3. Execute the Action to Create Index Alias via Kibana

… or what ever tool you are using to access the Elasticsearch directly.

The action to be executed:

Note that we filter the data which only contains locale in en-GB.

By having the filter, we ensure that querying this alias fetches data only for the given locale.

7. Repeat Previous Steps for All the Indexes

You MUST repeat previous steps for of the indexes you have (except Headless CMS ones, of course) because the environment variable you add will affect all the applications.

4. Update Your Environment Variables to Contain Feature Flag

You need to set the WEBINY_ELASTICSEARCH_INDEX_LOCALE environment variable to true.

5. Deploy the Code for Environment Variable to Have Effect