ヒストグラム（Histogram）

ヒストグラムフィールドタイプ

ヒストグラムを表す事前集計された数値データを格納するフィールドです。このデータは、2つのペア配列を使用して定義されます：

• ヒストグラムのバケットを表す values 配列の double 数値。これらの値は昇順で提供される必要があります。
• 各バケットに該当する値の数を表す対応する counts 配列の long 数値。これらの数値は正またはゼロでなければなりません。

values 配列の要素は count 配列の同じ位置の要素に対応するため、これら2つの配列は同じ長さでなければなりません。

• histogram フィールドは、ドキュメントごとに単一の values および count 配列のペアのみを格納できます。ネストされた配列はサポートされていません。
• histogram フィールドはソートをサポートしていません。

使用例

histogram フィールドは主に集計での使用を目的としています。集計に対してよりアクセスしやすくするために、histogram フィールドデータはバイナリ doc values として保存され、インデックスされません。そのサイズは最大で 13 * numValues バイトで、numValues は提供された配列の長さです。

データがインデックスされていないため、histogram フィールドは次の集計およびクエリにのみ使用できます：

• min 集計
• max 集計
• sum 集計
• value_count 集計
• avg 集計
• percentiles 集計
• percentile ranks 集計
• boxplot 集計
• histogram 集計
• range 集計
• exists クエリ

ヒストグラムの構築

集計の一部としてヒストグラムを使用する場合、結果の精度はヒストグラムの構築方法に依存します。ヒストグラムを構築するために使用されるパーセンタイル集計モードを考慮することが重要です。いくつかの可能性には次のものが含まれます：

• T-Digest モードでは、values 配列は平均セントロイド位置を表し、counts 配列は各セントロイドに帰属する値の数を表します。アルゴリズムがすでにパーセンタイルを近似し始めている場合、この不正確さはヒストグラムに引き継がれます。
• High Dynamic Range (HDR) ヒストグラムモードでは、values 配列は各バケット区間の固定上限を表し、counts 配列は各区間に帰属する値の数を表します。この実装は、固定の最悪ケースのパーセンテージ誤差（指定された有効桁数として）を維持します。したがって、ヒストグラムを生成する際に使用される値は、集計時に達成できる最大の精度となります。

ヒストグラムフィールドは「アルゴリズムに依存しない」とされ、T-Digest または HDRHistogram のいずれかに特有のデータを保存しません。これは、フィールドが技術的にはどちらのアルゴリズムでも集計できることを意味しますが、実際にはユーザーは1つのアルゴリズムを選択し、その方法でデータをインデックスする必要があります（例：T-Digest のセントロイドまたは HDRHistogram の区間）最良の精度を確保するために。

合成 _source

合成 _source は、一般的に TSDB インデックス（index.mode が time_series に設定されているインデックス）でのみ利用可能です。他のインデックスでは、合成 _source は技術プレビュー中です。技術プレビュー中の機能は、将来のリリースで変更または削除される可能性があります。Elastic は問題を修正するために作業しますが、技術プレビュー中の機能は公式 GA 機能のサポート SLA の対象ではありません。

histogram フィールドは、デフォルト構成で 合成 _source をサポートします。合成 _source は、copy_to と一緒に使用することはできません。

スペースを節約するために、ゼロカウントバケットはヒストグラムの doc values に保存されません。その結果、合成ソースが有効なインデックスでヒストグラムフィールドをインデックスする際に、ゼロカウントバケットを含むヒストグラムをインデックスすると、ヒストグラムを取得する際にバケットが欠落することになります。

例

次の インデックス作成 API リクエストは、2つのフィールドマッピングを持つ新しいインデックスを作成します：

• my_histogram、パーセンタイルデータを格納するために使用される histogram フィールド
• my_text、ヒストグラムのタイトルを格納するために使用される keyword フィールド

Python

resp = client.indices.create(
   index="my-index-000001",
   mappings={
   "properties": {
   "my_histogram": {
   "type": "histogram"
   },
   "my_text": {
   "type": "keyword"
   }
   }
   },
)
print(resp)

Ruby

response = client.indices.create(
  index: 'my-index-000001',
  body: {
   mappings: {
   properties: {
   my_histogram: {
   type: 'histogram'
   },
   my_text: {
   type: 'keyword'
   }
   }
   }
  }
)
puts response

Js

const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
   properties: {
   my_histogram: {
   type: "histogram",
   },
   my_text: {
   type: "keyword",
   },
   },
  },
});
console.log(response);

コンソール

PUT my-index-000001
{
  "mappings" : {
   "properties" : {
   "my_histogram" : {
   "type" : "histogram"
   },
   "my_text" : {
   "type" : "keyword"
   }
   }
  }
}

次の インデックス API リクエストは、2つのヒストグラムのために事前集計されたデータを保存します： histogram_1 と histogram_2。

Python

resp = client.index(
   index="my-index-000001",
   id="1",
   document={
   "my_text": "histogram_1",
   "my_histogram": {
   "values": [
                0.1,
                0.2,
                0.3,
                0.4,
                0.5
   ],
   "counts": [
   3,
   7,
   23,
   12,
   6
   ]
   }
   },
)
print(resp)
resp1 = client.index(
   index="my-index-000001",
   id="2",
   document={
   "my_text": "histogram_2",
   "my_histogram": {
   "values": [
                0.1,
                0.25,
                0.35,
                0.4,
                0.45,
                0.5
   ],
   "counts": [
   8,
   17,
   8,
   7,
   6,
   2
   ]
   }
   },
)
print(resp1)

Ruby

response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
   my_text: 'histogram_1',
   my_histogram: {
   values: [
        0.1,
        0.2,
        0.3,
        0.4,
        0.5
   ],
   counts: [
   3,
   7,
   23,
   12,
   6
   ]
   }
  }
)
puts response
response = client.index(
  index: 'my-index-000001',
  id: 2,
  body: {
   my_text: 'histogram_2',
   my_histogram: {
   values: [
        0.1,
        0.25,
        0.35,
        0.4,
        0.45,
        0.5
   ],
   counts: [
   8,
   17,
   8,
   7,
   6,
   2
   ]
   }
  }
)
puts response

Js

const response = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
   my_text: "histogram_1",
   my_histogram: {
   values: [0.1, 0.2, 0.3, 0.4, 0.5],
   counts: [3, 7, 23, 12, 6],
   },
  },
});
console.log(response);
const response1 = await client.index({
  index: "my-index-000001",
  id: 2,
  document: {
   my_text: "histogram_2",
   my_histogram: {
   values: [0.1, 0.25, 0.35, 0.4, 0.45, 0.5],
   counts: [8, 17, 8, 7, 6, 2],
   },
  },
});
console.log(response1);

コンソール

PUT my-index-000001/_doc/1
{
  "my_text" : "histogram_1",
  "my_histogram" : {
   "values" : [0.1, 0.2, 0.3, 0.4, 0.5],
   "counts" : [3, 7, 23, 12, 6]
   }
}
PUT my-index-000001/_doc/2
{
  "my_text" : "histogram_2",
  "my_histogram" : {
   "values" : [0.1, 0.25, 0.35, 0.4, 0.45, 0.5],
   "counts" : [8, 17, 8, 7, 6, 2]
   }
}