Core Development Concepts > Extending and Customizing
How to Change Elasticsearch Index Name to Contain Locale
Learn how to change Elasticsearch index name to contain locale code.
- how to how to change Elasticsearch index name to contain locale code.
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
.