Elasticsearch Java Client 9.3.0

Discover what changed in the 9.3.0 version of the Java client.

Breaking changes

This version presents many updates to existing fields that were wrongly mapped, or incomplete. Here is the complete list of changes:

elasticsearch.indices.update_aliases.AddAction
- indexRouting: modified from String to List<String>, now required
- routing: modified from String to List<String>, now required
- searchRouting: modified from String to List<String>, now required
elasticsearch.indices.AddBlockRequest
- index: modified from String to List<String>
elasticsearch.indices.Alias
- indexRouting: modified from String to List<String>, now required
- routing: modified from String to List<String>, now required
- searchRouting: modified from String to List<String>, now required
elasticsearch.core.bulk.BulkOperationBase
- routing: modified from String to List<String>, now required
elasticsearch.core.BulkRequest
- routing: modified from String to List<String>, now required
elasticsearch.security.ClearCachedPrivilegesRequest
- application: modified from String to List<String>
elasticsearch.core.search.CompletionSuggestOption
- routing: modified from String to List<String>, now required
elasticsearch.core.CountRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.CreateRequest
- routing: modified from String to List<String>, now required
elasticsearch.indices.DataStreamsStatsRequest
- name: modified from String to List<String>, now required
elasticsearch.core.DeleteByQueryRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.DeleteRequest
- routing: modified from String to List<String>, now required
elasticsearch.snapshot.DeleteSnapshotRequest
- snapshot: modified from String to List<String>
elasticsearch.core.reindex.Destination
- routing: modified from String to List<String>, now required
elasticsearch.core.ExistsRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.ExistsSourceRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.ExplainRequest
- routing: modified from String to List<String>, now required
elasticsearch.graph.ExploreRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.FieldCapsRequest
- filters: modified from String to List<String>, now required
elasticsearch._types.query_dsl.FieldLookup
- routing: modified from String to List<String>, now required
elasticsearch.text_structure.FindFieldStructureRequest
- columnNames: modified from String to List<String>, now required
elasticsearch.text_structure.FindMessageStructureRequest
- columnNames: modified from String to List<String>, now required
elasticsearch.fleet.FleetSearchRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.GetRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.GetSourceRequest
- routing: modified from String to List<String>, now required
elasticsearch._types.InlineGet
- routing: modified from String to List<String>, now required
elasticsearch.core.IndexRequest
- routing: modified from String to List<String>, now required
elasticsearch._types.query_dsl.LikeDocument
- routing: modified from String to List<String>, now required
elasticsearch.core.MgetRequest
- routing: modified from String to List<String>, now required
elasticsearch._types.query_dsl.MoreLikeThisQuery
- routing: modified from String to List<String>, now required
elasticsearch.core.msearch.MultisearchHeader
- routing: modified from String to List<String>, now required
elasticsearch.core.MsearchRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.MtermvectorsRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.mget.MultiGetOperation
- routing: modified from String to List<String>, now required
elasticsearch.core.mtermvectors.MultiTermVectorsOperation
- routing: modified from String to List<String>, now required
elasticsearch.core.OpenPointInTimeRequest
- routing: modified from String to List<String>, now required
elasticsearch._types.query_dsl.PercolateQuery
- routing: modified from String to List<String>, now required
elasticsearch.indices.PutAliasRequest
- indexRouting: modified from String to List<String>, now required
- routing: modified from String to List<String>, now required
- searchRouting: modified from String to List<String>, now required
elasticsearch.indices.RemoveBlockRequest
- index: modified from String to List<String>
elasticsearch.core.SearchRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.SearchShardsRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.SearchTemplateRequest
- routing: modified from String to List<String>, now required
elasticsearch.async_search.SubmitRequest
- routing: modified from String to List<String>, now required
elasticsearch._types.query_dsl.TermsLookup
- routing: modified from String to List<String>, now required
elasticsearch.core.TermsEnumRequest
- index: modified from String to List<String>
elasticsearch.core.TermvectorsRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.UpdateByQueryRequest
- routing: modified from String to List<String>, now required
elasticsearch.core.UpdateRequest
- routing: modified from String to List<String>, now required

