› › ›

Руководство по миграции Java time

С версии 7.0 Elasticsearch переключился с joda time на java time для обработки, форматирования и вычислений дат. Это руководство поможет определить, затронут ли ваш кластер, и, если да, подготовиться к обновлению.

Вам не нужно преобразовывать форматы дат joda-time в java time для индексов, созданных в Elasticsearch 6.8, перед обновлением до 7.7 или более поздних версий. Однако схемы индексов, созданных в 7.7 и более поздних версиях, должны использовать форматы java time.

Чтобы убедиться, что новые индексы используют форматы java time, рекомендуется обновить все конвейеры индексирования и шаблоны индексов, созданные в 6.8, на java time перед обновлением. Смотрите:

Индексы, созданные в версиях 7.0-7.6, не могут использовать joda time. Эта проблема была исправлена в 7.7 с помощью #52555.

Преобразовать форматы дат

Для использования java time в 6.8 добавьте префикс 8 к формату даты. Например, вы можете изменить формат даты YYYY-MM-dd на 8yyyy-MM-dd, чтобы указать, что формат даты использует java time.

Elasticsearch обрабатывает форматы дат, начинающиеся с префикса 8, по-разному в зависимости от версии:

6.8: Форматы дат с префиксом 8 обрабатываются как форматы java time. Форматы дат без префикса 8 обрабатываются как форматы joda time. Рекомендуется преобразовать эти форматы joda time в java time до обновления до 7.x.

7.x и более поздние версии: Для индексов, созданных в 6.x, форматы дат без префикса 8 обрабатываются как форматы joda time. Для индексов, созданных в 7.x и более поздних версиях, все форматы дат обрабатываются как форматы java time, независимо от того, начинается ли он с префикса 8.

Затронутые функции

Переход на java time затрагивает только пользовательские форматы поля date и date_nanos.

Эти форматы часто используются в:

Если вы не используете пользовательские форматы дат, можно пропустить остальную часть этого руководства. Большинство пользовательских форматов дат совместимы. Однако некоторые требуют обновления.

Чтобы определить, затронут ли ваш формат даты, используйте API информации об устаревании или помощника по обновлению Kibana .

Несовместимые форматы дат

Пользовательские форматы дат, содержащие следующие литералы joda-time, следует преобразовать в эквиваленты java-time.

Y (Год эры)

Замените на y.

Пример: YYYY-MM-dd должно стать yyyy-MM-dd.

В java time, Y используется для года, основанного на неделях. Использование Y вместо y может привести к ошибкам смещения на единицу при вычислении года.

Для шаблона YYYY-ww и даты 2019-01-01T00:00:00.000Z будет 2019-01. Для шаблона YYYY-ww и даты 2018-12-31T00:00:00.000Z будет 2019-01 (противоинтуитивно), потому что в 2019 году более 4 дней в этой неделе.

y (Год)

Замените на u.

Пример: yyyy-MM-dd должно стать uuuu-MM-dd.

В java time, y используется для года эры. u может содержать неположительные значения, в то время как y не может. y также может быть связан с полем эры.

C (Столетие эры)

Столетие эры не поддерживается в java time. Нет замены. Вместо этого рекомендуется предварительно обработать входные данные.

x (Год недели)

Замените на Y.

В java time, x обозначает смещение часового пояса.

Неправильное преобразование x (Год недели) в Y может привести к потере данных.

Z (Смещение/идентификатор часового пояса)

Замените на несколько X.

Z имеет аналогичное значение в java time. Однако java time ожидает разного количества литералов для анализа различных форм.

Рекомендуется перейти к X, что даёт больший контроль над обработкой времени. Например, формат joda-time YYYY-MM-dd'T'hh:mm:ssZZ принимает следующие даты:

2010-01-01T01:02:03Z
2010-01-01T01:02:03+01
2010-01-01T01:02:03+01:02
2010-01-01T01:02:03+01:02:03

В java time вы не можете анализировать все эти даты с помощью одного формата. Вместо этого необходимо указать 3 отдельных формата:

2010-01-01T01:02:03Z
2010-01-01T01:02:03+01
both parsed with yyyy-MM-dd'T'hh:mm:ssX

