WARNING: Version 5.6 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Java API changes
editJava API changes
editTransport client has been moved
editThe 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
editThe 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
editThe 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
editElasticsearch 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
editIn 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
editDocumentAlreadyExistsException
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
editIn 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
editBoostingQueryBuilder
editRemoved setters for mandatory positive/negative query. Both arguments now have to be supplied at construction time already and have to be non-null.
SpanContainingQueryBuilder
editRemoved 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
editMaking 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
editRemoved 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
editRemoved 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
editRemoved 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
editRemoved wrapperQueryBuilder(byte[] source, int offset, int length)
. Instead simply
use wrapperQueryBuilder(byte[] source)
. Updated the static factory methods in
QueryBuilders accordingly.
QueryStringQueryBuilder
editRemoved 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
editRemoved 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
editSupport 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
editInnerHitsBuilder 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
editMoving MatchQueryBuilder.Type and MatchQueryBuilder.ZeroTermsQuery enum to MatchQuery.Type. Also reusing new Operator enum.
MoreLikeThisQueryBuilder
editRemoved 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
editRemoving individual setters for lon() and lat() values, both values should be set together using point(lon, lat).
GeoDistanceRangeQueryBuilder
editRemoving 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
editRequire 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
editMoving 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
editThe 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
editThe 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
editRemove 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
editadd
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
editFor simplicity, only one way of adding the ids to the existing list (empty by default) is left: addIds(String...)
ShapeBuilders
editInternalLineStringBuilder
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
editRecoreBuilder.Rescorer
was merged with RescoreBuilder
, which now is an abstract superclass. QueryRescoreBuilder currently is its only implementation.
PhraseSuggestionBuilder
editThe inner DirectCandidateGenerator class has been moved out to its own class called DirectCandidateGeneratorBuilder.
SortBuilders
editThe 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
editThe 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
editThe field
setter has been deleted. Instead the field name needs to be specified as constructor argument.
SearchSourceBuilder
editAll 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
editAll 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
editAll 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
editSort values for string
fields are now return as java.lang.String
objects rather than org.elasticsearch.common.text.Text
.
AggregationBuilder
editAll 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
editsource(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
editsetSource()
methods have been removed in favor of using setQuery(QueryBuilder)
ExplainRequest
editsource(QuerySourceBuilder)
, source(Map)
, source(BytesReference)
and source()
have been removed in favor of using
query(QueryBuilder)
and query()
ExplainRequestBuilder
editThe setQuery(BytesReference)
method have been removed in favor of using setQuery(QueryBuilder)
ClusterStatsResponse
editRemoved 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
editsetRefresh(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
editSome 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
editThe 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
editThe 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
editThe 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
editThe 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
editThe 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
editSome methods have been removed from the BlobContainer
interface for Snapshot/Restore repositories. In particular,
the following three methods have been removed:
-
deleteBlobs(Collection<String>)
(usedeleteBlob(String)
instead) -
deleteBlobsByPrefix(String)
(usedeleteBlob(String)
instead) -
writeBlob(String, BytesReference)
(usewriteBlob(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
editNodeBuilder has been removed. While using Node directly within an application is not officially supported, it can still be constructed with the Node(Settings)
constructor.