Агрегация по датам

При конфигурировании агрегации по датам интервал можно указать двумя способами: календарно-ориентированные временные интервалы и фиксированные временные интервалы.

Календарно-ориентированные интервалы учитывают, что переходы на летнее/зимнее время изменяют длину определённых дней, месяцы имеют разное количество дней, а високосные секунды могут быть добавлены к определённому году.

В отличие от этого, фиксированные интервалы всегда являются кратными единицам СИ и не изменяются в зависимости от календарного контекста.

Календарно-ориентированные интервалы настраиваются с помощью параметра calendar_interval. Вы можете указать календарные интервалы, используя название единицы, например, month, или количество единиц, например, 1M. Например, day и 1d эквивалентны. Не поддерживаются несколько значений, таких как 2d.

Принимаемые календарные интервалы:

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "month"
      }
    }
  }
}

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "2d"
      }
    }
  }
}

{
  "error" : {
    "root_cause" : [...],
    "type" : "x_content_parse_exception",
    "reason" : "[1:82] [date_histogram] failed to parse field [calendar_interval]",
    "caused_by" : {
      "type" : "illegal_argument_exception",
      "reason" : "The supplied interval [2d] could not be parsed as a calendar interval.",
      "stack_trace" : "java.lang.IllegalArgumentException: The supplied interval [2d] could not be parsed as a calendar interval."
    }
  }
}

Фиксированные интервалы настраиваются с помощью параметра fixed_interval.

В отличие от календарно-ориентированных интервалов, фиксированные интервалы — это фиксированное количество единиц СИ и никогда не изменяются, независимо от того, где они находятся в календаре. Одна секунда всегда состоит из 1000ms. Это позволяет указывать фиксированные интервалы в любом кратном поддерживаемых единиц.

Однако это означает, что фиксированные интервалы не могут выражать другие единицы, такие как месяцы, поскольку продолжительность месяца не является фиксированной величиной. Попытка указать календарный интервал, такой как месяц или квартал, приведёт к исключению.

Принимаемые единицы для фиксированных интервалов:

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "fixed_interval": "30d"
      }
    }
  }
}

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "fixed_interval": "2w"
      }
    }
  }
}

{
  "error" : {
    "root_cause" : [...],
    "type" : "x_content_parse_exception",
    "reason" : "[1:82] [date_histogram] failed to parse field [fixed_interval]",
    "caused_by" : {
      "type" : "illegal_argument_exception",
      "reason" : "failed to parse setting [date_histogram.fixedInterval] with value [2w] as a time value: unit is missing or unrecognized",
      "stack_trace" : "java.lang.IllegalArgumentException: failed to parse setting [date_histogram.fixedInterval] with value [2w] as a time value: unit is missing or unrecognized"
    }
  }
}

Во всех случаях, когда указанное конечное время не существует, фактическое конечное время — это ближайшее доступное время после указанного конечного.

Широко распространённые приложения также должны учитывать особенности, такие как страны, которые начинают и заканчивают летнее/зимнее время в 12:01 ночи, что приводит к одной минуте воскресенья, за которой следует ещё 59 минут субботы раз в год, и страны, которые решают переместиться через международную дату. Ситуации такого рода могут заставить нерегулярные смещения часовых поясов казаться простыми.

Как всегда, тщательное тестирование, особенно вблизи событий перехода на другое время, гарантирует, что ваш указанный временной интервал соответствует вашим намерениям.

Внутренне дата представляется 64-битным числом, представляющим отметку времени в миллисекундах с начала эпохи (01.01.1970 полночь по UTC). Эти отметки времени возвращаются в качестве имени корзины key. key_as_string — это та же отметка времени, преобразованная в отформатированную строку даты с использованием спецификации параметра format:

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1M",
        "format": "yyyy-MM-dd" 
      }
    }
  }
}

Ответ:

{
  ...
  "aggregations": {
    "sales_over_time": {
      "buckets": [
        {
          "key_as_string": "2015-01-01",
          "key": 1420070400000,
          "doc_count": 3
        },
        {
          "key_as_string": "2015-02-01",
          "key": 1422748800000,
          "doc_count": 2
        },
        {
          "key_as_string": "2015-03-01",
          "key": 1425168000000,
          "doc_count": 2
        }
      ]
    }
  }
}

Elasticsearch хранит даты и время в формате Coordinated Universal Time (UTC). По умолчанию, все операции группирования и округления также выполняются в UTC. Используйте параметр time_zone, чтобы указать, что группировка должна использовать другую временную зону.

Например, если интервал — это календарный день, а временная зона — America/New_York, то 2020-01-03T01:00:01Z будет: # Преобразован в 2020-01-02T18:00:01 # Округлён вниз до 2020-01-02T00:00:00 # Затем преобразован обратно в UTC для получения 2020-01-02T05:00:00:00Z # Наконец, когда корзина преобразуется в строковый ключ, она отображается в America/New_York, поэтому отобразится как "2020-01-02T00:00:00".

Это выглядит так:

bucket_key = localToUtc(Math.floor(utcToLocal(value) / interval) * interval))

