› › ›

Агрегация гистограммы дат с автоматическим интервалом

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

Поле buckets является необязательным и по умолчанию устанавливается в 10 корзин, если не указано иное.

Запрос целевого значения в 10 корзин.

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "sales_over_time": {
            "auto_date_histogram": {
                "field": "date",
                "buckets": 10
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      sales_over_time: {
        auto_date_histogram: {
          field: 'date',
          buckets: 10
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    sales_over_time: {
      auto_date_histogram: {
        field: "date",
        buckets: 10,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "auto_date_histogram": {
        "field": "date",
        "buckets": 10
      }
    }
  }
}

Ключи

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

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

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "sales_over_time": {
            "auto_date_histogram": {
                "field": "date",
                "buckets": 5,
                "format": "yyyy-MM-dd"
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      sales_over_time: {
        auto_date_histogram: {
          field: 'date',
          buckets: 5,
          format: 'yyyy-MM-dd'
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    sales_over_time: {
      auto_date_histogram: {
        field: "date",
        buckets: 5,
        format: "yyyy-MM-dd",
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "sales_over_time": {
      "auto_date_histogram": {
        "field": "date",
        "buckets": 5,
        "format": "yyyy-MM-dd" 
      }
    }
  }
}

Поддерживает выразительные шаблоны форматирования дат Date Format/Pattern

Ответ:

{
  ...
  "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
        }
      ],
      "interval": "1M"
    }
  }
}

Интервалы

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

секунды	Кратные 1, 5, 10 и 30
минуты	Кратные 1, 5, 10 и 30
часы	Кратные 1, 3 и 12
дни	Кратные 1 и 7
месяцы	Кратные 1 и 3
годы	Кратные 1, 5, 10, 20, 50 и 100

В худшем случае, когда количество ежедневных корзин слишком велико для запрошенного количества корзин, количество возвращаемых корзин составит 1/7 часть от запрошенного количества корзин.

Временная зона

Даты и время хранятся в Elasticsearch в формате UTC. По умолчанию, все агрегации и округление также выполняются в UTC. Параметр time_zone может использоваться для указания того, что агрегация должна использовать другую временную зону.

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

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

resp = client.index(
    index="my-index-000001",
    id="1",
    refresh=True,
    document={
        "date": "2015-10-01T00:30:00Z"
    },
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="2",
    refresh=True,
    document={
        "date": "2015-10-01T01:30:00Z"
    },
)
print(resp1)

resp2 = client.index(
    index="my-index-000001",
    id="3",
    refresh=True,
    document={
        "date": "2015-10-01T02:30:00Z"
    },
)
print(resp2)

resp3 = client.search(
    index="my-index-000001",
    size="0",
    aggs={
        "by_day": {
            "auto_date_histogram": {
                "field": "date",
                "buckets": 3
            }
        }
    },
)
print(resp3)

response = client.index(
  index: 'my-index-000001',
  id: 1,
  refresh: true,
  body: {
    date: '2015-10-01T00:30:00Z'
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 2,
  refresh: true,
  body: {
    date: '2015-10-01T01:30:00Z'
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 3,
  refresh: true,
  body: {
    date: '2015-10-01T02:30:00Z'
  }
)
puts response

response = client.search(
  index: 'my-index-000001',
  size: 0,
  body: {
    aggregations: {
      by_day: {
        auto_date_histogram: {
          field: 'date',
          buckets: 3
        }
      }
    }
  }
)
puts response

const response = await client.index({
  index: "my-index-000001",
  id: 1,
  refresh: "true",
  document: {
    date: "2015-10-01T00:30:00Z",
  },
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: 2,
  refresh: "true",
  document: {
    date: "2015-10-01T01:30:00Z",
  },
});
console.log(response1);

const response2 = await client.index({
  index: "my-index-000001",
  id: 3,
  refresh: "true",
  document: {
    date: "2015-10-01T02:30:00Z",
  },
});
console.log(response2);

const response3 = await client.search({
  index: "my-index-000001",
  size: 0,
  aggs: {
    by_day: {
      auto_date_histogram: {
        field: "date",
        buckets: 3,
      },
    },
  },
});
console.log(response3);

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"
}

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

GET my-index-000001/_search?size=0
{
  "aggs": {
    "by_day": {
      "auto_date_histogram": {
        "field":     "date",
        "buckets" : 3
      }
    }
  }
}

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

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-10-01T00:00:00.000Z",
          "key": 1443657600000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T01:00:00.000Z",
          "key": 1443661200000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T02:00:00.000Z",
          "key": 1443664800000,
          "doc_count": 1
        }
      ],
      "interval": "1h"
    }
  }
}

