从Hibernate Search 5迁移至6：如何配置Spatial Mode？

Hibernate Search 6重构了空间索引模块，彻底移除了5.x版本的@Spatial注解，原来的SpatialMode配置逻辑也做了调整，以下是具体的替代方案：

1. 配置空间哈希模式（对应原SpatialMode.HASH） #

如果需要实现旧版哈希模式的空间索引，要在定义地理字段时显式指定spatialHash索引策略，还可以通过levels参数控制哈希精度：

代码示例 #

场景1：实体字段为GeoPoint类型

import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.GenericField;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.IndexOptions;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.SpatialHash;

@Indexed
public class Venue {
    @GenericField(
        indexOptions = @IndexOptions(
            spatialHash = @SpatialHash(levels = 5) // levels控制哈希网格精度，值越高网格越细
        )
    )
    private GeoPoint location;

    // 其他字段、构造方法等
}

场景2：实体用单独的纬度、经度字段

可以通过GeoPointBridge将经纬度字段转为地理点，再配置哈希索引：

import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.GenericField;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.IndexOptions;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.SpatialHash;
import org.hibernate.search.mapper.pojo.bridge.builtin.spatial.GeoPointBridge;
import org.hibernate.search.mapper.pojo.bridge.mapping.annotation.Bridge;
import org.hibernate.search.mapper.pojo.bridge.mapping.annotation.Parameter;

@Indexed
public class Venue {
    private Double latitude;
    private Double longitude;

    @GenericField(
        bridge = @Bridge(
            type = GeoPointBridge.class,
            params = {
                @Parameter(name = "latitude", value = "latitude"),
                @Parameter(name = "longitude", value = "longitude")
            }
        ),
        indexOptions = @IndexOptions(
            spatialHash = @SpatialHash(levels = 5)
        )
    )
    public GeoPoint getLocation() {
        return GeoPoint.of(latitude, longitude);
    }

    // getter、setter等
}

• levels参数：对应旧版HASH模式的精度设置，数值越大，哈希网格划分越细，查询精度越高，但索引占用空间也会增加，可根据业务场景调整。

2. 关于hibernate.search.backend.sharding.strategy的澄清 #

这个配置项和空间模式没有任何关系，它是用来配置索引分片策略的——也就是把数据分散到多个索引分片里，优化大规模数据的查询性能，完全不涉及空间索引的处理逻辑，不用为了配置空间模式去修改它。

额外说明 #

Hibernate Search 6默认会为GeoPoint字段创建适合空间范围查询的索引结构（类似旧版的SpatialMode.GRID），如果没有特殊的性能或精度需求，直接使用默认配置就能满足大部分空间查询场景。

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