Hibernate Search 6：动态字段模板排序报‘未知字段’错误

从Hibernate 5迁移至搭配Elasticsearch后端的Hibernate Search 6，项目中有含动态数量字段的实体，按官方文档用动态字段模板处理，已通过属性绑定器成功将动态字段加入索引并可正常搜索，但排序时触发错误：

org.hibernate.search.util.common.SearchException: HSEARCH000610: Unknown field 'customFields.town_TextForSort.keyword'

相关代码与配置如下：

属性绑定器代码 #

public class AddressElementBinder implements PropertyBinder {

    @Override
    public void bind(PropertyBindingContext context) {
        context
            .dependencies()
            .useRootOnly();

        IndexSchemaElement schemaElement = context.indexSchemaElement();
        
        IndexSchemaObjectField customFields = schemaElement
                .objectField( "customFields", ObjectStructure.FLATTENED)
                .multiValued();

        customFields.fieldTemplate( 
                "fieldValueTemplate_TextDefault", 
                f -> f.asString()
                .analyzer("customAnalyzer")
                .searchable( Searchable.YES )
                .sortable(Sortable.NO)
        )
        .matchingPathGlob( "*_TextDefault" );

        customFields.fieldTemplate( 
                "fieldValueTemplate_TextForSort",
                f -> f.asString()
                .normalizer("customNormalizer")
                .sortable( Sortable.YES )
                .searchable( Searchable.NO )
        )
        .matchingPathGlob( "*_TextForSort" );

        context.bridge( Set.class, new AddressElementBridge(customFields.toReference()) ); 
    }
}

属性桥代码 #

public class AddressElementBridge implements PropertyBridge<Set> {

    private IndexObjectFieldReference customFieldFieldReference = null;
    
    public AddressElementBridge(IndexObjectFieldReference customFieldFieldReference) {
        this.customFieldFieldReference = customFieldFieldReference;
    }
    
    @Override
    public void write(DocumentElement target, Set bridgedElement, PropertyBridgeWriteContext context) {
        if(bridgedElement == null || bridgedElement.isEmpty() || this.customFieldFieldReference == null) {
            return;
        }
                                                
        DocumentElement customFieldElement = target.addObject( this.customFieldFieldReference ); 
                
        AbstractPostalAddress postalAddress = ContactAddressHelper.getMainPostalAddress(bridgedElement);        
        List<CustomField> fields = postalAddress.getFields(context);
        if(fields == null ||  fields.isEmpty()) {
            return;
        }
        
        for (FieldInfoFullTextIndex customField : fields) {
            
            String fieldName = customField.getFieldName();
            Object fieldValue = customField.getFieldValue();
            
            if(fieldValue != null) {
                                
                if(fieldValue instanceof String) {          
                    
                    fieldName = fieldName + "_TextDefault";
                    customFieldElement.addValue( fieldName, fieldValue );

                    fieldName = fieldName + "_TextForSort";
                    customFieldElement.addValue( fieldName, fieldValue );
                    
                }
                
            }
        }
        
    }
}

索引映射结构 #

{
    "mappings": {
        "_doc": {
            "_source": {
                "enabled": false
            },
            "properties": {
                "_entity_type": {
                    "type": "keyword",
                    "index": false
                },
                "customFields": {
                    "dynamic": "true",
                    "properties": {
                        "town_TextDefault": {
                            "type": "text",
                            "fields": {
                                "keyword": {
                                    "type": "keyword",
                                    "ignore_above": 256
                                }
                            }
                        },
                        "town_TextForSort": {
                            "type": "text",
                            "fields": {
                                "keyword": {
                                    "type": "keyword",
                                    "ignore_above": 256
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

分析器与归一化器配置 #

public class GlobalElasticsearchAnalysisConfigurer implements ElasticsearchAnalysisConfigurer {

    @Override
    public void configure(ElasticsearchAnalysisConfigurationContext context) {
    
        context.analyzer( "customAnalyzer" )
            .custom()
            .tokenizer( "standard" ) 
            .charFilters( "html_strip" ) 
            .tokenFilters( "lowercase", "asciifolding" );

        context.normalizer( "customNormalizer" )
            .custom() 
            .tokenFilters( "lowercase", "asciifolding" );

    }
}

使用customFields.town_TextForSort排序时，因字段类型为text无法正常排序；使用customFields.town_TextForSort.keyword排序则触发上述错误，但直接通过Elasticsearch接口使用该路径排序可正常返回结果。

疑问：这是Hibernate Search 6的bug吗？还是配置有误？原本以为使用ObjectStructure.FLATTENED时字段应均为keyword类型，而非text。或者是Elasticsearch自动生成了keyword子字段？如何强制字段为keyword类型？

问题根源 #

1. 字段模板配置偏差：为*_TextForSort模板配置.asString()+归一化器时，Hibernate Search默认会映射为Elasticsearch的text类型，并自动添加keyword子字段，但Hibernate Search的元数据中不包含这个自动生成的子字段，因此用customFields.town_TextForSort.keyword排序会提示字段不存在。
2. 对ObjectStructure.FLATTENED的误解：FLATTENED仅控制对象字段的存储结构（扁平化存储，而非嵌套对象），不会自动将所有字段设为keyword类型。
3. 属性桥字段命名错误：当前属性桥中，fieldName = fieldName + "_TextDefault"后又执行fieldName = fieldName + "_TextForSort"，最终生成的字段名是town_TextDefault_TextForSort，而非预期的town_TextForSort，导致模板匹配失败。

修复步骤 #

1. 调整字段模板，直接映射为keyword类型

修改AddressElementBinder中的模板配置，将.asString()替换为.asKeyword()，直接生成keyword类型字段，无需依赖自动生成的子字段：

customFields.fieldTemplate( 
        "fieldValueTemplate_TextForSort",
        f -> f.asKeyword()
        .normalizer("customNormalizer")
        .sortable( Sortable.YES )
        .searchable( Searchable.NO )
)
.matchingPathGlob( "*_TextForSort" );

2. 修正属性桥的字段命名逻辑

拆分搜索与排序字段的命名，避免拼接错误：

if(fieldValue instanceof String) {          
    // 处理搜索用字段
    String searchFieldName = fieldName + "_TextDefault";
    customFieldElement.addValue( searchFieldName, fieldValue );

    // 处理排序用字段
    String sortFieldName = fieldName + "_TextForSort";
    customFieldElement.addValue( sortFieldName, fieldValue );
}

3. 重建索引

修改配置后，删除现有索引并重新创建、索引数据，确保新的字段模板生效。

额外说明 #

• Hibernate Search的动态字段模板严格匹配路径通配符，必须保证桥中生成的字段名完全符合模板的matchingPathGlob规则。
• 若确实需要text类型+keyword子字段的结构，需在Hibernate Search的字段模板中通过.fields()方法显式定义子字段，这样Hibernate Search的元数据才会包含该子字段，排序时才能识别路径。

内容的提问来源于stack exchange，提问作者Stefan