当前位置：首页 > news >正文

Elasticsearch对象映射

news 来源：原创 2025/6/22 19:20:59

Spring Data Elasticsearch对象映射是将Java对象（域实体）映射到存储在Elasticsearchs中的JSON表示形式并返回的过程。内部用于此映射的类是MappingElasticsearchConverter。

元模型对象映射

基于元模型的方法使用域类型信息对Elasticsearch进行读写操作。这允许注册特定域类型映射的Converter实例。

1、映射注释概述

MappingElasticsearchConverter使用元数据来驱动对象到文档的映射。元数据取自可以注释的实体属性。

以下注释可用：

@Document: 在类级别应用，表示该类是映射到数据库的候选对象。最重要的属性是（查看API文档以获取完整的属性列表）:
- indexName: 用于存储此实体的索引的名称。这可以包含SpEL模板表达式，如 "log-#{T(java.time.LocalDate).now().toString()}"
- createIndex: 标记是否在存储库引导时创建索引。默认值为true。请参阅使用相应映射自动创建索引
@Id:在字段级别应用，以标记用于标识目的的字段。
@Transient, @ReadOnlyProperty, @WriteOnlyProperty:有关详细信息，请参阅以下“控制向Elasticsearch写入和从Elasticsearchs读取哪些属性”一节。
@PersistenceConstructor: 标记给定的构造函数（甚至是受包保护的构造函数），以便在从数据库实例化对象时使用。构造函数参数按名称映射到检索到的文档中的键值。
@Field:在字段级别应用并定义字段的属性，大多数属性映射到相应的Elasticsearch Mapping定义（以下列表不完整，请查看注释Javadoc以获取完整参考）：
- name: Elasticsearch文档中表示的字段名称，如果未设置，则使用Java字段名称。
- type: The field type, can be one of Text, Keyword, Long, Integer, Short, Byte, Double, Float, Half_Float, Scaled_Float, Date, Date_Nanos, Boolean, Binary, Integer_Range, Float_Range, Long_Range, Double_Range, Date_Range, Ip_Range, Object, Nested, Ip, TokenCount, Percolator, Flattened, Search_As_You_Type. 请参阅Elasticsearch映射类型。如果未指定字段类型，则默认为FieldType.auto。这意味着，没有为该属性编写映射条目，并且当存储了该属性的第一个数据时，Elasticsearch将动态添加一个映射条目（有关动态映射规则，请查看Elasticsearch文档）。
- format: 一个或多个内置日期格式，请参阅下一节“日期格式映射”。
- pattern: 一个或多个自定义日期格式，请参阅下一节“日期格式映射”。
- store: 标记原始字段值是否应存储在Elasticsearch中，默认值为false。
- analyzer, searchAnalyzer, normalizer 用于指定自定义分析器和归一化器。
@GeoPoint:将字段标记为geo_point数据类型。如果该字段是GeoPoint类的实例，则可以省略。
@ValueConverter ：定义一个用于转换给定属性的类。与注册的Spring Converter不同，它只转换带注释的属性，而不是给定类型的每个属性。

映射元数据基础设施是在一个独立的spring data commons项目中定义的，该项目与技术无关。

控制向Elasticsearch写入和从中读取哪些属性

本节详细介绍了定义属性值是写入Elasticsearch还是从Elasticsearchs读取的注释。

@Transient：用此注释注释的属性不会写入映射，它的值不会发送到Elasticsearch，当Elasticsearchs返回文档时，此属性不会在结果实体中设置。

@ReadOnlyProperty：带有此注释的属性不会将其值写入Elasticsearch，但在返回数据时，该属性将填充Elasticsearchs在文档中返回的值。一个用例是在索引映射中定义的运行时字段。

@WriteOnlyProperty：带有此注释的属性将其值存储在Elasticsearch中，但在读取文档时不会设置任何值。例如，这可以用于合成字段，这些字段应该进入Elasticsearch索引，但不会在其他地方使用。

日期格式映射

