Параметры конфигурации поиска

Создание индексов

Дополнение Search проверяет текущую конфигурацию индексов Elasticsearch и сравнивает ее с ожидаемой. Дальнейшие действия зависят от выбранной стратегии управления схемой индекса:

  • create-only - каждый отсутствующий индекс будет создан, существующие индексы с нерелевантной конфигурацией останутся как есть.

  • create-or-recreate - каждый отсутствующий индекс будет создан, существующие индексы с нерелевантной конфигурацией будут пересозданы (все данные будут потеряны). Это стратегия по умолчанию.

  • Стратегия create-or-update управляет поисковыми индексами, создавая отсутствующие и обновляя конфигурацию существующих без их полного пересоздания.

    При использовании этой стратегии:

    • Если в существующий индекс добавляется новое поле или поля, индекс не будет пересоздан. Все ранее проиндексированные экземпляры останутся в индексе (с данными, соответствующими старой конфигурации), в то время как вновь индексируемые экземпляры будут добавлены с новой конфигурацией (включающей дополнительное поле или поля).

    • Если какие-либо поля удалены из индекса, этот индекс станет недоступным. Такой индекс должен быть пересоздан вручную с использованием JMX-консоли.

  • none - отсутствующие индексы игнорируются, существующие индексы с нерелевантной конфигурацией останутся как есть. Эта опция может быть использована, если вы хотите управлять индексами вручную.

Стратегия может быть настроена путем добавления следующего свойства в ваш файл application.properties:

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

Синхронизация схемы индекса автоматически выполняется при запуске приложения. Кроме того, она может быть выполнена вручную с использованием операций synchronizeXXX EntityIndexing MBean.

EntityIndexing MBean также содержит операцию recreateIndex. Она удаляет и создает индекс без учета текущей стратегии управления схемой индекса, даже если целевой индекс имеет актуальную конфигурацию. Все данные индекса будут потеряны.

Именование индексов

Индексы поиска имеют следующий шаблон именования: <prefix><entity_name>.

Префикс по умолчанию - search_index_.

Если несколько проектов используют один и тот же сервис Elasticsearch, вы должны обеспечить уникальность имен индексов: все проекты должны иметь уникальные имена сущностей или проекты должны иметь разные префиксы.

Префиксы могут быть настроены путем добавления следующего свойства в ваш файл application.properties:

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

Также вы можете указать полное имя индекса в атрибуте indexName аннотации @JmixEntitySearchIndex.

Индексация существующих данных

Существует два подхода к индексации существующих данных:

  • Автоматический - является частью синхронизации схемы индекса и включен по умолчанию. Он ставит в очередь все экземпляры каждой сущности, индекс для которой был создан (в фоновом процессе). Автоматическая индексация может быть включена только для определенных сущностей.

  • Ручной - с использованием операции enqueueIndexAll EntityIndexing MBean.

Чтобы включить автоматическую индексацию для определенных сущностей, добавьте следующее свойство приложения:

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

Также вы можете полностью отключить автоматическую индексацию, добавив следующее свойство приложения:

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

Отслеживание сущностей

По умолчанию система отслеживает изменения индексированных сущностей. Она сохраняет информацию обо всех экземплярах сущностей, затронутых изменениями, в очередь индексации.

Это поведение может быть отключено путем добавления следующего свойства приложения:

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

Роли безопасности

Для использования функциональности дополнения Search пользователи с ограниченным доступом к системе должны иметь одну из следующих ролей:

  • Search: edit filter предоставляет разрешения на добавление условий полнотекстового поиска в фильтр.

  • Search: view search results предоставляет разрешения на доступ к экрану результатов поиска.

Настройки индекса и анализ

Дополнение позволяет вам настраивать параметры индекса, включая конфигурацию анализа.

Эта настройка зависит от вашей поисковой платформы (OpenSearch или Elasticsearch) и должна быть пересоздана при переключении между ними.

API конфигурации

API конфигурации был переработан, чтобы разделить настройки индекса и настройки анализа. Предыдущие методы (getCommonSettingsBuilder, getEntitySettingsBuilder) объявлены устаревшими (deprecated). Они продолжают работать только до тех пор, пока не используются какие-либо новые методы API или не включен @ExtendedSearch. Как только новый API задействуется, устаревший API игнорируется.

Создание бина-конфигуратора

Создайте Spring-бин, реализующий:

  • OpenSearchIndexSettingsConfigurer – для OpenSearch.

  • ElasticsearchIndexSettingsConfigurer – для Elasticsearch.

Реализуйте метод configure(), который предоставляет объект ConfigurationContext.

Настройка параметров индекса

Параметры индекса настраиваются с помощью специальных билдеров настроек индекса:

  • getCommonIndexSettingsBuilder() – применяется ко всем индексам.

  • getEntityIndexSettingsBuilder(Class<?> entityClass) – применяется к индексу конкретной сущности. Настройки для конкретной сущности имеют более высокий приоритет и переопределяют общие настройки.

Настройка анализа

Параметры анализа настраиваются с помощью специальных билдеров анализа:

  • getCommonAnalysisBuilder() – применяется ко всем индексам.

  • getEntityAnalysisBuilder(Class<?> entityClass) – применяется к индексу конкретной сущности.

Используйте метод .analysis() билдера для определения:

  • Анализаторов – .analyzer()

  • Токенизаторов – .tokenizer()

  • Фильтров – .filter()

  • Символьных фильтров – .charFilter()

  • Нормализаторов – .normalizer()

Полный пример

Следующий пример демонстрирует пользовательский конфигуратор для OpenSearch. Он настраивает общие параметры индекса и анализа, а затем переопределяет их настройками для конкретной сущности Order.

import com.company.demo.entity.Order;
import io.jmix.searchopensearch.index.OpenSearchIndexSettingsConfigurationContext;
import io.jmix.searchopensearch.index.OpenSearchIndexSettingsConfigurer;
import org.opensearch.client.opensearch.indices.IndexSettings;
import org.springframework.stereotype.Component;

@Component
public class CustomOpenSearchIndexSettingsConfigurer implements OpenSearchIndexSettingsConfigurer {

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

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

Руководство по миграции API

Если вы обновляетесь с более ранней версии, замените устаревшие методы следующим образом:

Устаревший метод

Новый API

getCommonSettingsBuilder()

getCommonIndexSettingsBuilder()
getCommonAnalysisBuilder()

getEntitySettingsBuilder(Class)

getEntityIndexSettingsBuilder(Class)
getEntityAnalysisBuilder(Class)

Не смешивайте старый и новый API. Как только вы начнете использовать новые методы билдеров, устаревшие будут игнорироваться. Это особенно важно, если вы используете @ExtendedSearch, который требует новый API.