バケット集約 - 日付範囲（Date range） - 《Elasticsearchガイドv8.15》日本語

日付範囲集計
欠落値
日付形式/パターン
日付範囲集計におけるタイムゾーン
キー付き応答

日付範囲集計

日付値専用の範囲集計です。この集計と通常の範囲集計との主な違いは、from および to の値が日付数学表現で表現できること、また from および to の応答フィールドが返される日付形式を指定できることです。この集計には、各範囲の from 値が含まれ、to 値は除外されます。

例:

Python

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)

Ruby

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

Js

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か月前の月の初めに切り捨てられた日付以上。

上記の例では、2つの範囲バケットを作成しました。最初のバケットは10か月前の日付より前の日付のすべてのドキュメントを「バケット」し、2番目のバケットは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 パラメータは、値が欠落しているドキュメントがどのように扱われるべきかを定義します。デフォルトでは無視されますが、値があるかのように扱うことも可能です。これは、フィールドごとにデフォルト値を指定するためのフィールド名: 値のマッピングを追加することで行われます。

Python

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)

Ruby

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

Js

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` フィールドに値がないドキュメントは「古い」バケットに追加されます。

日付形式/パターン

この情報は DateTimeFormatter からコピーされました。

すべてのASCII文字は形式パターン文字として予約されており、次のように定義されています:

シンボル	意味	表示	例
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; 3rd quarter
Y	週ベースの年	年	1996; 96
w	週ベースの年の週	数字	27
W	月の週	数字	4
E	週の日	テキスト	火; 火曜日; T
e/c	ローカライズされた週の日	数字/テキスト	2; 02; 火; 火曜日; T
F	月の週	数字	3
a	日の午前午後	テキスト	PM
h	午前午後の時計の時間 (1-12)	数字	12
K	午前午後の時間 (0-11)	数字	0
k	午前午後の時計の時間 (1-24)	数字	0
H	日の時間 (0-23)	数字	0
m	時間の分	数字	30
s	分の秒	数字	55
S	秒の分数	分数	978
A	日のミリ秒	数字	1234
n	秒のナノ	数字	987654321
N	日のナノ	数字	1234000000
V	タイムゾーンID	ゾーンID	America/Los_Angeles; Z; -08:30
z	タイムゾーン名	ゾーン名	太平洋標準時; 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 は、テキストスタイルの独立した形式を指定します。
数字
文字の数が1の場合、値は最小の桁数で出力され、パディングはありません。それ以外の場合、桁数は出力フィールドの幅として使用され、必要に応じて値はゼロパディングされます。次のパターン文字には、文字数に制約があります。c および F の文字は1文字のみ指定できます。d, H, h, K, k, m, および s の文字は最大2文字指定できます。D の文字は最大3文字指定できます。
数字/テキスト
パターン文字の数が3以上の場合は、上記のテキストルールを使用します。それ以外の場合は、上記の数字ルールを使用します。
分数
ナノ秒フィールドを秒の分数として出力します。ナノ秒値は9桁であり、したがってパターン文字の数は1から9です。9未満の場合、ナノ秒値は切り捨てられ、最も重要な桁のみが出力されます。
年
文字の数は、パディングが使用される最小フィールド幅を決定します。文字の数が2の場合、2桁の形式が使用されます。印刷時、これは右端の2桁を出力します。解析時、これは2000の基準値を使用して解析され、2000年から2099年の範囲内の年が得られます。文字の数が4未満（ただし2ではない）場合、SignStyle.NORMAL に従って負の年に対してのみ符号が出力されます。それ以外の場合、SignStyle.EXCEEDS_PAD に従ってパッド幅が超えた場合に符号が出力されます。
ZoneId
これは、Europe/Paris のようなタイムゾーンIDを出力します。文字の数が2の場合、タイムゾーンIDが出力されます。他の文字数は IllegalArgumentException をスローします。
ゾーン名
これは、タイムゾーンIDの表示名を出力します。文字の数が1、2、または3の場合、短い名前が出力されます。文字の数が4の場合、完全な名前が出力されます。5文字以上は IllegalArgumentException をスローします。
オフセット X および x
これは、パターン文字の数に基づいてオフセットをフォーマットします。1文字は、+01 のように時間のみを出力しますが、分がゼロでない場合は分も出力されます（+0130 のように）。2文字は、コロンなしで時間と分を出力します（+0130 のように）。3文字は、コロン付きで時間と分を出力します（+01:30 のように）。4文字は、コロンなしで時間と分とオプションの秒を出力します（+013015 のように）。5文字は、コロン付きで時間と分とオプションの秒を出力します（+01:30:15 のように）。6文字以上は IllegalArgumentException をスローします。パターン文字 X (大文字) は、出力されるオフセットがゼロである場合に Z を出力し、パターン文字 x (小文字) は +00, +0000, または +00:00 を出力します。
オフセット O
これは、パターン文字の数に基づいてローカライズされたオフセットをフォーマットします。1文字は、GMT のようにローカライズされたオフセットの短い形式を出力します。これは、先頭ゼロなしの時間、ゼロでない場合はオプションの2桁の分と秒、コロンを含みます（GMT+8 のように）。4文字は、GMT, with 2-digit hour and minute field, optional second field if non-zero, and colon, for example `GMT+08:00 のようにローカライズされたオフセットの完全な形式を出力します。他の文字数は IllegalArgumentException をスローします。
オフセット Z
これは、パターン文字の数に基づいてオフセットをフォーマットします。1、2、または3文字は、コロンなしで時間と分を出力します（+0130 のように）。オフセットがゼロの場合、出力は +0000 になります。4文字は、オフセット-O の4文字に相当するローカライズされたオフセットの完全な形式を出力します。オフセットがゼロの場合、出力は対応するローカライズされたオフセットテキストになります。5文字は、ゼロでない場合はオプションの秒を含む時間、分をコロン付きで出力します。オフセットがゼロの場合、Z を出力します。6文字以上は IllegalArgumentException をスローします。
オプションセクション
オプションセクションマーカーは、DateTimeFormatterBuilder.optionalStart() および DateTimeFormatterBuilder.optionalEnd() を呼び出すのとまったく同じように機能します。
パッド修飾子
直後のパターンをスペースでパディングされるように修正します。パッド幅はパターン文字の数によって決まります。これは、DateTimeFormatterBuilder.padNext(int) を呼び出すのと同じです。

例えば、ppH は、幅2にパディングされた日の時間を出力します。

認識されない文字はエラーです。[, ], {, }, # およびシングルクォート以外の非文字文字は直接出力されます。それにもかかわらず、将来の変更がアプリケーションを壊さないように、直接出力したいすべての文字の周りにシングルクォートを使用することをお勧めします。

日付範囲集計におけるタイムゾーン

日付は、time_zone パラメータを指定することによって、別のタイムゾーンからUTCに変換できます。

タイムゾーンは、ISO 8601 UTCオフセット（例: +01:00 または -08:00）として指定するか、TZデータベースのタイムゾーンIDのいずれかとして指定できます。

time_zone パラメータは、日付数学表現の丸めにも適用されます。たとえば、CETタイムゾーンで日の始まりに丸めるには、次のようにします:

Python

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)

Ruby

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

Js

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 に設定すると、各バケットに一意の文字列キーが関連付けられ、範囲が配列ではなくハッシュとして返されます:

Python

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)

Ruby

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

Js

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

各範囲のキーをカスタマイズすることも可能です:

Python

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)

Ruby

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

Js

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