グラフ探索API（Graph explore API）

グラフ探索API

グラフ探索APIを使用すると、Elasticsearchデータストリームまたはインデックス内のドキュメントや用語に関する情報を抽出し、要約できます。

このAPIの動作を理解する最も簡単な方法は、Graph UIを使用して接続を探索することです。最後のリクエストパネルから、_exploreエンドポイントに送信された最新のリクエストを表示できます。詳細については、Graphの始め方を参照してください。

探索APIの使用に関する追加情報については、Graphのトラブルシューティングおよび制限事項のトピックを参照してください。

グラフ探索APIはデフォルトで有効になっています。グラフ探索APIおよびKibanaのGraph UIへのアクセスを無効にするには、xpack.graph.enabled: falseをelasticsearch.ymlに追加します。

リクエスト

POST <target>/_graph/explore

説明

_explore APIへの最初のリクエストには、関心のあるドキュメントを特定し、グラフに含めたい頂点と接続を定義するフィールドを指定するシードクエリが含まれています。その後の_exploreリクエストでは、関心のある1つ以上の頂点からスパイダーアウトすることができます。すでに返された頂点を除外することができます。

リクエストボディ

• クエリ
• 関心のあるドキュメントを特定するシードクエリ。任意の有効なElasticsearchクエリを使用できます。例えば：

Js

"query": {
  "bool": {
   "must": {
   "match": {
   "query.raw": "midi"
   }
   },
   "filter": [
   {
   "range": {
   "query_time": {
   "gte": "2015-10-01 00:00:00"
   }
   }
   }
   ]
  }
}

• 頂点
• グラフに頂点として含めたい用語を含む1つ以上のフィールドを指定します。例えば：

Js

"vertices": [
  {
   "field": "product"
   }
]

  -   フィールド   
  -  関心のあるドキュメント内のフィールドを特定します。  
  -   含める   
  -  スパイダーアウトしたい出発点を形成する関心のある用語を特定します。含める句を指定する場合、シードクエリを指定する必要はありません。含める句は、リストされた用語のいずれかを含むドキュメントを暗黙的にクエリします。単純な文字列の配列を指定するだけでなく、`````term`````および`````boost`````の値を持つオブジェクトを渡して特定の用語の一致を強化することもできます。  
  -   除外   
  -  `````exclude`````句は、指定された用語が結果に含まれるのを防ぎます。  
  -   サイズ   
  -  各フィールドに対して返される頂点用語の最大数を指定します。デフォルトは5です。  
  -   min_doc_count   
  -  有用な接続と見なされるために、用語のペアを含む必要があるドキュメントの数を指定します。この設定は確実性の閾値として機能します。デフォルトは3です。  
  -   shard_min_doc_count   
  -  この高度な設定は、特定のシャード上で用語のペアを含む必要があるドキュメントの数を制御します。デフォルトは2です。     
-   接続   
-  指定された頂点に関連する用語を抽出したい1つ以上のフィールドを指定します。例えば：
#### Js
``````js
"connections": {
  "vertices": [
   {
   "field": "query.raw"
   }
  ]
}
`

接続はconnectionsオブジェクト内にネストされ、データ内の追加の関係を探索できます。ネストの各レベルはホップと見なされ、グラフ内の近接はしばしばホップの深さで説明されます。

  -   クエリ   
  -  接続された用語を探索する際にGraph APIを制約するオプションのガイドクエリです。例えば、最近のドキュメントを特定するクエリを指定して、Graph APIに古いデータを無視させることができます。  
  -   頂点   
  -  興味のあるフィールドを含みます。例えば：
#### Js
``````js
"vertices": [
  {
   "field": "query.raw",
   "size": 5,
   "min_doc_count": 10,
   "shard_min_doc_count": 3
  }
]
`