2010-01-01T01:02:03+01:02
yyyy-MM-dd'T'hh:mm:ssXXX

2010-01-01T01:02:03+01:02:03
yyyy-MM-dd'T'hh:mm:ssXXXXX

Форматы должны быть разделены с помощью ||:

yyyy-MM-dd'T'hh:mm:ssX||yyyy-MM-dd'T'hh:mm:ssXXX||yyyy-MM-dd'T'hh:mm:ssXXXXX

То же самое относится, если вы ожидаете, что ваш шаблон будет встречаться без двоеточия (:): Например, формат YYYY-MM-dd'T'hh:mm:ssZ принимает следующие формы дат:

2010-01-01T01:02:03Z
2010-01-01T01:02:03+01
2010-01-01T01:02:03+0102
2010-01-01T01:02:03+010203

Чтобы принять все эти формы в java time, необходимо использовать разделитель ||:

yyyy-MM-dd'T'hh:mm:ssX||yyyy-MM-dd'T'hh:mm:ssXX||yyyy-MM-dd'T'hh:mm:ssXXXX

Тестирование с вашими данными

Настоятельно рекомендуется протестировать любые изменения в формате даты с реальными данными перед развертыванием в рабочей среде.

Обновление сопоставлений индексов

Для обновления форматов дат joda-time в сопоставлениях индексов необходимо создать новый индекс с обновлённым сопоставлением и переиндексировать данные в него. Однако вы можете обновить свои конвейеры или шаблоны.

Следующий my-index-000001 индекс содержит сопоставление для поля datetime, поля date с настраиваемым форматом даты joda-time.

GET my-index-000001/_mapping

{
  "my-index-000001" : {
    "mappings" : {
      "properties" : {
         "datetime": {
           "type": "date",
           "format": "yyyy/MM/dd HH:mm:ss||yyyy/MM/dd||epoch_millis"
         }
      }
    }
  }
}

Чтобы изменить формат даты для поля datetime, создайте отдельный индекс с обновлённым сопоставлением и форматом даты.

Например, следующий my-index-000002 индекс изменяет формат даты поля datetime на 8uuuu/MM/dd HH:mm:ss||uuuu/MM/dd||epoch_millis. Префикс 8 указывает, что этот формат даты использует java time.

PUT my-index-000002
{
  "mappings": {
    "properties": {
      "datetime": {
        "type": "date",
        "format": "8uuuu/MM/dd HH:mm:ss||uuuu/MM/dd||epoch_millis"
      }
    }
  }
}

Затем переиндексируйте данные из старого индекса в новый.

Следующий запрос API переиндексации переиндексирует данные из my-index-000001 в my-index-000002.

POST _reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-index-000002"
  }
}

Если вы используете псевдонимы индексов, обновите их для указания на новый индекс.

POST /_aliases
{
  "actions" : [
    { "remove" : { "index" : "my-index-000001", "alias" : "my-index" } },
    { "add" : { "index" : "my-index-000002", "alias" : "my-index" } }
  ]
}

Обновление конвейеров приема данных

Если ваши конвейеры приема данных содержат форматы дат joda-time, вы можете обновить их, используя API создания или обновления конвейера приема данных.

PUT _ingest/pipeline/my_pipeline
{
  "description": "Pipeline for routing data to specific index",
  "processors": [
    {
      "date": {
        "field": "createdTime",
        "formats": [
         "8uuuu-w"
        ]
      },
      "date_index_name": {
        "field": "@timestamp",
        "date_rounding": "d",
        "index_name_prefix": "x-",
        "index_name_format": "8uuuu-w"
      }
    }
  ]
}

Обновление шаблонов индексов

Если ваши шаблоны индексов содержат форматы дат joda-time, вы можете обновить их, используя API обновления шаблона индекса.

PUT _template/template_1
{
  "index_patterns": [
    "te*",
    "bar*"
  ],
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date",
        "format": "8EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}

Обновление внешних инструментов и шаблонов

Убедитесь, что вы также обновили все форматы дат в шаблонах или инструментах, расположенных вне Elasticsearch. Это могут быть такие инструменты, как Beats или Logstash.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/7.17/migrate-to-java-time.html