403 lines
17 KiB
Plaintext
403 lines
17 KiB
Plaintext
|
|
|
|
|
|
[[breaking_50_java_api_changes]]
|
|
=== Java API changes
|
|
|
|
==== Transport client has been moved
|
|
|
|
The Java transport client has been moved to its own module which can be referenced using:
|
|
|
|
[source,xml]
|
|
-----
|
|
<dependency>
|
|
<groupId>org.elasticsearch.client</groupId>
|
|
<artifactId>transport</artifactId>
|
|
<version>5.0.0-alpha5</version>
|
|
</dependency>
|
|
-----
|
|
|
|
The transport client is now created using the following snippet:
|
|
|
|
[source,java]
|
|
-----
|
|
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 {javaclient}java-api.html[Java client documentation]
|
|
|
|
==== Count api has been removed
|
|
|
|
The deprecated count api has been removed from the Java api, use the search api instead and set size to 0.
|
|
|
|
The following call
|
|
|
|
[source,java]
|
|
-----
|
|
client.prepareCount(indices).setQuery(query).get();
|
|
-----
|
|
|
|
can be replaced with
|
|
|
|
[source,java]
|
|
-----
|
|
client.prepareSearch(indices).setSource(new SearchSourceBuilder().size(0).query(query)).get();
|
|
-----
|
|
|
|
==== Suggest api has been removed
|
|
|
|
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
|
|
|
|
[source,java]
|
|
-----
|
|
client.prepareSuggest(indices).addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s")).get();
|
|
-----
|
|
|
|
can be replaced with
|
|
|
|
[source,java]
|
|
-----
|
|
client.prepareSearch(indices).suggest(new SuggestBuilder().addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s"))).get();
|
|
-----
|
|
|
|
==== Elasticsearch will no longer detect logging implementations
|
|
|
|
Elasticsearch now logs only to log4j 1.2. Previously if log4j wasn't on the
|
|
classpath it made some effort to degrade to slf4j or java.util.logging. Now it
|
|
will fail to work without the log4j 1.2 api. The log4j-over-slf4j bridge ought
|
|
to work when using the java client, as should log4j 2's log4j-1.2-api. The
|
|
Elasticsearch server now only supports log4j as configured by `logging.yml`
|
|
and will fail if log4j isn't present.
|
|
|
|
==== Groovy dependencies
|
|
|
|
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
|
|
|
|
`DocumentAlreadyExistsException` is removed and a `VersionConflictException` 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
|
|
|
|
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 <<index-wait-for-active-shards,wait for active shards>>
|
|
for more details.
|
|
|
|
This change affects `IndexRequest`, `IndexRequestBuilder`, `BulkRequest`,
|
|
`BulkRequestBuilder`, `UpdateRequest`, `UpdateRequestBuilder`, `DeleteRequest`,
|
|
and `DeleteRequestBuilder`.
|
|
|
|
==== Changes to Query Builders
|
|
|
|
===== BoostingQueryBuilder
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
Removed `wrapperQueryBuilder(byte[] source, int offset, int length)`. Instead simply
|
|
use `wrapperQueryBuilder(byte[] source)`. Updated the static factory methods in
|
|
QueryBuilders accordingly.
|
|
|
|
===== QueryStringQueryBuilder
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
Moving MatchQueryBuilder.Type and MatchQueryBuilder.ZeroTermsQuery enum to MatchQuery.Type.
|
|
Also reusing new Operator enum.
|
|
|
|
===== MoreLikeThisQueryBuilder
|
|
|
|
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
|
|
|
|
Removing individual setters for lon() and lat() values, both values should be set together
|
|
using point(lon, lat).
|
|
|
|
===== GeoDistanceRangeQueryBuilder
|
|
|
|
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 inludeLower()/includeUpper().
|
|
|
|
===== GeoPolygonQueryBuilder
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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 ExistsQueryBuilder(name)` now use
|
|
`new BoolQueryBuilder().mustNot(new ExistsQueryBuilder(name))`.
|
|
|
|
===== NotQueryBuilder
|
|
|
|
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
|
|
|
|
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
|
|
|
|
`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
|
|
|
|
For simplicity, only one way of adding the ids to the existing list (empty by default) is left: `addIds(String...)`
|
|
|
|
===== ShapeBuilders
|
|
|
|
`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
|
|
|
|
`RecoreBuilder.Rescorer` was merged with `RescoreBuilder`, which now is an abstract superclass. QueryRescoreBuilder currently is its only implementation.
|
|
|
|
===== PhraseSuggestionBuilder
|
|
|
|
The inner DirectCandidateGenerator class has been moved out to its own class called DirectCandidateGeneratorBuilder.
|
|
|
|
===== SortBuilders
|
|
|
|
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
|
|
|
|
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
|
|
|
|
The `field` setter has been deleted. Instead the field name needs to be specified as constructor argument.
|
|
|
|
==== SearchSourceBuilder
|
|
|
|
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
|
|
|
|
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 infavor of `setRescorer(RescoreBuilder)` and `setRescorer(RescoreBuilder, int)`
|
|
|
|
==== SearchRequest
|
|
|
|
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
|
|
|
|
Sort values for `string` fields are now return as `java.lang.String` objects rather than `org.elasticsearch.common.text.Text`.
|
|
|
|
==== AggregationBuilder
|
|
|
|
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
|
|
|
|
`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
|
|
|
|
`setSource()` methods have been removed in favor of using `setQuery(QueryBuilder)`
|
|
|
|
==== ExplainRequest
|
|
|
|
`source(QuerySourceBuilder)`, `source(Map)`, `source(BytesReference)` and `source()` have been removed in favor of using
|
|
`query(QueryBuilder)` and `query()`
|
|
|
|
==== ExplainRequestBuilder
|
|
|
|
The `setQuery(BytesReference)` method have been removed in favor of using `setQuery(QueryBuilder)`
|
|
|
|
==== ClusterStatsResponse
|
|
|
|
Removed the `getMemoryAvailable` method from `OsStats`, which could be previously accessed calling
|
|
`clusterStatsResponse.getNodesStats().getOs().getMemoryAvailable()`.
|
|
|
|
==== setRefresh(boolean) has been removed
|
|
|
|
`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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
==== BlobContainer Interface for Snapshot/Restore
|
|
|
|
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:
|
|
|
|
[source,java]
|
|
-----
|
|
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.
|
|
|