Если указано смещение time_zone -01:00, то полночь начинается за час до полуночи UTC:

resp = client.search(
    index="my-index-000001",
    size="0",
    aggs={
        "by_day": {
            "auto_date_histogram": {
                "field": "date",
                "buckets": 3,
                "time_zone": "-01:00"
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'my-index-000001',
  size: 0,
  body: {
    aggregations: {
      by_day: {
        auto_date_histogram: {
          field: 'date',
          buckets: 3,
          time_zone: '-01:00'
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "my-index-000001",
  size: 0,
  aggs: {
    by_day: {
      auto_date_histogram: {
        field: "date",
        buckets: 3,
        time_zone: "-01:00",
      },
    },
  },
});
console.log(response);

GET my-index-000001/_search?size=0
{
  "aggs": {
    "by_day": {
      "auto_date_histogram": {
        "field":     "date",
        "buckets" : 3,
        "time_zone": "-01:00"
      }
    }
  }
}

Теперь по-прежнему возвращаются три корзины по 1 часу, но первая корзина начинается в 23:00 30 сентября 2015 года, поскольку это местное время для корзины в указанной временной зоне.

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-09-30T23:00:00.000-01:00", 
          "key": 1443657600000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T00:00:00.000-01:00",
          "key": 1443661200000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T01:00:00.000-01:00",
          "key": 1443664800000,
          "doc_count": 1
        }
      ],
      "interval": "1h"
    }
  }
}

Значение key_as_string представляет собой полночь каждого дня в указанной временной зоне.

При использовании временных зон, которые следуют изменению DST (переход на летнее время), корзины, близкие к моменту этих изменений, могут иметь немного разные размеры по сравнению с соседними корзинами. Например, рассмотрим начало DST в CET временной зоне: 27 марта 2016 года в 2:00, часы перевели вперёд на 1 час до 3:00 местного времени. Если результатом агрегации были ежедневные корзины, корзина, охватывающая этот день, будет содержать данные только за 23 часа вместо обычных 24 часов для других корзин. То же самое относится к более коротким интервалам, например, 12 часов. Здесь у нас будет корзина только на 11 часов утром 27 марта, когда происходит смена DST.

Минимальный параметр интервала

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

Принятые единицы для minimum_interval:

год
месяц
день
час
минута
секунда

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "sale_date": {
            "auto_date_histogram": {
                "field": "date",
                "buckets": 10,
                "minimum_interval": "minute"
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      sale_date: {
        auto_date_histogram: {
          field: 'date',
          buckets: 10,
          minimum_interval: 'minute'
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    sale_date: {
      auto_date_histogram: {
        field: "date",
        buckets: 10,
        minimum_interval: "minute",
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "sale_date": {
      "auto_date_histogram": {
        "field": "date",
        "buckets": 10,
        "minimum_interval": "minute"
      }
    }
  }
}

Пропущенное значение

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

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "sale_date": {
            "auto_date_histogram": {
                "field": "date",
                "buckets": 10,
                "missing": "2000/01/01"
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      sale_date: {
        auto_date_histogram: {
          field: 'date',
          buckets: 10,
          missing: '2000/01/01'
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    sale_date: {
      auto_date_histogram: {
        field: "date",
        buckets: 10,
        missing: "2000/01/01",
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "sale_date": {
      "auto_date_histogram": {
        "field": "date",
        "buckets": 10,
        "missing": "2000/01/01" 
      }
    }
  }
}

Документы без значения в поле publish_date попадут в ту же корзину, что и документы со значением 2000-01-01.

© 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-autodatehistogram-aggregation.html