Elasticsearch 9.3 introduces the possibility to ingest vectors in a Base64 string format instead of float arrays, with a substantial performance gain. To make this feature easier to use, the Java Client 9.3 provides an utility class, AbstractBase64VectorDocument, that can be extended to facilitate conversion from float[] to Base64 string in the format accepted by the server.

Example usage:

		public final class CustomVectorDoc extends AbstractBase64VectorDocument {
    private String docid;
    private String title;
    private String text;
  ...
}

...

try (ElasticsearchClient client = ElasticsearchClient.of(e -> e
        .host("your-host")
        .apiKey("your-api-keys"))) {

    float[] embeddings = embeddingModel.getEmbeddings("content");

    // Converting vector from array of floats to base64 using utility class
    CustomVectorDoc customVectorDoc = new CustomVectorDoc("docID", "title", "content", embeddings);

    // Indexing the custom vector class normally
    client.index(i ->i
      .index(INDEX)
      .document(customVectorDoc)
    );
}
		
	

constructor, getters, setters

Note that while normally Elasticsearch automatically detects vector fields and creates a new index with the correct mapping and vector dimension, when ingesting vectors in Base64 format the index must be created first and all vector properties must be specified in the mapping. A complete example is available in the Java Client repository as a unit test.

Once an instance of a class has been created, all its fields are immutable, so it's not possible to apply modifications without having to create a new instance. A new method rebuild() has been added to all requests and subclasses that converts an object back to its builder, keeping the value of all fields as they were set.

Example usage:

		 SearchRequest searchRequest = SearchRequest.of(s -> s
        .size(20)
        .index("test")
        .query(q -> q.match(m -> m.field("field").query("value")))
);
SearchRequest.Builder builder = searchRequest.rebuild();

SearchRequest searchRequestRebuilt = builder
        // can update values here
        .build();
		
	

Correctly handling endpoints that return plain text responses, such as hot_threads and _cat.

Example usage:

		TextResponse resp = elasticsearchClient.cat().help();
System.out.println(resp.value());

Msearch and Search requests (and the template in ScriptSource) have similar bodies, but they are different classes (SearchRequest vs SearchRequestBody) due to how the client is generated from the common API specification. This version introduces overload methods in the builders of Msearch's RequestItem and ScriptSource so that they can also accept a SearchRequest instance instead of only the original SearchRequestBody.

Example usage:

		// Normal search request
SearchRequest searchRequest = SearchRequest.of(b -> b
                .size(10)
                .from(10)
                .query(q -> q
                        .matchAll(m -> m)
                )
        );

// Using it to build Msearch
MsearchRequest msearchRequestOverload = MsearchRequest.of(ms -> ms
        .searches(s -> s
                .header(h -> h.index("index"))
                .body(searchRequest)
        )
);

// Or script source
ScriptSource scriptSourceOverload = ScriptSource.of(s -> s
        .scriptTemplate(searchRequest)
);
		
	

Added an overload setter to Time so that it can be built using an integer and a TimeUnit, instead of just a plain string.

Example usage:

		// Old builder
OpenPointInTimeRequest opr = OpenPointInTimeRequest.of(o -> o
                .index("test")
                .keepAlive(k -> k
                        .time("5s")
                )
        );

// New builder
OpenPointInTimeRequest opr = OpenPointInTimeRequest.of(o -> o
        .index("test")
        .keepAlive(k -> k
                .time(5, TimeUnit.Seconds)
        )
);
		
	

plain string was the only way
TimeUnit provides all accepted units

Deprecations

Nothing was deprecated in this version of the client.

Elasticsearch Java Client 9.3.0

Breaking changes

Features and enhancements

Deprecations