Вы можете указать временные зоны как смещение UTC в формате ISO 8601 (например, +01:00 или -08:00), или как идентификатор временной зоны IANA, такой как America/Los_Angeles.

Рассмотрим следующий пример:

PUT my-index-000001/_doc/1?refresh
{
  "date": "2015-10-01T00:30:00Z"
}

PUT my-index-000001/_doc/2?refresh
{
  "date": "2015-10-01T01:30:00Z"
}

GET my-index-000001/_search?size=0
{
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field":     "date",
        "calendar_interval":  "day"
      }
    }
  }
}

Если вы не укажете временную зону, будет использоваться UTC. Это приведет к тому, что оба документа будут помещены в одну и ту же корзину дня, которая начинается в полночь UTC 1 октября 2015 года:

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-10-01T00:00:00.000Z",
          "key":           1443657600000,
          "doc_count":     2
        }
      ]
    }
  }
}

Если вы укажете временную зону time_zone как -01:00, полночь в этой временной зоне будет на один час раньше полуночи UTC:

GET my-index-000001/_search?size=0
{
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field":     "date",
        "calendar_interval":  "day",
        "time_zone": "-01:00"
      }
    }
  }
}

Теперь первый документ попадает в корзину на 30 сентября 2015 года, а второй документ — в корзину на 1 октября 2015 года:

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-09-30T00:00:00.000-01:00", 
          "key": 1443574800000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T00:00:00.000-01:00", 
          "key": 1443661200000,
          "doc_count": 1
        }
      ]
    }
  }
}

Используйте параметр offset, чтобы изменить начальное значение каждой корзины на указанное положительное (+) или отрицательное смещение (-) продолжительности, например, 1h для часа или 1d для дня. См. Единицы измерения времени для других возможных вариантов продолжительности времени.

Например, при использовании интервала day каждая корзина работает с полуночи до полуночи. Установка параметра offset на значение +6h изменяет каждую корзину так, чтобы она работала с 6 утра до 6 утра:

PUT my-index-000001/_doc/1?refresh
{
  "date": "2015-10-01T05:30:00Z"
}

PUT my-index-000001/_doc/2?refresh
{
  "date": "2015-10-01T06:30:00Z"
}

GET my-index-000001/_search?size=0
{
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field":     "date",
        "calendar_interval":  "day",
        "offset":    "+6h"
      }
    }
  }
}

Вместо одной корзины, начинающейся в полночь, вышеуказанный запрос группирует документы в корзины, начинающиеся в 6 утра:

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-09-30T06:00:00.000Z",
          "key": 1443592800000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T06:00:00.000Z",
          "key": 1443679200000,
          "doc_count": 1
        }
      ]
    }
  }
}

Установка флага keyed в значение true связывает с каждой корзиной уникальный строковый ключ и возвращает диапазоны как хеш, а не как массив:

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1M",
        "format": "yyyy-MM-dd",
        "keyed": true
      }
    }
  }
}

Ответ:

{
  ...
  "aggregations": {
    "sales_over_time": {
      "buckets": {
        "2015-01-01": {
          "key_as_string": "2015-01-01",
          "key": 1420070400000,
          "doc_count": 3
        },
        "2015-02-01": {
          "key_as_string": "2015-02-01",
          "key": 1422748800000,
          "doc_count": 2
        },
        "2015-03-01": {
          "key_as_string": "2015-03-01",
          "key": 1425168000000,
          "doc_count": 2
        }
      }
    }
  }
}

Если данные в ваших документах не точно соответствуют тому, что вы хотите агрегировать, используйте поле runtime. Например, если выручка от продвинутых продаж должна учитываться на следующий день после даты продажи:

POST /sales/_search?size=0
{
  "runtime_mappings": {
    "date.promoted_is_tomorrow": {
      "type": "date",
      "script": """
        long date = doc['date'].value.toInstant().toEpochMilli();
        if (doc['promoted'].value) {
          date += 86400;
        }
        emit(date);
      """
    }
  },
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "date.promoted_is_tomorrow",
        "calendar_interval": "1M"
      }
    }
  }
}

Вы можете контролировать порядок возвращаемых корзин с помощью настроек order и фильтровать возвращаемые корзины на основе настройки min_doc_count (по умолчанию возвращаются все корзины между первой корзиной, соответствующей документам, и последней). Эта гистограмма также поддерживает настройку extended_bounds, которая позволяет расширить границы гистограммы за пределы самих данных, и настройку hard_bounds, которая ограничивает гистограмму заданными границами. Дополнительную информацию см. в Extended Bounds и Hard Bounds.

POST /sales/_search?size=0
{
  "aggs": {
    "sale_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "year",
        "missing": "2000/01/01" 
      }
    }
  }
}

POST /sales/_search?size=0
{
  "runtime_mappings": {
    "date.day_of_week": {
      "type": "keyword",
      "script": "emit(doc['date'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
    }
  },
  "aggs": {
    "day_of_week": {
      "terms": { "field": "date.day_of_week" }
    }
  }
}

{
  ...
  "aggregations": {
    "day_of_week": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "Sunday",
          "doc_count": 4
        },
        {
          "key": "Thursday",
          "doc_count": 3
        }
      ]
    }
  }
}