mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-05 20:48:22 +00:00
412e163cf6
The joda to java.time migration requires users to upgrade their mappings. We allow them to still use 6.x created indices with joda patterns in 7 but ask them to upgrade their patterns in 7.x. This migration guide is to help them understand how they could be affected and what needs to be changed in their mappings. closes #51614 closes #51236
136 lines
5.5 KiB
Plaintext
136 lines
5.5 KiB
Plaintext
//NOTE: The notable-breaking-changes tagged regions are re-used in the
|
|
//Installation and Upgrade Guide
|
|
|
|
//tag::notable-breaking-changes[]
|
|
|
|
// end::notable-breaking-changes[]
|
|
|
|
[float]
|
|
[[breaking_70_java_time_changes]]
|
|
=== Replacing Joda-Time with java time
|
|
|
|
Since Java 8 there is a dedicated `java.time` package, which is superior to
|
|
the Joda-Time library, that has been used so far in Elasticsearch. One of
|
|
the biggest advantages is the ability to be able to store dates in a higher
|
|
resolution than milliseconds for greater precision. Also this will allow us
|
|
to remove the Joda-Time dependency in the future.
|
|
|
|
The mappings, aggregations and search code switched from Joda-Time to
|
|
java time.
|
|
|
|
[float]
|
|
==== Joda based date formatters are replaced with java ones
|
|
|
|
With the release of Elasticsearch 6.7 a backwards compatibility layer was
|
|
introduced, that checked if you are using a Joda-Time based formatter, that is
|
|
supported differently in java time. A log message was emitted, and you could
|
|
create the proper java time based formatter prefixed with an `8`.
|
|
|
|
With Elasticsearch 7.0 all formatters are now java based, which means you will
|
|
get exceptions when using deprecated formatters without checking the
|
|
deprecation log in 6.7. In the worst case you may even end up with different
|
|
dates.
|
|
|
|
An example deprecation message looks like this, that is returned, when you
|
|
try to use a date formatter that includes a lower case `Y`
|
|
|
|
[source,text]
|
|
----------
|
|
Use of 'Y' (year-of-era) will change to 'y' in the next major version of
|
|
Elasticsearch. Prefix your date format with '8' to use the new specifier.
|
|
----------
|
|
|
|
So, instead of using `YYYY.MM.dd` you should use `8yyyy.MM.dd`.
|
|
|
|
You can find more information about available formatting strings in the
|
|
https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter javadocs].
|
|
|
|
[float]
|
|
==== Date formats behavioural change
|
|
|
|
The `epoch_millis` and `epoch_second` formatters no longer support
|
|
scientific notation.
|
|
|
|
If you are using the century of era formatter in a date (`C`), this will no
|
|
longer be supported.
|
|
|
|
The year-of-era formatting character is a `Y` in Joda-Time, but a lowercase
|
|
`y` in java time.
|
|
|
|
The week-based-year formatting character is a lowercase `x` in Joda-Time,
|
|
but an upper-case `Y` in java time.
|
|
|
|
[float]
|
|
==== Using time zones in the Java client
|
|
|
|
Timezones have to be specified as java time based zone objects. This means,
|
|
instead of using a `org.joda.time.DateTimeZone` the use of
|
|
`java.time.ZoneId` is required.
|
|
|
|
Examples of possible uses are the `QueryStringQueryBuilder`, the
|
|
`RangeQueryBuilder` or the `DateHistogramAggregationBuilder`, each of them
|
|
allow for an optional timezone for that part of the search request.
|
|
|
|
[float]
|
|
==== Parsing aggregation buckets in the Java client
|
|
|
|
The date based aggregation buckets in responses used to be of
|
|
type `JodaTime`. Due to migrating to java-time, the buckets are now of
|
|
type `ZonedDateTime`. As the client is returning untyped objects here, you
|
|
may run into class cast exceptions only when running the code, but not at
|
|
compile time, ensure you have proper test coverage for this in your
|
|
own code.
|
|
|
|
[float]
|
|
[[parsing-gtm0-timezeone-jdk8-not-supported]]
|
|
==== Parsing `GMT0` timezone with JDK8 is not supported
|
|
|
|
When you are running Elasticsearch 7 with Java 8, you are not able to parse
|
|
the timezone `GMT0` properly anymore. The reason for this is a bug in the
|
|
JDK, which has not been fixed for JDK8. You can read more in the
|
|
https://bugs.openjdk.java.net/browse/JDK-8138664[official issue]
|
|
This bug is fixed in JDK9 and later versions.
|
|
|
|
[float]
|
|
==== Scripting with dates should use java time based methods
|
|
|
|
If dates are used in scripting, a backwards compatibility layer has been added
|
|
that emulates the Joda-Time methods, but logs a deprecation message as well
|
|
to use the java time methods.
|
|
|
|
The following methods will be removed in future versions of Elasticsearch
|
|
and should be replaced.
|
|
|
|
* `getDayOfWeek()` will be an enum instead of an int, if you need to use
|
|
an int, use `getDayOfWeekEnum().getValue()`
|
|
* `getMillis()` should be replaced with `toInstant().toEpochMilli()`
|
|
* `getCenturyOfEra()` should be replaced with `get(ChronoField.YEAR_OF_ERA) / 100`
|
|
* `getEra()` should be replaced with `get(ChronoField.ERA)`
|
|
* `getHourOfDay()` should be replaced with `getHour()`
|
|
* `getMillisOfDay()` should be replaced with `get(ChronoField.MILLI_OF_DAY)`
|
|
* `getMillisOfSecond()` should be replaced with `get(ChronoField.MILLI_OF_SECOND)`
|
|
* `getMinuteOfDay()` should be replaced with `get(ChronoField.MINUTE_OF_DAY)`
|
|
* `getMinuteOfHour()` should be replaced with `getMinute()`
|
|
* `getMonthOfYear()` should be replaced with `getMonthValue()`
|
|
* `getSecondOfDay()` should be replaced with `get(ChronoField.SECOND_OF_DAY)`
|
|
* `getSecondOfMinute()` should be replaced with `getSecond()`
|
|
* `getWeekOfWeekyear()` should be replaced with `get(WeekFields.ISO.weekOfWeekBasedYear())`
|
|
* `getWeekyear()` should be replaced with `get(WeekFields.ISO.weekBasedYear())`
|
|
* `getYearOfCentury()` should be replaced with `get(ChronoField.YEAR_OF_ERA) % 100`
|
|
* `getYearOfEra()` should be replaced with `get(ChronoField.YEAR_OF_ERA)`
|
|
* `toString(String)` should be replaced with a `DateTimeFormatter`
|
|
* `toString(String,Locale)` should be replaced with a `DateTimeFormatter`
|
|
|
|
[float]
|
|
==== Negative epoch timestamps are no longer supported
|
|
|
|
With the switch to java time, support for negative timestamps has been removed.
|
|
For dates before 1970, use a date format containing a year.
|
|
|
|
|
|
[float]
|
|
==== Migration guide
|
|
For a detailed migration guide, see <<migrate-to-java-time>>.
|
|
|
|
include::migrate_to_java_time.asciidoc[]
|