部分配置释义

索引创建

搜索扩展组件检查 ES 索引当前的配置并与期望的索引配置进行比较。根据选择的索引结构管理策略（Index Schema Management Strategy）采取不同的操作：

  • create-only - 创建所有缺失的索引，保留使用不相关配置的已存在索引。

  • create-or-recreate - 创建所有缺失的索引，重新创建使用不相关配置的已存在索引（会丢失所有索引数据）。这是默认策略。

  • none - 忽略缺失的索引，保留使用不相关配置的已存在索引。如需手动操作索引可以使用该策略。

在 application.properties 文件添加下列应用程序属性可以配置策略：

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

应用程序启动时会自动进行索引结构同步。此外，也可以通过 EntityIndexing MBean 的 synchronizeXXX 操作手动进行。

EntityIndexing MBean 还包含 recreateIndex 操作。该操作直接删除并创建索引，并忽略当前的索引结构管理策略，即使目标索引有实际的配置。所有索引数据都会丢失。

索引命名

索引的命名格式：<prefix><entity_name>。

默认前缀为 search_index_。

如果多个项目使用同一个 ES 服务，需要确保索引名称的唯一性：所有项目都需要唯一的实体名称或者项目需要使用不同的前缀。

前缀可以在 application.properties 文件使用下列属性配置：

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

还可以在 @JmixEntitySearchIndex 注解的 indexName 属性中设置索引全名。

已有数据索引

有两种方式处理已有数据的索引：

  • Automatic（自动） - 这是索引结构同步的一部分，默认启用。将已经存在索引的实体实例都加入队列中（后台进程）。可以仅对特定实体使用自动索引。

  • Manual（手动） - 调用 EntityIndexing MBean 的 enqueueIndexAll 操作。

如需启用对特定实体的自动索引，添加下列应用程序属性：

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: edit filter 提供能在过滤器添加全文搜索条件的权限。

  • Search: view search results 提供访问搜索结果视图的权限。

索引配置和分析

扩展组件支持索引配置包括分析。

该配置依赖使用的搜索平台（OpenSearch 或 Elasticsearch），如果切换搜索引擎的话，需要重新创建配置。

  • 根据使用的引擎，创建一个实现 OpenSearchIndexSettingsConfigurer（或 ElasticsearchIndexSettingsConfigurer）接口的类。

  • 实现 configure(OpenSearchIndexSettingsConfigurationContext) 方法。

实现

配置可以通过配置的 builder（属于OpenSearch/Elasticsearch Java API 客户端）构建。

配置上下文提供两种类型的 builder：

  • 通用 - 可以配置全部索引的设置。可通过 context.getCommonSettingsBuilder() 获取。

  • 特定实体 - 可以配置某些实体索引的设置。 特定实体的索引配置优先级要高于通用配置。 可以通过 context.getEntitySettingsBuilder(Class) 获取。

使用 builder 中的方法配置对应的索引设置。

使用 .analysis() 方法可以开始使用流式接口，支持创建自定义的分析器，分词器等。

@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)
                                )
                        )
                );
    }
}