从TemporalAccessor派生或java.util.类型的属性。日期必须具有FieldType类型的@Field注释。必须为此类型注册日期或自定义转换器。本段介绍FieldType的使用。日期。

@Field注释有两个属性，用于定义将哪种日期格式信息写入映射（另请参阅Elasticsearch内置格式和Elasticsearch-自定义日期格式）

format属性用于定义至少一种预定义格式。如果未定义，则使用默认值_date_optional_time和epoch_millis。

pattern属性可用于添加其他自定义格式字符串。如果只想使用自定义日期格式，则必须将format属性设置为空｛｝。

下表显示了不同的属性及其值创建的映射：

annotation	format string in Elasticsearch mapping
@Field(type=FieldType.Date)	"date_optional_time\|\|epoch_millis",
@Field(type=FieldType.Date, format=DateFormat.basic_date)	"basic_date"
@Field(type=FieldType.Date, format={DateFormat.basic_date, DateFormat.basic_time})	"basic_date\|\|basic_time"
@Field(type=FieldType.Date, pattern="dd.MM.uuuu")	"date_optional_time\|\|epoch_millis\|\|dd.MM.uuuu",
@Field(type=FieldType.Date, format={}, pattern="dd.MM.uuuu")	"dd.MM.uuuu"

检查org.springframework.data.elasticsearch.annotation的代码。DateFormat枚举，用于预定义值及其模式的完整列表。

范围类型
当一个字段被标注为Integer_Range、Float_Range和Long_Range中的一种类型时，该字段必须是映射到Elasticsearch范围的类的实例，例如：

class SomePersonData {@Field(type = FieldType.Integer_Range)private ValidAge validAge;// getter and setter
}class ValidAge {@Field(name="gte")private Integer from;@Field(name="lte")private Integer to;// getter and setter
}

作为Spring Data的替代方案，Elasticsearch提供了一个Range<T>类，因此前面的示例可以写成：

class SomePersonData {@Field(type = FieldType.Integer_Range)private Range<Integer> validAge;// getter and setter
}

<T>类型支持的类是Integer、Long、Float、Double、Date和实现TemporalAccessor接口的类。

映射字段名称
在没有进一步配置的情况下，Spring Data Elasticsearch将使用对象的属性名作为Elasticsearch中的字段名。可以通过在该属性上使用@field注释来更改单个字段的设置。

也可以在客户端（Elasticsearch客户端）的配置中定义FieldNamingStrategy。例如，如果配置了SnakeCaseFieldNamingStrategy，则对象的属性sampleProperty将映射到Elasticsearch中的sample_property。FieldNaming战略适用于所有实体；可以通过在属性上使用@Field设置特定名称来覆盖它。

Non-field-backed属性

通常，实体中使用的属性是实体类的字段。在某些情况下，属性值是在实体中计算的，应该存储在Elasticsearch中。在这种情况下，getter方法（getProperty（））可以用@Field注释进行注释，此外，该方法必须用@AccessType（AccessType.Type.PROPERTY）进行注释。在这种情况下需要的第三个注释是@WriteOnlyProperty，因为这样的值只会写入Elasticsearch。完整示例：

@Field(type = Keyword)
@WriteOnlyProperty
@AccessType(AccessType.Type.PROPERTY)
public String getProperty() {return "some value that is calculated here";
}

其他特性注释

@IndexedIndexName

可以在实体的String属性上设置此注释。该属性不会写入映射，它不会存储在Elasticsearch中，并且不会从Elasticsearch文档中读取其值。在持久化实体后，例如通过调用ElasticsearchOperations.save（T实体），从该调用返回的实体将包含实体保存到该属性中的索引的名称。当bean动态设置索引名时，或者在写入写入别名时，这很有用。

将一些值放入这样的属性中不会设置实体存储到的索引！

2、映射规则

类型注解
映射使用嵌入在发送到服务器的文档中的类型提示来允许泛型类型映射。这些类型提示在文档中表示为_class属性，并为每个聚合根编写。