• コントロール
• グラフを構築する方法をGraph APIに指示します。
  controlsのプロパティ
  • use_significance
  • use_significanceフラグは、関連する用語をフィルタリングし、クエリに大きく関連する用語のみを含めます。重要性を計算するために使用されるアルゴリズムについては、significant_terms集約を参照してください。デフォルトはtrueです。
  • sample_size
  • 各ホップは、各シャードで最も一致するドキュメントのサンプルを考慮します。サンプルを使用すると、実行速度が向上し、意味的に関連する用語に焦点を当てた探索が維持されます。非常に小さな値（50未満）は、用語間の重要な接続を特定するための十分な証拠の重みを提供しない可能性があります。非常に大きなサンプルサイズは、結果の質を希薄にし、実行時間を増加させる可能性があります。デフォルトは100ドキュメントです。
  • timeout
  • 探索が停止され、これまでに収集された結果が返されるまでのミリ秒単位の時間の長さ。このタイムアウトは、最善の努力に基づいて尊重されます。例えば、フィールドデータがフィールドにロードされる際に長い一時停止が発生した場合、実行がこのタイムアウトを超える可能性があります。
  • sample_diversity
  • トップ一致するドキュメントのサンプルが単一の結果ソースによって支配されるのを避けるために、サンプルの多様性を要求する必要がある場合があります。これを行うには、単一値フィールドを選択し、そのフィールドの値ごとに最大ドキュメント数を設定します。例えば：

Js

"sample_diversity": {
  "field": "category.raw",
  "max_docs_per_value": 500
}

例

基本的な探索

最初の検索は通常、強く関連する用語を特定するクエリから始まります。

Python

resp = client.graph.explore(
   index="clicklogs",
   query={
   "match": {
   "query.raw": "midi"
   }
   },
   vertices=[
   {
   "field": "product"
   }
   ],
   connections={
   "vertices": [
   {
   "field": "query.raw"
   }
   ]
   },
)
print(resp)

Js

const response = await client.graph.explore({
  index: "clicklogs",
  query: {
   match: {
   "query.raw": "midi",
   },
  },
  vertices: [
   {
   field: "product",
   },
  ],
  connections: {
   vertices: [
   {
   field: "query.raw",
   },
   ],
  },
});
console.log(response);

コンソール

POST clicklogs/_graph/explore
{
  "query": {
   "match": {
   "query.raw": "midi"
   }
  },
  "vertices": [
   {
   "field": "product"
   }
  ],
  "connections": {
   "vertices": [
   {
   "field": "query.raw"
   }
   ]
  }
}

探索APIからの応答は次のようになります：

Js

{
   "took": 0,
   "timed_out": false,
   "failures": [],
   "vertices": [
   {
   "field": "query.raw",
   "term": "midi cable",
   "weight": 0.08745858139552132,
   "depth": 1
   },
   {
   "field": "product",
   "term": "8567446",
   "weight": 0.13247784285434397,
   "depth": 0
   },
   {
   "field": "product",
   "term": "1112375",
   "weight": 0.018600718471158982,
   "depth": 0
   },
   {
   "field": "query.raw",
   "term": "midi keyboard",
   "weight": 0.04802242866755111,
   "depth": 1
   }
   ],
   "connections": [
   {
   "source": 0,
   "target": 1,
   "weight": 0.04802242866755111,
   "doc_count": 13
   },
   {
   "source": 2,
   "target": 3,
   "weight": 0.08120623870976627,
   "doc_count": 23
   }
   ]
}

| | 配列内の頂点間の接続。sourceおよびtargetプロパティは頂点配列にインデックスされ、探索の一部としてどの頂点用語が他の用語に導いたかを示します。doc_count値は、サンプルセット内のこの用語のペアを含むドキュメントの数を示します（これはデータストリームまたはインデックス内のすべてのドキュメントのグローバルカウントではありません）。

オプショナルコントロール

デフォルトの設定は、ノイズの多いデータを除去し、データから”全体像”を取得するように構成されています。この例では、グラフの構築方法に影響を与える追加のパラメータを指定する方法を示します。

すべてのドキュメントが関心のある場合の詳細な法医学的評価のための設定を調整するためのヒントについては、トラブルシューティングガイドを参照してください。

Python

