› › ›

Агрегация по диапазону дат

Агрегация по диапазону, предназначенная для значений дат. Основное отличие этой агрегации от обычной агрегации по диапазону range заключается в том, что значения from и to могут быть выражены в выражениях Date Math, а также можно указать формат даты, в котором будут возвращены поля ответа from и to. Обратите внимание, что эта агрегация включает значение from и исключает значение to для каждого диапазона.

Пример:

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "range": {
            "date_range": {
                "field": "date",
                "format": "MM-yyyy",
                "ranges": [
                    {
                        "to": "now-10M/M"
                    },
                    {
                        "from": "now-10M/M"
                    }
                ]
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      range: {
        date_range: {
          field: 'date',
          format: 'MM-yyyy',
          ranges: [
            {
              to: 'now-10M/M'
            },
            {
              from: 'now-10M/M'
            }
          ]
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    range: {
      date_range: {
        field: "date",
        format: "MM-yyyy",
        ranges: [
          {
            to: "now-10M/M",
          },
          {
            from: "now-10M/M",
          },
        ],
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "range": {
      "date_range": {
        "field": "date",
        "format": "MM-yyyy",
        "ranges": [
          { "to": "now-10M/M" },  
          { "from": "now-10M/M" } 
        ]
      }
    }
  }
}

	< сейчас минус 10 месяцев, округляя вниз до начала месяца.
	>= сейчас минус 10 месяцев, округляя вниз до начала месяца.

В приведенном выше примере мы создали две корзины диапазона. Первая «поместит» в себя все документы, датированные до 10 месяцев назад, а вторая — все документы, датированные с 10 месяцев назад.

Ответ:

{
  ...
  "aggregations": {
    "range": {
      "buckets": [
        {
          "to": 1.4436576E12,
          "to_as_string": "10-2015",
          "doc_count": 7,
          "key": "*-10-2015"
        },
        {
          "from": 1.4436576E12,
          "from_as_string": "10-2015",
          "doc_count": 0,
          "key": "10-2015-*"
        }
      ]
    }
  }
}

Если формат или значение даты неполны, агрегация по диапазону дат заполняет отсутствующие компоненты значениями по умолчанию. См. Отсутствующие компоненты даты.

Отсутствующие значения

Параметр missing определяет, как должны обрабатываться документы, у которых отсутствует значение. По умолчанию они игнорируются, но также можно обработать их так, как будто у них есть значение. Для этого нужно добавить набор сопоставлений «имя_поля : значение» для указания значений по умолчанию для каждого поля.

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "range": {
            "date_range": {
                "field": "date",
                "missing": "1976/11/30",
                "ranges": [
                    {
                        "key": "Older",
                        "to": "2016/02/01"
                    },
                    {
                        "key": "Newer",
                        "from": "2016/02/01",
                        "to": "now/d"
                    }
                ]
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      range: {
        date_range: {
          field: 'date',
          missing: '1976/11/30',
          ranges: [
            {
              key: 'Older',
              to: '2016/02/01'
            },
            {
              key: 'Newer',
              from: '2016/02/01',
              to: 'now/d'
            }
          ]
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    range: {
      date_range: {
        field: "date",
        missing: "1976/11/30",
        ranges: [
          {
            key: "Older",
            to: "2016/02/01",
          },
          {
            key: "Newer",
            from: "2016/02/01",
            to: "now/d",
          },
        ],
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
   "aggs": {
       "range": {
           "date_range": {
               "field": "date",
               "missing": "1976/11/30",
               "ranges": [
                  {
                    "key": "Older",
                    "to": "2016/02/01"
                  }, 
                  {
                    "key": "Newer",
                    "from": "2016/02/01",
                    "to" : "now/d"
                  }
              ]
          }
      }
   }
}

Документы без значения в поле date будут добавлены в корзину «Старее», как если бы у них было значение даты «1976-11-30».

Формат/Шаблон даты

Эта информация скопирована из DateTimeFormatter

Все латинские буквы в формате шаблона зарезервированы и определяются следующим образом:

Символ	Значение	Представление	Примеры
G	эра	текст	AD; Anno Domini; A
u	год	год	2004; 04
y	год эры	год	2004; 04
D	день года	число	189
M/L	месяц года	число/текст	7; 07; Jul; July; J
d	день месяца	число	10
Q/q	четверть года	число/текст	3; 03; Q3; 3-я четверть
Y	год по неделе	год	1996; 96
w	неделя года по неделе	число	27
W	неделя месяца	число	4
E	день недели	текст	Tue; Tuesday; T
e/c	локальный день недели	число/текст	2; 02; Tue; Tuesday; T
F	неделя месяца	число	3
a	AM/PM дня	текст	PM
h	час AM/PM (1-12)	число	12
K	час AM/PM (0-11)	число	0
k	час AM/PM (1-24)	число	0
H	час дня (0-23)	число	0
m	минута часа	число	30
s	секунда минуты	число	55
S	дробь секунды	дробь	978
A	миллисекунда дня	число	1234
n	наносекунда секунды	число	987654321
N	наносекунда дня	число	1234000000
V	Идентификатор часового пояса	идентификатор-часового-пояса	America/Los_Angeles; Z; -08:30
z	название часового пояса	название-часового-пояса	Pacific Standard Time; PST
O	локализованное смещение часового пояса	смещение-O	GMT+8; GMT+08:00; UTC-08:00;
X	смещение часового пояса Z для нуля	смещение-X	Z; -08; -0830; -08:30; -083015; -08:30:15;
x	смещение часового пояса	смещение-x	+0000; -08; -0830; -08:30; -083015; -08:30:15;
Z	смещение часового пояса	смещение-Z	+0000; -0800; -08:00;
p	заполнить следующее	модификатор заполнения	1
'	экранирование для текста	разделитель	''
одинарная кавычка	литерал	'	[
начало необязательной секции	]	конец необязательной секции	#
зарезервировано для будущего использования	{	зарезервировано для будущего использования	}

Количество символов шаблона определяет формат.

Текст: Стиль текста определяется на основе количества букв шаблона. Менее 4 букв шаблона будут использовать короткий формат. Ровно 4 буквы шаблона будут использовать полный формат. Ровно 5 букв шаблона будут использовать узкий формат. Буквы шаблона L, c и q определяют автономный формат стилей текста.
Число: Если количество букв равно одному, значение выводится с минимальным количеством цифр без заполнения. В противном случае количество цифр используется в качестве ширины поля вывода, а значение дополняется нулями по необходимости. Следующие буквы шаблона имеют ограничения на количество букв. Может быть указана только одна буква из c и F. Может быть указано до двух букв из d, H, h, K, k, m и s. Может быть указано до трёх букв из D.
Число/Текст: Если количество букв шаблона 3 или больше, применяются правила для Текста выше. В противном случае применяются правила для Числа выше.
Дробь: Выводит поле наносекунд как дробную часть секунды. Значение наносекунд содержит девять цифр, поэтому количество букв шаблона составляет от 1 до 9. Если оно меньше 9, то значение наносекунд усекается, и выводятся только самые значимые цифры.
Год: Количество букв определяет минимальную ширину поля, при которой используется заполнение. Если количество букв равно двум, используется сокращённая форма с двумя цифрами. При печати выводится две последние цифры. При разборе будет использоваться базовое значение 2000, что даёт год в диапазоне от 2000 до 2099 включительно. Если количество букв меньше четырёх (но не двух), знак выводится только для отрицательных лет, как указано в SignStyle.NORMAL. В противном случае знак выводится, если превышена ширина заполнения, как указано в SignStyle.EXCEEDS_PAD.
ZoneId: Выводит идентификатор часового пояса, например Europe/Paris. Если количество букв равно двум, выводится идентификатор часового пояса. Любое другое количество букв приводит к IllegalArgumentException.
Имена часовых поясов: Выводит отображаемое имя идентификатора часового пояса. Если количество букв равно одному, двум или трём, выводится короткое имя. Если количество букв равно четырём, выводится полное имя. Пять или более букв приводят к IllegalArgumentException.
Смещение X и x: Этот формат выводит смещение на основе количества букв шаблона. Одна буква выводит только час, например +01, если минута не равна нулю, то выводится также минута, например +0130. Две буквы выводят час и минуту без двоеточия, например +0130. Три буквы выводят час и минуту с двоеточием, например +01:30. Четыре буквы выводят час, минуту и необязательные секунды без двоеточия, например +013015. Пять букв выводит час, минуту и необязательные секунды с двоеточием, например +01:30:15. Шесть или более букв приводят к IllegalArgumentException. Буква шаблона X (заглавная) выведет Z, если смещение, которое нужно вывести, равно нулю, а буква шаблона x (строчная) выведет +00, +0000 или +00:00.
Смещение O: Этот формат выводит локальное смещение на основе количества букв шаблона. Одна буква выводит короткий формат локального смещения, который представляет собой текст локального смещения, например GMT, с часом без ведущего нуля, необязательными 2-значными минутами и секундами, если они не равны нулю, и двоеточием, например GMT+8. Четыре буквы выводит полный формат, который представляет собой текст локального смещения, например GMT, with 2-digit hour and minute field, optional second field if non-zero, and colon, for example `GMT+08:00. Любое другое количество букв приводит к IllegalArgumentException.
Смещение Z: Этот формат выводит смещение на основе количества букв шаблона. Одна, две или три буквы выводят час и минуту без двоеточия, например +0130. Вывод будет +0000, когда смещение равно нулю. Четыре буквы выводят полный формат локального смещения, эквивалентный четырём буквам смещения-O. Вывод будет соответствующим текстом локального смещения, если смещение равно нулю. Пять букв выводят час, минуту, необязательные секунды, если они не равны нулю, с двоеточием. Выводится Z, если смещение равно нулю. Шесть или более букв приводит к исключению IllegalArgumentException.
Необязательная секция: Маркеры необязательной секции работают точно так же, как вызов DateTimeFormatterBuilder.optionalStart() и DateTimeFormatterBuilder.optionalEnd().
Модификатор заполнения: Изменяет шаблон, который следует непосредственно за ним, чтобы он был заполнен пробелами. Ширина заполнения определяется количеством букв шаблона. Это то же самое, что вызов DateTimeFormatterBuilder.padNext(int).

Например, ppH выводит час дня, заполненный пробелами слева до ширины 2.

Любая нераспознанная буква является ошибкой. Любой небуквенный символ, кроме [, ], {, }, # и одиночной кавычки, будет выведен напрямую. Несмотря на это, рекомендуется использовать одинарные кавычки вокруг всех символов, которые вы хотите вывести напрямую, чтобы гарантировать, что будущие изменения не повредят ваше приложение.

Часовой пояс в агрегациях диапазонов дат

Даты могут быть преобразованы из другого часового пояса в UTC, указав параметр time_zone.

Часовые пояса могут быть указаны либо как смещение UTC в формате ISO 8601 (например, +01:00 или -08:00), либо как один из идентификаторов часовых поясов из базы данных TZ.

Параметр time_zone также применяется к округлениям в выражениях математики дат. Например, чтобы округлить до начала дня в часовом поясе CET, можно сделать следующее:

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "range": {
            "date_range": {
                "field": "date",
                "time_zone": "CET",
                "ranges": [
                    {
                        "to": "2016/02/01"
                    },
                    {
                        "from": "2016/02/01",
                        "to": "now/d"
                    },
                    {
                        "from": "now/d"
                    }
                ]
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      range: {
        date_range: {
          field: 'date',
          time_zone: 'CET',
          ranges: [
            {
              to: '2016/02/01'
            },
            {
              from: '2016/02/01',
              to: 'now/d'
            },
            {
              from: 'now/d'
            }
          ]
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    range: {
      date_range: {
        field: "date",
        time_zone: "CET",
        ranges: [
          {
            to: "2016/02/01",
          },
          {
            from: "2016/02/01",
            to: "now/d",
          },
          {
            from: "now/d",
          },
        ],
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
   "aggs": {
       "range": {
           "date_range": {
               "field": "date",
               "time_zone": "CET",
               "ranges": [
                  { "to": "2016/02/01" }, 
                  { "from": "2016/02/01", "to" : "now/d" }, 
                  { "from": "now/d" }
              ]
          }
      }
   }
}

	Эта дата будет преобразована в `2016-02-01T00:00:00.000+01:00`.
	`now/d` будет округлено до начала дня в часовом поясе CET.

Ответ с ключами

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

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "range": {
            "date_range": {
                "field": "date",
                "format": "MM-yyy",
                "ranges": [
                    {
                        "to": "now-10M/M"
                    },
                    {
                        "from": "now-10M/M"
                    }
                ],
                "keyed": True
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      range: {
        date_range: {
          field: 'date',
          format: 'MM-yyy',
          ranges: [
            {
              to: 'now-10M/M'
            },
            {
              from: 'now-10M/M'
            }
          ],
          keyed: true
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    range: {
      date_range: {
        field: "date",
        format: "MM-yyy",
        ranges: [
          {
            to: "now-10M/M",
          },
          {
            from: "now-10M/M",
          },
        ],
        keyed: true,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "range": {
      "date_range": {
        "field": "date",
        "format": "MM-yyy",
        "ranges": [
          { "to": "now-10M/M" },
          { "from": "now-10M/M" }
        ],
        "keyed": true
      }
    }
  }
}

Ответ:

{
  ...
  "aggregations": {
    "range": {
      "buckets": {
        "*-10-2015": {
          "to": 1.4436576E12,
          "to_as_string": "10-2015",
          "doc_count": 7
        },
        "10-2015-*": {
          "from": 1.4436576E12,
          "from_as_string": "10-2015",
          "doc_count": 0
        }
      }
    }
  }
}

Также можно настроить ключ для каждого диапазона:

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "range": {
            "date_range": {
                "field": "date",
                "format": "MM-yyy",
                "ranges": [
                    {
                        "from": "01-2015",
                        "to": "03-2015",
                        "key": "quarter_01"
                    },
                    {
                        "from": "03-2015",
                        "to": "06-2015",
                        "key": "quarter_02"
                    }
                ],
                "keyed": True
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      range: {
        date_range: {
          field: 'date',
          format: 'MM-yyy',
          ranges: [
            {
              from: '01-2015',
              to: '03-2015',
              key: 'quarter_01'
            },
            {
              from: '03-2015',
              to: '06-2015',
              key: 'quarter_02'
            }
          ],
          keyed: true
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    range: {
      date_range: {
        field: "date",
        format: "MM-yyy",
        ranges: [
          {
            from: "01-2015",
            to: "03-2015",
            key: "quarter_01",
          },
          {
            from: "03-2015",
            to: "06-2015",
            key: "quarter_02",
          },
        ],
        keyed: true,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "range": {
      "date_range": {
        "field": "date",
        "format": "MM-yyy",
        "ranges": [
          { "from": "01-2015", "to": "03-2015", "key": "quarter_01" },
          { "from": "03-2015", "to": "06-2015", "key": "quarter_02" }
        ],
        "keyed": true
      }
    }
  }
}

Ответ:

{
  ...
  "aggregations": {
    "range": {
      "buckets": {
        "quarter_01": {
          "from": 1.4200704E12,
          "from_as_string": "01-2015",
          "to": 1.425168E12,
          "to_as_string": "03-2015",
          "doc_count": 5
        },
        "quarter_02": {
          "from": 1.425168E12,
          "from_as_string": "03-2015",
          "to": 1.4331168E12,
          "to_as_string": "06-2015",
          "doc_count": 2
        }
      }
    }
  }
}

© 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/8.17/search-aggregations-bucket-daterange-aggregation.html