Cwikius-Spring/spring-data-elasticsearch
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-data-elasticsearch.git synced 2025-05-29 16:22:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Polishing and documentation.

Browse Source
This commit is contained in:
Peter-Josef Meisch 2021-07-12 21:22:01 +02:00
parent 271e1eee0d
commit 7c340bc9a2
No known key found for this signature in database
GPG Key ID: DE108246970C7708
5 changed files with 81 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc
View File

@ -11,5 +11,4 @@ This section describes breaking changes from version 4.2.x to 4.3.x and how remo
=== Handling of field and sourceFilter properties of Query
Up to version 4.2 the `fields` property of a `Query` was interpreted and added to the include list of the `sourceFilter`. This was not correct, as these are different things for Elasticsearch. This has been corrected. As a consequence code might not work anymore that relies on using `fields` to specify which fields should be returned from the document's
`_source' and should be changed to use the `sourceFilter`.
Up to version 4.2 the `fields` property of a `Query` was interpreted and added to the include list of the `sourceFilter`. This was not correct, as these are different things for Elasticsearch. This has been corrected. As a consequence code might not work anymore that relies on using `fields` to specify which fields should be returned from the document's `_source' and should be changed to use the `sourceFilter`.

81
src/main/asciidoc/reference/elasticsearch-object-mapping.adoc
View File