resp = client.graph.explore(
   index="clicklogs",
   query={
   "match": {
   "query.raw": "midi"
   }
   },
   controls={
   "use_significance": False,
   "sample_size": 2000,
   "timeout": 2000,
   "sample_diversity": {
   "field": "category.raw",
   "max_docs_per_value": 500
   }
   },
   vertices=[
   {
   "field": "product",
   "size": 5,
   "min_doc_count": 10,
   "shard_min_doc_count": 3
   }
   ],
   connections={
   "query": {
   "bool": {
   "filter": [
   {
   "range": {
   "query_time": {
   "gte": "2015-10-01 00:00:00"
   }
   }
   }
   ]
   }
   },
   "vertices": [
   {
   "field": "query.raw",
   "size": 5,
   "min_doc_count": 10,
   "shard_min_doc_count": 3
   }
   ]
   },
)
print(resp)

Js

const response = await client.graph.explore({
  index: "clicklogs",
  query: {
   match: {
   "query.raw": "midi",
   },
  },
  controls: {
   use_significance: false,
   sample_size: 2000,
   timeout: 2000,
   sample_diversity: {
   field: "category.raw",
   max_docs_per_value: 500,
   },
  },
  vertices: [
   {
   field: "product",
   size: 5,
   min_doc_count: 10,
   shard_min_doc_count: 3,
   },
  ],
  connections: {
   query: {
   bool: {
   filter: [
   {
   range: {
   query_time: {
   gte: "2015-10-01 00:00:00",
   },
   },
   },
   ],
   },
   },
   vertices: [
   {
   field: "query.raw",
   size: 5,
   min_doc_count: 10,
   shard_min_doc_count: 3,
   },
   ],
  },
});
console.log(response);

コンソール

POST clicklogs/_graph/explore
{
  "query": {
   "match": {
   "query.raw": "midi"
   }
  },
  "controls": {
   "use_significance": false,
   "sample_size": 2000,
   "timeout": 2000,
   "sample_diversity": {
   "field": "category.raw",
   "max_docs_per_value": 500
   }
  },
  "vertices": [
   {
   "field": "product",
   "size": 5,
   "min_doc_count": 10,
   "shard_min_doc_count": 3
   }
  ],
  "connections": {
   "query": {
   "bool": {
   "filter": [
   {
   "range": {
   "query_time": {
   "gte": "2015-10-01 00:00:00"
   }
   }
   }
   ]
   }
   },
   "vertices": [
   {
   "field": "query.raw",
   "size": 5,
   "min_doc_count": 10,
   "shard_min_doc_count": 3
   }
   ]
  }
}

スパイダー操作

最初の検索の後、通常は関心のある頂点を選択し、追加の接続があるかどうかを確認したいと思います。グラフ用語では、この操作は”スパイダー”と呼ばれます。一連のリクエストを送信することで、関連情報のグラフを徐々に構築できます。

スパイダーアウトするには、2つのことを指定する必要があります：

• 追加の接続を見つけたい頂点のセット
• 結果から除外したい既に知っている頂点のセット。

この情報は、includeおよびexclude句を使用して指定します。例えば、次のリクエストは製品1854873から始まり、その製品に関連する追加の検索用語を見つけるためにスパイダーアウトします。用語”midi”、”midiキーボード”、および”シンセ”は結果から除外されます。

Python

resp = client.graph.explore(
   index="clicklogs",
   vertices=[
   {
   "field": "product",
   "include": [
   "1854873"
   ]
   }
   ],
   connections={
   "vertices": [
   {
   "field": "query.raw",
   "exclude": [
   "midi keyboard",
   "midi",
   "synth"
   ]
   }
   ]
   },
)
print(resp)

Js

const response = await client.graph.explore({
  index: "clicklogs",
  vertices: [
   {
   field: "product",
   include: ["1854873"],
   },
  ],
  connections: {
   vertices: [
   {
   field: "query.raw",
   exclude: ["midi keyboard", "midi", "synth"],
   },
   ],
  },
});
console.log(response);

コンソール

POST clicklogs/_graph/explore
{
   "vertices": [
   {
   "field": "product",
   "include": [ "1854873" ]
   }
   ],
   "connections": {
   "vertices": [
   {
   "field": "query.raw",
   "exclude": [
   "midi keyboard",
   "midi",
   "synth"
   ]
   }
   ]
   }
}