Search Configuration Options

Index Creation

The Search add-on checks the current configuration of Elasticsearch indexes and compares it to the expected ones. Further actions depend on the selected Index Schema Management Strategy:

  • create-only - every missing index will be created, existing indexes with irrelevant configuration will be kept as is.

  • create-or-recreate - every missing index will be created, existing indexes with irrelevant configuration will be recreated (all data will be lost). This is the default strategy.

  • none - missing indexes are ignored, existing indexes with irrelevant configuration will be kept as is. This option may be used if you want to operate indexes manually.

The strategy can be configured by adding the following property to your application.properties file:

jmix.search.index-schema-management-strategy = create-only

The index schema synchronization is automatically performed on application startup. Besides, it can be manually performed using synchronizeXXX operations of EntityIndexing MBean.

The EntityIndexing MBean also contains the recreateIndex operation. It drops and creates index without taking into account the current Index Schema Management Strategy, even if the target index has an actual configuration. All index data will be lost.

Index Naming

Search indexes have the following naming template: <prefix><entity_name>.

Default prefix is search_index_.

If multiple projects use the same Elasticsearch service, you should ensure that index names are unique: all projects should have unique entity names or projects should have different prefixes.

Prefixes can be configured by adding the following property to your application.properties file:

jmix.search.search-index-name-prefix = demo_prefix_

Also you can specify full index name in indexName attribute of @JmixEntitySearchIndex.

Existing Data Indexing

There are two approaches to existing data indexing:

  • Automatic - is a part of the index schema synchronization and enabled by default. It enqueues all instances of each entity whose index has been created (in the background process). Automatic indexing can be enabled for specific entities only.

  • Manual - by using the enqueueIndexAll operation of EntityIndexing MBean.

To enable automatic indexing for specific entities, add the following application property:

jmix.search.enqueue-index-all-on-startup-index-recreation-entities = Order_,Customer

Also, you can completely disable automatic indexing by adding the following application property:

jmix.search.enqueue-index-all-on-startup-index-recreation-enabled = false

Entities Tracking

By default, the system tracks changes of indexed entities. It stores information about all entity instances affected by the changes to the indexing queue.

This behavior can be disabled by adding the following application property:

jmix.search.changed-entities-indexing-enabled = false

Security Roles

To utilize the functionality of the Search add-on, users with limited access to the system should have one of the following roles:

  • Search: edit filter provides permissions to add full-text search conditions to the filter.

  • Search: view search results provides permissions to access the Search Results view.

Index Settings and Analysis

The add-on allows you to configure index settings including analysis.

This configuration depends on used search platform (OpenSearch or Elasticsearch) and should be recreated accordingly if you switch between them.

  • Create a Spring bean that implements OpenSearchIndexSettingsConfigurer (or ElasticsearchIndexSettingsConfigurer in case of Elasticsearch usage).

  • Implement method configure(OpenSearchIndexSettingsConfigurationContext).

Implementation

Settings can be configured via settings builder (belongs to OpenSearch/Elasticsearch Java API client).

Configuration context provides two types of settings builder:

  • Common - allows you to configure settings that will be applied to all indexes. Can be acquired via context.getCommonSettingsBuilder().

  • Entity specific - allows you to configure settings that will be applied only to index for specific entity. Entity specific settings has higher priority and override the common settings. Can be acquired via context.getEntitySettingsBuilder(Class).

Use builder’s methods to set corresponding index settings.

Use .analysis() to start building chain that allows you to create custom analyzers, tokenizers, etc.

@Component
public class CustomOpenSearchIndexSettingsConfigurer implements OpenSearchIndexSettingsConfigurer {

    @Override
    public void configure(OpenSearchIndexSettingsConfigurationContext context) {
        IndexSettings.Builder commonSettingsBuilder = context.getCommonIndexSettingsBuilder();
        commonSettingsBuilder
                .maxResultWindow(15000)
                .analysis(analysisBuilder ->
                        analysisBuilder.analyzer("customized_standard", analyzerBuilder ->
                                analyzerBuilder.standard(stdAnalyzerBuilder ->
                                        stdAnalyzerBuilder.maxTokenLength(100)
                                )
                        )
                );

        IndexSettings.Builder orderSettingsBuilder = context.getEntityIndexSettingsBuilder(Order.class);
        orderSettingsBuilder
                .maxResultWindow(15000)
                .maxRegexLength(2000)
                .analysis(analysisBuilder ->
                        analysisBuilder.analyzer("customized_standard", analyzerBuilder ->
                                analyzerBuilder.standard(stdAnalyzerBuilder ->
                                        stdAnalyzerBuilder.maxTokenLength(150)
                                )
                        )
                );
    }
}