269 lines
11 KiB
Plaintext
269 lines
11 KiB
Plaintext
[[breaking-changes-3.0]]
|
|
== Breaking changes in 3.0
|
|
|
|
This section discusses the changes that you need to be aware of when migrating
|
|
your application to Elasticsearch 3.0.
|
|
|
|
=== Search changes
|
|
|
|
==== `search_type=count` removed
|
|
|
|
The `count` search type was deprecated since version 2.0.0 and is now removed.
|
|
In order to get the same benefits, you just need to set the value of the `size`
|
|
parameter to `0`.
|
|
|
|
For instance, the following request:
|
|
[source,sh]
|
|
---------------
|
|
GET /my_index/_search?search_type=count
|
|
{
|
|
"aggs": {
|
|
"my_terms": {
|
|
"terms": {
|
|
"field": "foo"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------
|
|
|
|
can be replaced with:
|
|
[source,sh]
|
|
---------------
|
|
GET /my_index/_search
|
|
{
|
|
"size": 0,
|
|
"aggs": {
|
|
"my_terms": {
|
|
"terms": {
|
|
"field": "foo"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------
|
|
|
|
==== `search_type=scan` removed
|
|
|
|
The `scan` search type was deprecated since version 2.1.0 and is now removed.
|
|
All benefits from this search type can now be achieved by doing a scroll
|
|
request that sorts documents in `_doc` order, for instance:
|
|
|
|
[source,sh]
|
|
---------------
|
|
GET /my_index/_search?scroll=2m
|
|
{
|
|
"sort": [
|
|
"_doc"
|
|
]
|
|
}
|
|
---------------
|
|
|
|
Scroll requests sorted by `_doc` have been optimized to more efficiently resume
|
|
from where the previous request stopped, so this will have the same performance
|
|
characteristics as the former `scan` search type.
|
|
|
|
=== Parent/Child changes
|
|
|
|
The `children` aggregation, parent child inner hits and `has_child` and `has_parent` queries will not work on indices
|
|
with `_parent` field mapping created before version `2.0.0`. The data of these indices need to be re-indexed into a new index.
|
|
|
|
The format of the join between parent and child documents have changed with the `2.0.0` release. The old
|
|
format can't read from version `3.0.0` and onwards. The new format allows for a much more efficient and
|
|
scalable join between parent and child documents and the join data structures are stored on on disk
|
|
data structures as opposed as before the join data structures were stored in the jvm heap space.
|
|
|
|
==== `score_type` has been removed
|
|
|
|
The `score_type` option has been removed from the `has_child` and `has_parent` queries in favour of the `score_mode` option
|
|
which does the exact same thing.
|
|
|
|
==== `sum` score mode removed
|
|
|
|
The `sum` score mode has been removed in favour of the `total` mode which doesn the same and is already available in
|
|
previous versions.
|
|
|
|
==== `max_children` option
|
|
|
|
When `max_children` was set to `0` on the `has_child` query then there was no upper limit on how many children documents
|
|
are allowed to match. This has changed and `0` now really means to zero child documents are allowed. If no upper limit
|
|
is needed then the `max_children` option shouldn't be defined at all on the `has_child` query.
|
|
|
|
=== Settings changes ===
|
|
|
|
==== Ping timeout settings
|
|
|
|
Previously, there were three settings for the ping timeout: `discovery.zen.initial_ping_timeout`,
|
|
`discovery.zen.ping.timeout` and `discovery.zen.ping_timeout`. The former two have been removed and
|
|
the only setting key for the ping timeout is now `discovery.zen.ping_timeout`. The default value for
|
|
ping timeouts remains at three seconds.
|
|
|
|
=== Plugins
|
|
|
|
Plugins implementing custom queries need to implement the `fromXContent(QueryParseContext)` method in their
|
|
`QueryParser` subclass rather than `parse`. This method will take care of parsing the query from `XContent` format
|
|
into an intermediate query representation that can be streamed between the nodes in binary format, effectively the
|
|
query object used in the java api. Also, the query parser needs to implement the `getBuilderPrototype` method that
|
|
returns a prototype of the `NamedWriteable` query, which allows to deserialize an incoming query by calling
|
|
`readFrom(StreamInput)` against it, which will create a new object, see usages of `Writeable`. The `QueryParser`
|
|
also needs to declare the generic type of the query that it supports and it's able to parse.
|
|
The query object can then transform itself into a lucene query through the new `toQuery(QueryShardContext)` method,
|
|
which returns a lucene query to be executed on the data node.
|
|
|
|
Similarly, plugins implementing custom score functions need to implement the `fromXContent(QueryParseContext)`
|
|
method in their `ScoreFunctionParser` subclass rather than `parse`. This method will take care of parsing
|
|
the function from `XContent` format into an intermediate function representation that can be streamed between
|
|
the nodes in binary format, effectively the function object used in the java api. Also, the query parser needs
|
|
to implement the `getBuilderPrototype` method that returns a prototype of the `NamedWriteable` function, which
|
|
allows to deserialize an incoming function by calling `readFrom(StreamInput)` against it, which will create a
|
|
new object, see usages of `Writeable`. The `ScoreFunctionParser` also needs to declare the generic type of the
|
|
function that it supports and it's able to parse. The function object can then transform itself into a lucene
|
|
function through the new `toFunction(QueryShardContext)` method, which returns a lucene function to be executed
|
|
on the data node.
|
|
|
|
=== Java-API
|
|
|
|
==== 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.
|
|
|
|
==== 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.
|
|
|
|
==== 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.
|
|
|
|
==== QueryFilterBuilder
|
|
|
|
Removed the setter `queryName(String queryName)` since this field is not supported
|
|
in this type of query. Use `FQueryFilterBuilder.queryName(String queryName)` instead
|
|
when in need to wrap a named query as a filter.
|
|
|
|
==== 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 beeing 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 equivallent
|
|
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 two individual setters for existence() and nullValue() were removed in favour of
|
|
optional constructor settings in order to better capture and validate their interdependent
|
|
settings at construction time.
|
|
|
|
==== 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...)`
|
|
|