Webiny Docs home page
What you'll learn
  • how to how to change Elasticsearch index name to contain locale code.
This article requires advanced knowledge of the Elasticsearch.

Overview
anchor

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?
anchor

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
anchor

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
anchor

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

1. Backup
anchor

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

2. Update Your Environment Variables to Contain Feature Flag
anchor

You need to set the WEBINY_ELASTICSEARCH_INDEX_LOCALE environment variable to true.

Skip this step if your CI automatically deploys the code when environment variable changes.

3. Lock Your Original Index
anchor

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.

POST root-page-builder
{
  "index.blocks.read_only": true
}

4. Figure Out the Name for Your New Elasticsearch Index
anchor

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
anchor

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

The action to be executed:

POST root-page-builder/_clone/root-en-gb-page-builder

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

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

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

7. Repeat Previous Steps for All the Indexes
anchor

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
anchor

POST root-en-gb-page-builder
{
  "index.blocks.read_only": false
}

9. Deploy the Code for Environment Variable to Have Effect
anchor

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

Option 2: Add the Alias to the Original Elasticsearch Index
anchor

Our preferred option is the first one as we will, probably, use Elasticsearch Index Aliases in some later versions to extend the search capabilities. If you go with this option, use it at your own risk of having issues with the system in later versions.

We will use the Create or update alias API external link.

1. Backup
anchor

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

2. Figure Out the Name for Your New Elasticsearch Index
anchor

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
anchor

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

The action to be executed:

POST root-page-builder/_alias/root-en-gb-page-builder
{
  "filter": {
    "bool": {
      "must": [
        {
          "term": {
            "locale.keyword": "en-GB"
          }
        }
      ]
    }
  },
  "is_write_index": true
}

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
anchor

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
anchor

You need to set the WEBINY_ELASTICSEARCH_INDEX_LOCALE environment variable to true.

5. Deploy the Code for Environment Variable to Have Effect
anchor