public class Person {              @Id String id;String firstname;String lastname;
}
{"_class" : "com.example.Person", "id" : "cb7bef","firstname" : "Sarah","lastname" : "Connor"
}

可以将类型提示配置为保存自定义信息。使用@TypeAlias注释来执行此操作。

@TypeAlias("human")                
public class Person {@Id String id;// ...
}
{"_class" : "human",              "id" : ...
}

禁用类型提示

如果应该使用的索引已经存在，但没有在其映射中定义类型提示，并且映射模式设置为strict，则可能需要禁用类型提示的写入。在这种情况下，写入类型提示将产生错误，因为无法自动添加字段。

通过重写从AbstractElasticsearchConfiguration派生的配置类中的方法writeTypeHints（），可以为整个应用程序禁用类型提示（请参阅Elasticsearch客户端）。

或者，可以使用@Document批注为单个索引禁用它们：

@Document(indexName = "index", writeTypeHint = WriteTypeHint.FALSE)

地理空间类型
Point和GeoPoint等地理空间类型转换为lat/lon对。

public class Address {String city, street;Point location;
}
{"city" : "Los Angeles","street" : "2800 East Observatory Road","location" : { "lat" : 34.118347, "lon" : -118.3026284 }
}

GeoJson类型
Spring Data Elasticsearch通过为不同的几何体提供接口GeoJson和实现来支持GeoJson类型。根据GeoJson规范，它们被映射到Elasticsearch文档。当写入索引映射时，实体的相应属性在索引映射中指定为geo_shape。（同时检查Elasticsearch文档）

public class Address {String city, street;GeoJsonPoint location;
}
{"city": "Los Angeles","street": "2800 East Observatory Road","location": {"type": "Point","coordinates": [-118.3026284, 34.118347]}
}

实现了以下GeoJson类型：

GeoJsonPoint
GeoJsonMultiPoint
GeoJsonLineString
GeoJsonMultiLineString
GeoJsonPolygon
GeoJsonMultiPolygon
GeoJsonGeometryCollection

Collections

对于集合内的值，当涉及类型提示和自定义转换时，应用与聚合根相同的映射规则。

public class Person {// ...List<Person> friends;}
{// ..."friends" : [ { "firstname" : "Kyle", "lastname" : "Reese" } ]
}

Maps

对于Maps内的值，当涉及类型提示和自定义转换时，应用与聚合根相同的映射规则。然而，Map键需要String才能由Elasticsearch处理。

public class Person {// ...Map<String, Address> knownLocations;}
{// ..."knownLocations" : {"arrivedAt" : {"city" : "Los Angeles","street" : "2800 East Observatory Road","location" : { "lat" : 34.118347, "lon" : -118.3026284 }}}
}

3、自定义转换

查看上一节中的配置ElasticsearchCustomConversions允许注册映射域和简单类型的特定规则。

@Configuration
public class Config extends ElasticsearchConfiguration  {@Overridepublic ClientConfiguration clientConfiguration() {return ClientConfiguration.builder() //.connectedTo("localhost:9200") //.build();}@Bean@Overridepublic ElasticsearchCustomConversions elasticsearchCustomConversions() {return new ElasticsearchCustomConversions(Arrays.asList(new AddressToMap(), new MapToAddress()));       }@WritingConverter                                                 static class AddressToMap implements Converter<Address, Map<String, Object>> {@Overridepublic Map<String, Object> convert(Address source) {LinkedHashMap<String, Object> target = new LinkedHashMap<>();target.put("ciudad", source.getCity());// ...return target;}}@ReadingConverter                                                 static class MapToAddress implements Converter<Map<String, Object>, Address> {@Overridepublic Address convert(Map<String, Object> source) {// ...return address;}}
}
{"ciudad" : "Los Angeles","calle" : "2800 East Observatory Road","localidad" : { "lat" : 34.118347, "lon" : -118.3026284 }
}

元模型对象映射

1、映射注释概述

2、映射规则

Maps

3、自定义转换

相关文章：