spring data elasticsearch 4.0.3 参考文档选翻

5.Elasticsearch Clients

This chapter illustrates configuration and usage of supported Elasticsearch client implementations.

本章说明了配置和使用支持Elasticsearch客户端实现。

Spring Data Elasticsearch operates upon an Elasticsearch client that is connected to a single Elasticsearch node or a cluster. Although the Elasticsearch Client can be used to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of Elasticsearch Operations and Elasticsearch Repositories.

Spring Data Elasticsearch运作在一个连接到单个Elasticsearch节点或一个集群的Elasticsearch client上。尽管可以使用Elasticsearch client可以与集群一起工作，但使用Spring Data Elasticsearch的应用程序通常使用更高层次抽象的Elasticsearch Operations 和Elasticsearch Repositories。

5.2. High Level REST Client

The Java High Level REST Client is the default client of Elasticsearch, it provides a straight forward replacement for the TransportClient as it accepts and returns the very same request/response objects and therefore depends on the Elasticsearch core project. Asynchronous calls are operated upon a client managed thread pool and require a callback to be notified when the request is done.

Java High Level REST Client 是Elasticsearch的默认客户端，它直接替代了TransportClient，因为它接受并返回完全相同的请求/响应对象，因此依赖于Elasticsearch核心项目。异步调用是在客户端托管线程池上操作的，请求完成时需要一个回调通知。

Example 53. High Level REST Client

@Configuration
public class RestClientConfig extends AbstractElasticsearchConfiguration {

    @Override
    @Bean
    public RestHighLevelClient elasticsearchClient() {

        final ClientConfiguration clientConfiguration = ClientConfiguration.builder()  
            .connectedTo("localhost:9200")
            .build();

        return RestClients.create(clientConfiguration).rest();                         
    }
}

// ...

  @Autowired
  RestHighLevelClient highLevelClient;

  RestClient lowLevelClient = highLevelClient.lowLevelClient();                        

// ...

IndexRequest request = new IndexRequest("spring-data", "elasticsearch", randomID())
  .source(singletonMap("feature", "high-level-rest-client"))
  .setRefreshPolicy(IMMEDIATE);

IndexResponse response = highLevelClient.index(request);

1. Use the builder to provide cluster addresses, set default HttpHeaders or enable SSL.
   使用bulider提供集群地址，设置默认HttpHeaders 或开启ssl

2. Create the RestHighLevelClient.
   创建RestHighLevelClient

3. It is also possible to obtain the lowLevelRest() client.
   也可以获得lowLevelRest() client

5.4. Client Configuration

Client behaviour can be changed via the ClientConfiguration that allows to set options for SSL, connect and socket timeouts, headers and other parameters.

客户端行为可以通过ClientConfiguration来更改，它允许设置SSL、连接和套接字超时、报头和其他参数。

Example 55. Client Configuration

HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.add("some-header", "on every request")                      