@ -47,8 +47,9 @@ Constructor arguments are mapped by name to the key values in the retrieved Docu
* `@Field`: Applied at the field level and defines properties of the field, most of the attributes map to the respective https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html[Elasticsearch Mapping] definitions (the following list is not complete, check the annotation Javadoc for a complete reference):
** `name`: The name of the field as it will be represented in the Elasticsearch document, if not set, the Java field name is used.
** `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_.
See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html[Elasticsearch Mapping Types]. If the field type is not specified, it defaults to `FieldType.Auto`. This means, that no mapping entry is written for the property and that Elasticsearch will add a mapping entry dynamically when the first data for this property is stored
(check the Elasticsearch documentation for dynamic mapping rules).
See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html[Elasticsearch Mapping Types].
If the field type is not specified, it defaults to `FieldType.Auto`.
This means, that no mapping entry is written for the property and that Elasticsearch will add a mapping entry dynamically when the first data for this property is stored (check the Elasticsearch documentation for dynamic mapping rules).
** `format`: One or more built-in date formats, see the next section <<elasticsearch.mapping.meta-model.date-formats>>.
** `pattern`: One or more custom date formats, see the next section <<elasticsearch.mapping.meta-model.date-formats>>.
** `store`: Flag whether the original field value should be store in Elasticsearch, default value is _false_.
@ -61,21 +62,20 @@ The mapping metadata infrastructure is defined in a separate spring-data-commons
[[elasticsearch.mapping.meta-model.date-formats]]
==== Date format mapping
Properties that derive from `TemporalAccessor` or are of type `java.util.Date` must either have a `@Field` annotation
of type `FieldType.Date` or a custom converter must be registered for this type. This paragraph describes the use of
Properties that derive from `TemporalAccessor` or are of type `java.util.Date` must either have a `@Field` annotation of type `FieldType.Date` or a custom converter must be registered for this type.
This paragraph describes the use of
`FieldType.Date`.
There are two attributes of the `@Field` annotation that define which date format information is written to the
mapping (also see https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#built-in-date-formats[Elasticsearch Built In Formats] and https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#custom-date-formats[Elasticsearch Custom Date Formats])
There are two attributes of the `@Field` annotation that define which date format information is written to the mapping (also see https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#built-in-date-formats[Elasticsearch Built In Formats] and https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#custom-date-formats[Elasticsearch Custom Date Formats])
The `format` attributes is used to define at least one of the predefined formats. If it is not defined, then a
default value of __date_optional_time_ and _epoch_millis_ is used.
The `format` attributes is used to define at least one of the predefined formats.
If it is not defined, then a default value of __date_optional_time_ and _epoch_millis_ is used.
The `pattern` attribute can be used to add additional custom format strings. If you want to use only custom date formats, you must set the `format` property to empty `{}`.
The `pattern` attribute can be used to add additional custom format strings.
If you want to use only custom date formats, you must set the `format` property to empty `{}`.
The following table shows the different attributes and the mapping created from their values:
[cols=2*,options=header]
|===
| annotation
@ -101,12 +101,59 @@ The following table shows the different attributes and the mapping created from
NOTE: If you are using a custom date format, you need to use _uuuu_ for the year instead of _yyyy_.
This is due to a https://www.elastic.co/guide/en/elasticsearch/reference/current/migrate-to-java-time.html#java-time-migration-incompatible-date-formats[change in Elasticsearch 7].
==== Range types
When a field is annotated with a type of one of _Integer_Range, Float_Range, Long_Range, Double_Range, Date_Range,_ or _Ip_Range_ the field must be an instance of a class that will be mapped to an Elasticsearch range, for example:
====
[source,java]
----
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
}
----
====
As an alternative Spring Data Elasticsearch provides a `Range<T>` class so that the previous example can be written as:
====
[source,java]
----
class SomePersonData {
@Field(type = FieldType.Integer_Range)
private Range<Integer> validAge;
// getter and setter
}
----
====
Supported classes for the type `<T>` are `Integer`, `Long`, `Float`, `Double`, `Date` and classes that implement the
`TemporalAccessor` interface.
==== Mapped field names
Without further configuration, Spring Data Elasticsearch will use the property name of an object as field name in Elasticsearch. This can be changed for individual field by using the `@Field` annotation on that property.
Without further configuration, Spring Data Elasticsearch will use the property name of an object as field name in Elasticsearch.
This can be changed for individual field by using the `@Field` annotation on that property.
It is also possible to define a `FieldNamingStrategy` in the configuration of the client (<<elasticsearch.clients>>). If for example a `SnakeCaseFieldNamingStrategy` is configured, the property _sampleProperty_ of the object would be mapped to _sample_property_ in Elasticsearch. A `FieldNamingStrategy` applies to all entities; it can be overwritten by
setting a specific name with `@Field` on a property.
It is also possible to define a `FieldNamingStrategy` in the configuration of the client (<<elasticsearch.clients>>).
If for example a `SnakeCaseFieldNamingStrategy` is configured, the property _sampleProperty_ of the object would be mapped to _sample_property_ in Elasticsearch.
A `FieldNamingStrategy` applies to all entities; it can be overwritten by setting a specific name with `@Field` on a property.
[[elasticsearch.mapping.meta-model.rules]]
=== Mapping Rules
@ -171,11 +218,13 @@ NOTE: Type hints will not be written for nested Objects unless the properties ty
===== Disabling Type Hints
It may be necessary to disable writing of type hints when the index that should be used already exists without having the type hints defined in its mapping and with the mapping mode set to strict. In this case, writing the type hint will produce an error, as the field cannot be added automatically.
It may be necessary to disable writing of type hints when the index that should be used already exists without having the type hints defined in its mapping and with the mapping mode set to strict.
In this case, writing the type hint will produce an error, as the field cannot be added automatically.
Type hints can be disabled for the whole application by overriding the method `writeTypeHints()` in a configuration class derived from `AbstractElasticsearchConfiguration` (see <<elasticsearch.clients>>).
As an alternativ they can be disabled for a single index with the `@Document` annotation:
====
[source,java]
----
@ -183,7 +232,9 @@ As an alternativ they can be disabled for a single index with the `@Document` an
----
====
WARNING: We strongly advise against disabling Type Hints. Only do this if you are forced to. Disabling type hints can lead to documents not being retrieved correctly from Elasticsearch in case of polymorphic data or document retrieval may fail completely.
WARNING: We strongly advise against disabling Type Hints.
Only do this if you are forced to.
Disabling type hints can lead to documents not being retrieved correctly from Elasticsearch in case of polymorphic data or document retrieval may fail completely.
==== Geospatial Types

24
src/main/java/org/springframework/data/elasticsearch/core/Range.java
View File

@ -22,7 +22,7 @@ import org.springframework.util.ObjectUtils;
/**
* Simple value object to work with ranges and boundaries.
*
*
* @author Sascha Woo
* @since 4.3
*/
@ -33,12 +33,12 @@ public class Range<T> {
/**
* The lower bound of the range.
*/
private Bound<T> lowerBound;
private final Bound<T> lowerBound;
/**
* The upper bound of the range.
*/
private Bound<T> upperBound;
private final Bound<T> upperBound;
/**
* Creates a new {@link Range} with inclusive bounds for both values.
@ -89,12 +89,10 @@ public class Range<T> {
}
/**
* Creates a new {@link Range} with the given lower and upper bound. Prefer {@link #from(Bound)} for a more builder
* style API.
* Creates a new {@link Range} with the given lower and upper bound.
*
* @param lowerBound must not be {@literal null}.
* @param upperBound must not be {@literal null}.
* @see #from(Bound)
*/
public static <T> Range<T> of(Bound<T> lowerBound, Bound<T> upperBound) {
return new Range<>(lowerBound, upperBound);
@ -146,10 +144,7 @@ public class Range<T> {
return (Range<T>) UNBOUNDED;
}
private Range() {
}
private Range(Bound<T> lowerBound, Bound<T> upperBound) {
private Range(Bound<T> lowerBound, Bound<T> upperBound) {
Assert.notNull(lowerBound, "Lower bound must not be null!");
Assert.notNull(upperBound, "Upper bound must not be null!");
@ -164,7 +159,8 @@ public class Range<T> {
* @param value must not be {@literal null}.
* @return
*/
public boolean contains(T value) {
@SuppressWarnings("unchecked")
public boolean contains(T value) {
Assert.notNull(value, "Reference value must not be null!");
Assert.isInstanceOf(Comparable.class, value, "value must implements Comparable!");
@ -243,7 +239,8 @@ public class Range<T> {
@SuppressWarnings({ "rawtypes", "unchecked" }) //
private static final Bound<?> UNBOUNDED = new Bound(Optional.empty(), true);
private final Optional<T> value;
@SuppressWarnings("OptionalUsedAsFieldOrParameterType")
private final Optional<T> value;
private final boolean inclusive;
/**
@ -360,7 +357,8 @@ public class Range<T> {
return (Bound<T>) UNBOUNDED;
}
private Bound(Optional<T> value, boolean inclusive) {
@SuppressWarnings("OptionalUsedAsFieldOrParameterType")
private Bound(Optional<T> value, boolean inclusive) {
this.value = value;
this.inclusive = inclusive;
}

6
src/test/java/org/springframework/data/elasticsearch/core/RangeTests.java
View File

@ -18,7 +18,7 @@ package org.springframework.data.elasticsearch.core;
import static org.assertj.core.api.Assertions.*;
import java.time.LocalDate;
import java.util.Arrays;
import java.util.Collections;
import org.junit.jupiter.api.Test;
@ -166,9 +166,7 @@ public class RangeTests {
// given
// when
Throwable thrown = catchThrowable(() -> {
Range.just(Arrays.asList("test"));
});
Throwable thrown = catchThrowable(() -> Range.just(Collections.singletonList("test")));
// then
assertThat(thrown).isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("value must implements Comparable!");

3
src/test/java/org/springframework/data/elasticsearch/core/convert/MappingElasticsearchConverterUnitTests.java
View File

@ -2275,8 +2275,7 @@ public class MappingElasticsearchConverterUnitTests {
}
}
private static class ElectricCar extends Car {
}
private static class ElectricCar extends Car {}
private static class PersonWithCars {
@Id @Nullable String id;