Java API changes

edit

Transport client has been moved

edit

The Java transport client has been moved to its own module which can be referenced using:

<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>transport</artifactId>
    <version>5.0.0</version>
</dependency>

The transport client is now created using the following snippet:

TransportClient client = new PreBuiltTransportClient(Settings.EMPTY)
        .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host1"), 9300))
        .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("host2"), 9300));

For more information please see the Java client documentation

Count api has been removed

edit

The deprecated count api has been removed from the Java api, use the search api instead and set size to 0.

The following call

client.prepareCount(indices).setQuery(query).get();

can be replaced with

client.prepareSearch(indices).setSource(new SearchSourceBuilder().size(0).query(query)).get();

Suggest api has been removed

edit

The suggest api has been removed from the Java api, use the suggest option in search api, it has been optimized for suggest-only request.

The following call

client.prepareSuggest(indices).addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s")).get();

can be replaced with

client.prepareSearch(indices).suggest(new SuggestBuilder().addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s"))).get();

Elasticsearch will no longer detect logging implementations

edit

Elasticsearch now logs using Log4j 2. Previously if Log4j wasn’t on the classpath it made some effort to degrade to SLF4J or Java logging. Now it will fail to work without the Log4j 2 API. The log4j-over-slf4j bridge ought to work when using the Java client. The log4j-1.2-api bridge is used for third-party dependencies that still use the Log4j 1 API. The Elasticsearch server now only supports Log4j 2 as configured by log4j2.properties and will fail if Log4j isn’t present.

Groovy dependencies

edit

In previous versions of Elasticsearch, the Groovy scripting capabilities depended on the org.codehaus.groovy:groovy-all artifact. In addition to pulling in the Groovy language, this pulls in a very large set of functionality, none of which is needed for scripting within Elasticsearch. Aside from the inherent difficulties in managing such a large set of dependencies, this also increases the surface area for security issues. This dependency has been reduced to the core Groovy language org.codehaus.groovy:groovy artifact.

DocumentAlreadyExistsException removed

edit

DocumentAlreadyExistsException is removed and a VersionConflictEngineException is thrown instead (with a better error description). This will influence code that use the IndexRequest.opType() or IndexRequest.create() to index a document only if it doesn’t already exist.

writeConsistencyLevel removed on write requests

edit

In previous versions of Elasticsearch, the various write requests had a setWriteConsistencyLevel method to set the shard consistency level for write operations. However, the semantics of write consistency were ambiguous as this is just a pre-operation check to ensure the specified number of shards were available before the operation commenced. The write consistency level did not guarantee that the data would be replicated to those number of copies by the time the operation finished. The setWriteConsistencyLevel method on these write requests has been changed to setWaitForActiveShards, which can take a numerical value up to the total number of shard copies or ActiveShardCount.ALL for all shard copies. The default is to just wait for the primary shard to be active before proceeding with the operation. See the section on wait for active shards for more details.

This change affects IndexRequest, IndexRequestBuilder, BulkRequest, BulkRequestBuilder, UpdateRequest, UpdateRequestBuilder, DeleteRequest, and DeleteRequestBuilder.

Changes to Query Builders

edit

BoostingQueryBuilder

edit

Removed setters for mandatory positive/negative query. Both arguments now have to be supplied at construction time already and have to be non-null.

SpanContainingQueryBuilder

edit

Removed setters for mandatory big/little inner span queries. Both arguments now have to be supplied at construction time already and have to be non-null. Updated static factory methods in QueryBuilders accordingly.

SpanOrQueryBuilder

edit

Making sure that query contains at least one clause by making initial clause mandatory in constructor. Renaming method to add clauses from clause(SpanQueryBuilder) to addClause(SpanQueryBuilder).

SpanNearQueryBuilder

edit

Removed setter for mandatory slop parameter, needs to be set in constructor now. Also making sure that query contains at least one clause by making initial clause mandatory in constructor. Updated the static factory methods in QueryBuilders accordingly. Renaming method to add clauses from clause(SpanQueryBuilder) to addClause(SpanQueryBuilder).

SpanNotQueryBuilder

edit

Removed setter for mandatory include/exclude span query clause, needs to be set in constructor now. Updated the static factory methods in QueryBuilders and tests accordingly.

SpanWithinQueryBuilder

edit

Removed setters for mandatory big/little inner span queries. Both arguments now have to be supplied at construction time already and have to be non-null. Updated static factory methods in QueryBuilders accordingly.

WrapperQueryBuilder

edit

Removed wrapperQueryBuilder(byte[] source, int offset, int length). Instead simply use wrapperQueryBuilder(byte[] source). Updated the static factory methods in QueryBuilders accordingly.

QueryStringQueryBuilder

edit

Removed ability to pass in boost value using field(String field) method in form e.g. field^2. Use the field(String, float) method instead.

Operator

edit

Removed the enums called Operator from MatchQueryBuilder, QueryStringQueryBuilder, SimpleQueryStringBuilder, and CommonTermsQueryBuilder in favour of using the enum defined in org.elasticsearch.index.query.Operator in an effort to consolidate the codebase and avoid duplication.

queryName and boost support

edit

Support for queryName and boost has been streamlined to all of the queries. That is a breaking change till queries get sent over the network as serialized json rather than in Streamable format. In fact whenever additional fields are added to the json representation of the query, older nodes might throw error when they find unknown fields.

InnerHitsBuilder

edit

InnerHitsBuilder now has a dedicated addParentChildInnerHits and addNestedInnerHits methods to differentiate between inner hits for nested vs. parent / child documents. This change makes the type / path parameter mandatory.

MatchQueryBuilder

edit

Moving MatchQueryBuilder.Type and MatchQueryBuilder.ZeroTermsQuery enum to MatchQuery.Type. Also reusing new Operator enum.

MoreLikeThisQueryBuilder

edit

Removed MoreLikeThisQueryBuilder.Item#id(String id), Item#doc(BytesReference doc), Item#doc(XContentBuilder doc). Use provided constructors instead.

Removed MoreLikeThisQueryBuilder#addLike in favor of texts and/or items being provided at construction time. Using arrays there instead of lists now.

Removed MoreLikeThisQueryBuilder#addUnlike in favor to using the unlike methods which take arrays as arguments now rather than the lists used before.

The deprecated docs(Item... docs), ignoreLike(Item... docs), ignoreLike(String... likeText), addItem(Item... likeItems) have been removed.

GeoDistanceQueryBuilder

edit

Removing individual setters for lon() and lat() values, both values should be set together using point(lon, lat).

GeoDistanceRangeQueryBuilder

edit

Removing setters for to(Object …​) and from(Object …​) in favour of the only two allowed input arguments (String, Number). Removing setter for center point (point(), geohash()) because parameter is mandatory and should already be set in constructor. Also removing setters for lt(), lte(), gt(), gte() since they can all be replaced by equivalent calls to to/from() and includeLower()/includeUpper().

GeoPolygonQueryBuilder

edit

Require shell of polygon already to be specified in constructor instead of adding it pointwise. This enables validation, but makes it necessary to remove the addPoint() methods.

MultiMatchQueryBuilder

edit

Moving MultiMatchQueryBuilder.ZeroTermsQuery enum to MatchQuery.ZeroTermsQuery. Also reusing new Operator enum.

Removed ability to pass in boost value using field(String field) method in form e.g. field^2. Use the field(String, float) method instead.

MissingQueryBuilder

edit

The MissingQueryBuilder which was deprecated in 2.2.0 is removed. As a replacement use ExistsQueryBuilder inside a mustNot() clause. So instead of using new MissingQueryBuilder(name) now use new BoolQueryBuilder().mustNot(new ExistsQueryBuilder(name)).

NotQueryBuilder

edit

The NotQueryBuilder which was deprecated in 2.1.0 is removed. As a replacement use BoolQueryBuilder with added mustNot() clause. So instead of using new NotQueryBuilder(filter) now use new BoolQueryBuilder().mustNot(filter).

TermsQueryBuilder

edit

Remove the setter for termsLookup(), making it only possible to either use a TermsLookup object or individual values at construction time. Also moving individual settings for the TermsLookup (lookupIndex, lookupType, lookupId, lookupPath) to the separate TermsLookup class, using constructor only and moving checks for validation there. Removed TermsLookupQueryBuilder in favour of TermsQueryBuilder.

FunctionScoreQueryBuilder

edit

add methods have been removed, all filters and functions must be provided as constructor arguments by creating an array of FunctionScoreQueryBuilder.FilterFunctionBuilder objects, containing one element for each filter/function pair.

scoreMode and boostMode can only be provided using corresponding enum members instead of string values: see FilterFunctionScoreQuery.ScoreMode and CombineFunction.

CombineFunction.MULT has been renamed to MULTIPLY.

IdsQueryBuilder

edit

For simplicity, only one way of adding the ids to the existing list (empty by default) is left: addIds(String...)

ShapeBuilders

edit

InternalLineStringBuilder is removed in favour of LineStringBuilder, InternalPolygonBuilder in favour of PolygonBuilder` and Ring has been replaced with LineStringBuilder. Also the abstract base classes BaseLineStringBuilder and BasePolygonBuilder haven been merged with their corresponding implementations.

RescoreBuilder

edit

RecoreBuilder.Rescorer was merged with RescoreBuilder, which now is an abstract superclass. QueryRescoreBuilder currently is its only implementation.

PhraseSuggestionBuilder

edit

The inner DirectCandidateGenerator class has been moved out to its own class called DirectCandidateGeneratorBuilder.

SortBuilders

edit

The sortMode setter in FieldSortBuilder, GeoDistanceSortBuilder and ScriptSortBuilder now accept a SortMode enum instead of a String constant. Also the getter returns the same enum type.

SuggestBuilder

edit

The setText method has been changed to setGlobalText to make the intent more clear, and a getGlobalText method has been added.

The addSuggestion method now required the user specified suggestion name, previously used in the ctor of each suggestion.

SuggestionBuilder

edit

The field setter has been deleted. Instead the field name needs to be specified as constructor argument.

SearchSourceBuilder

edit

All methods which take an XContentBuilder, BytesReference Map<String, Object> or bytes[] have been removed in favor of providing the relevant builder object for that feature (e.g. HighlightBuilder, AggregationBuilder, SuggestBuilder) . This means that all search requests can now be validated at call time which results in much clearer errors.

The defaultResourceWindowSize(int) method has been removed. The window size should be set explicitly on all RescoreBuilder objects.

SearchRequestBuilder

edit

All methods which take an XContentBuilder, BytesReference Map<String, Object> or bytes[] have been removed in favor of providing the relevant builder object for that feature (e.g. HighlightBuilder, AggregationBuilder, SuggestBuilder) . This means that all search requests can now be validated at call time which results in much clearer errors.

All highlighter methods have been removed in favor of a single highlighter(HighlightBuilder) method.

The setExtraSource(SearchSourceBuilder) method has been removed.

The setTemplateSource(String) and setTemplateSource(BytesReference) methods have been removed. Use setTemplate(Template) instead.

setRescorer(Rescorer) and setRescorer(Rescorer, int) have been removed in favor of setRescorer(RescoreBuilder) and setRescorer(RescoreBuilder, int)

SearchRequest

edit

All source methods have been removed in favor of a single source(SearchSourceBuilder) method. This means that all search requests can now be validated at call time which results in much clearer errors.

All extraSource methods have been removed.

All template methods have been removed in favor of a new Search Template API. A new SearchTemplateRequest now accepts a template and a SearchRequest and must be executed using the new SearchTemplateAction action.

SearchResponse

edit

Sort values for string fields are now return as java.lang.String objects rather than org.elasticsearch.common.text.Text.

AggregationBuilder

edit

All methods which take an XContentBuilder, BytesReference Map<String, Object> or bytes[] have been removed in favor of providing the relevant builder object (i.e. subAggregation(AggregationBuilder) or subAggregation(PipelineAggregationBuilder)). This means that all requests can now be validated at call time which results in much clearer errors.

ValidateQueryRequest

edit

source(QuerySourceBuilder), source(Map), source(XContentBuilder), source(String), source(byte[]), source(byte[], int, int), source(BytesReference) and source() have been removed in favor of using query(QueryBuilder) and query()

ValidateQueryRequestBuilder

edit

setSource() methods have been removed in favor of using setQuery(QueryBuilder)

ExplainRequest

edit

source(QuerySourceBuilder), source(Map), source(BytesReference) and source() have been removed in favor of using query(QueryBuilder) and query()

ExplainRequestBuilder

edit

The setQuery(BytesReference) method have been removed in favor of using setQuery(QueryBuilder)

ClusterStatsResponse

edit

Removed the getMemoryAvailable method from OsStats, which could be previously accessed calling clusterStatsResponse.getNodesStats().getOs().getMemoryAvailable(). It is now replaced with clusterStatsResponse.getNodesStats().getOs().getMem() which exposes getTotal(), getFree(), getUsed(), getFreePercent() and getUsedPercent().

setRefresh(boolean) has been removed

edit

setRefresh(boolean) has been removed in favor of setRefreshPolicy(RefreshPolicy) because there are now three options (NONE, IMMEDIATE, and WAIT_FOR). setRefresh(IMMEDIATE) has the same behavior as setRefresh(true) used to have. See setRefreshPolicy's javadoc for more.

Remove properties support

edit

Some Java APIs (e.g., IndicesAdminClient#setSettings) would support Java properties syntax (line-delimited key=value pairs). This support has been removed.

Render Search Template Java API has been removed

edit

The Render Search Template Java API including RenderSearchTemplateAction, RenderSearchTemplateRequest and RenderSearchTemplateResponse has been removed in favor of a new simulate option in the Search Template Java API. This Search Template API is now included in the lang-mustache module and the simulate flag must be set on the SearchTemplateRequest object.

AnalyzeRequest

edit

The tokenFilters(String...) and charFilters(String...) methods have been removed in favor of using addTokenFilter(String)/addTokenFilter(Map) and addCharFilter(String)/addCharFilter(Map) each filters

AnalyzeRequestBuilder

edit

The setTokenFilters(String...) and setCharFilters(String...) methods have been removed in favor of using addTokenFilter(String)/addTokenFilter(Map) and addCharFilter(String)/addCharFilter(Map) each filters

ClusterHealthRequest

edit

The waitForRelocatingShards(int) method has been removed in favor of waitForNoRelocatingShards(boolean) which instead uses a boolean flag to denote whether the cluster health operation should wait for there to be no relocating shards in the cluster before returning.

ClusterHealthRequestBuilder

edit

The setWaitForRelocatingShards(int) method has been removed in favor of setWaitForNoRelocatingShards(boolean) which instead uses a boolean flag to denote whether the cluster health operation should wait for there to be no relocating shards in the cluster before returning.

BlobContainer Interface for Snapshot/Restore

edit

Some methods have been removed from the BlobContainer interface for Snapshot/Restore repositories. In particular, the following three methods have been removed:

  1. deleteBlobs(Collection<String>) (use deleteBlob(String) instead)
  2. deleteBlobsByPrefix(String) (use deleteBlob(String) instead)
  3. writeBlob(String, BytesReference) (use writeBlob(String, InputStream, long) instead)

The deleteBlob methods that took multiple blobs as arguments were deleted because no atomic guarantees can be made about either deleting all blobs or deleting none of them, and exception handling in such a situation is ambiguous and best left to the caller. Hence, all delete blob calls use the singular deleteBlob(String) method.

The extra writeBlob method offered no real advantage to the interface and all calls to writeBlob(blobName, bytesRef) can be replaced with:

try (InputStream stream = bytesRef.streamInput()) {
    blobContainer.writeBlob(blobName, stream, bytesRef.length());
}

For any custom implementation of the BlobContainer interface, these three methods must be removed.

NodeBuilder removed

edit

NodeBuilder has been removed. While using Node directly within an application is not officially supported, it can still be constructed with the Node(Settings) constructor.