ClientConfiguration clientConfiguration = ClientConfiguration.builder()
  .connectedTo("localhost:9200", "localhost:9291")                      
  .useSsl()                                                             
  .withProxy("localhost:8888")                                          
  .withPathPrefix("ela")                                                
  .withConnectTimeout(Duration.ofSeconds(5))                            
  .withSocketTimeout(Duration.ofSeconds(3))                             
  .withDefaultHeaders(defaultHeaders)                                   
  .withBasicAuth(username, password)                                    
  .withHeaders(() -> {                                                  
    HttpHeaders headers = new HttpHeaders();
    headers.add("currentTime", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
    return headers;
  })
  . // ... other options
  .build();

1. Define default headers, if they need to be customized
2. Use the builder to provide cluster addresses, set default HttpHeaders or enable SSL.
3. Optionally enable SSL.
4. Optionally set a proxy.
5. Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
6. Set the connection timeout. Default is 10 sec.
7. Set the socket timeout. Default is 5 sec.
8. Optionally set headers.
9. Add basic authentication.
10. A Supplier<Header> function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header.

6.1.1. Mapping Annotation Overview

The MappingElasticsearchConverter uses metadata to drive the mapping of objects to documents. The metadata is taken from the entity’s properties which can be annotated.

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

The following annotations are available:

• @Document: Applied at the class level to indicate this class is a candidate for mapping to the database. The most important attributes are:

• 在类级别上应用，以指示该类是映射到数据库的候选类。最重要的属性是:
  – indexName: the name of the index to store this entity in
  – shards: the number of shards for the index.
  – replicas: the number of replicas for the index.
  – refreshIntervall: Refresh interval for the index. Used for index creation. Default value is “1s”.
  – indexStoreType: Index storage type for the index. Used for index creation. Default value is “fs”.
  – createIndex: Configuration whether to create an index on repository bootstrapping. Default value is true.
  – versionType: Configuration of version management. Default value is EXTERNAL.

• @Id: Applied at the field level to mark the field used for identity purpose.

• @Transient: By default all fields are mapped to the document when it is stored or retrieved, this annotation excludes the field.

• @PersistenceConstructor: Marks a given constructor - even a package protected one - to use when instantiating the object from the database. Constructor arguments are mapped by name to the key values in the retrieved Document.

• @Field: Applied at the field level and defines properties of the field, most of the attributes map to the respective 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 Elasticsearch Mapping Types
  – format and pattern definitions for the Date type. format must be defined for date types.
  – store: Flag wether the original field value should be store in Elasticsearch, default value is false.
  – analyzer, searchAnalyzer, normalizer for specifying custom custom analyzers and normalizer.

• @GeoPoint: marks a field as geo_point datatype. Can be omitted if the field is an instance of the GeoPoint class.

Properties that derive from TemporalAccessor must either have a @Field annotation of type FieldType.Date or a custom converter must be registerd for this type.
If you are using a custom date format, you need to use uuuu for the year instead of yyyy. This is due to a change in Elasticsearch 7.

6.1.2. Mapping Rules

类型提示
Mapping uses type hints embedded in the document sent to the server to allow generic type mapping. Those type hints are represented as _class attributes within the document and are written for each aggregate root.

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

public class Person {              

  @Id String id;
  String firstname;
  String lastname;
}

{
  "_class" : "com.example.Person", 
  "id" : "cb7bef",
  "firstname" : "Sarah",
  "lastname" : "Connor"
}

By default the domain types class name is used for the type hint.

Type hints can be configured to hold custom information. Use the @TypeAlias annotation to do so.

类型提示可以配置为保存自定义信息。使用@TypeAlias注释来做到这一点。

Example 57. Type Hints with Alias

@TypeAlias("human")                
public class Person {

  @Id String id;
  // ...
}

{
  "_class" : "human",              
  "id" : ...
}

7. Elasticsearch Operations

Spring Data Elasticsearch uses several interfaces to define the operations that can be called against an Elasticsearch index (for a description of the reactive interfaces see Reactive Elasticsearch Operations).

Spring Data Elasticsearch使用几个接口来定义可以针对Elasticsearch索引调用的操作(有关响应性接口的描述，请参阅响应性Elasticsearch操作)。

• IndexOperations defines actions on index level like creating or deleting an index.
• DocumentOperations defines actions to store, update and retrieve entities based on their id.
• SearchOperations define the actions to search for multiple entities using queries
• ElasticsearchOperations combines the DocumentOperations and SearchOperations interfaces.

7.2. ElasticsearchRestTemplate

The ElasticsearchRestTemplate is an implementation of the ElasticsearchOperations interface using the High Level REST Client.

Example 63. ElasticsearchRestTemplate configuration

@Configuration
public class RestClientConfig extends AbstractElasticsearchConfiguration {
  @Override
  public RestHighLevelClient elasticsearchClient() {       
    return RestClients.create(ClientConfiguration.localhost()).rest();
  }

  // no special bean creation needed                       
}

1、Setting up the High Level REST Client.
2、The base class AbstractElasticsearchConfiguration already provides the elasticsearchTemplate bean.

7.3. Usage examples

As both ElasticsearchTemplate and ElasticsearchRestTemplate implement the ElasticsearchOperations interface, the code to use them is not different. The example shows how to use an injected ElasticsearchOperations instance in a Spring REST controller. The decision, if this is using the TransportClient or the RestClient is made by providing the corresponding Bean with one of the configurations shown above.

由于elasticsearchtemplate和elasticsearchresttemplate都实现了elasticsearchoperations接口，所以使用它们的代码没有什么不同。该示例显示了如何在spring rest控制器中使用注入的elasticsearchoperations实例。如果使用transportclient或restclient，则通过为相应的bean提供上面所示的配置之一来做出决定。

Example 64. ElasticsearchOperations usage

@RestController
@RequestMapping("/")
public class TestController {

  private  ElasticsearchOperations elasticsearchOperations;

  public TestController(ElasticsearchOperations elasticsearchOperations) { 
    this.elasticsearchOperations = elasticsearchOperations;
  }

  @PostMapping("/person")
  public String save(@RequestBody Person person) {                         

    IndexQuery indexQuery = new IndexQueryBuilder()
      .withId(person.getId().toString())
      .withObject(person)
      .build();
    String documentId = elasticsearchOperations.index(indexQuery);
    return documentId;
  }

  @GetMapping("/person/{id}")
  public Person findById(@PathVariable("id")  Long id) {                   
    Person person = elasticsearchOperations
      .queryForObject(GetQuery.getById(id.toString()), Person.class);
    return person;
  }
}

1、Let Spring inject the provided ElasticsearchOperations bean in the constructor.
2、Store some entity in the Elasticsearch cluster.
3、Retrieve the entity with a query by id.

7.5. Search Result Types

When a document is retrieved with the methods of the DocumentOperations interface, just the found entity will be returned. When searching with the methods of the SearchOperations interface, additional information is available for each entity, for example the score or the sortValues of the found entity.

当使用documentoperations接口的方法检索文档时，只返回找到的实体。当使用searchoperations界面的方法进行搜索时，每个实体都有附加信息，例如找到的实体的得分或排序值。

In order to return this information, each entity is wrapped in a SearchHit object that contains this entity-specific additional information. These SearchHit objects themselves are returned within a SearchHits object which additionally contains informations about the whole search like the maxScore or requested aggregations. The following classes and interfaces are now available:

为了返回这个信息，每个实体都被包装在一个searchhit对象中，该对象包含这个特定于实体的附加信息。这些searchhit对象本身在searchhits对象中返回，该对象还包含关于整个搜索的信息，如maxscore或请求的聚合。现在可以使用以下类和接口:

SearchHit
Contains the following information:

• Id

• Score

• Sort Values

• Highlight fields

• The retrieved entity of type

SearchHits

Contains the following information:

• Number of total hits

• Total hits relation

• Maximum score

• A list of SearchHit objects

• Returned aggregations

SearchPage
Defines a Spring Data Page that contains a SearchHits<T> element and can be used for paging access using repository methods.

SearchScrollHits
Returned by the low level scroll API functions in ElasticsearchRestTemplate, it enriches a SearchHits<T> with the Elasticsearch scroll id.

SearchHitsIterator
An Iterator returned by the streaming functions of the SearchOperations interface.