« Fleet 多重搜索 API 索引 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API

图探索 API

编辑

图探索 API

编辑

图探索 API 使您能够提取和总结 Elasticsearch 数据流或索引中的文档和术语信息。

了解此 API 行为的最简单方法是使用图 UI 探索连接。您可以从上次请求面板中查看提交到 _explore 端点的最新请求。有关更多信息，请参阅图入门。

有关使用探索 API 的更多信息，请参阅图 故障排除和限制主题。

默认情况下启用图探索 API。要禁用对图探索 API 和 Kibana 图 UI 的访问，请将 xpack.graph.enabled: false 添加到 elasticsearch.yml。

请求

编辑

POST <目标>/_graph/explore

描述

编辑

对 _explore API 的初始请求包含一个种子查询，该查询标识感兴趣的文档，并指定您要包含在图中的顶点和连接的字段。后续的 _explore 请求使您能够从一个或多个感兴趣的顶点向外扩展。您可以排除已经返回的顶点。

请求正文

编辑
query

标识感兴趣文档的种子查询。可以是任何有效的 Elasticsearch 查询。例如

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

指定一个或多个字段，其中包含您要作为顶点包含在图中的术语。例如

"vertices": [
  {
    "field": "product"
    }
]
vertices 的属性
field
标识感兴趣的文档中的字段。
include
标识您想要从中向外扩展的起始点的感兴趣的术语。如果您指定 include 子句，则不必指定种子查询。include 子句隐式查询包含任何列出术语的文档。除了指定简单的字符串数组外，您还可以传递具有 term 和 boost 值的对象，以提升特定术语的匹配度。
exclude
exclude 子句阻止将指定的术语包含在结果中。
size
指定每个字段返回的最大顶点术语数。默认为 5。
min_doc_count
指定在被认为是有效连接之前，必须有多少文档包含一对术语。此设置充当确定性阈值。默认为 3。
shard_min_doc_count
此高级设置控制特定分片上有多少文档必须包含一对术语，然后该连接才能返回以供全局考虑。默认为 2。
connections

指定您想要从中提取与指定顶点关联的术语的一个或多个字段。例如

"connections": {  
  "vertices": [
    {
      "field": "query.raw"
    }
  ]
}

连接可以嵌套在 connections 对象内部，以探索数据中的其他关系。每个嵌套级别都被视为一个跳跃，并且图中邻近度通常以跳跃深度来描述。

connections 的属性
query
一个可选的引导查询，它在探索连接的术语时约束图 API。例如，您可能希望通过指定标识最近文档的查询来指导图 API 忽略旧数据。
vertices

包含您感兴趣的字段。例如

"vertices": [
  {
    "field": "query.raw",
    "size": 5,
    "min_doc_count": 10,
    "shard_min_doc_count": 3
  }
]
controls

指导图 API 如何构建图。

controls 的属性
use_significance
use_significance 标志会筛选关联的术语，以便只包含与您的查询显着关联的术语。有关用于计算显着性的算法的信息，请参阅significant_terms 聚合。默认为 true。
sample_size
每个跳跃都会考虑每个分片上最佳匹配文档的样本。使用样本可以提高执行速度，并使探索集中在有意义地连接的术语上。非常小的值（小于 50）可能无法提供足够的证据权重来识别术语之间显着的连接。非常大的样本量会降低结果的质量并增加执行时间。默认为 100 个文档。
timeout
以毫秒为单位的时间长度，在此时间之后，将停止探索并返回到目前为止收集的结果。此超时以尽力而为的方式执行。如果例如在为字段加载 FieldData 时遇到长时间的暂停，则执行可能会超出此超时。
sample_diversity

为了避免最佳匹配的文档样本被单一的结果来源主导，有时有必要请求样本中的多样性。您可以通过选择一个单值字段并为该字段的每个值设置最大文档数来完成此操作。例如

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

示例

编辑

基本探索

编辑

初始搜索通常以查询开始，以识别强相关的术语。

resp = client.graph.explore(
    index="clicklogs",
    query={
        "match": {
            "query.raw": "midi"
        }
    },
    vertices=[
        {
            "field": "product"
        }
    ],
    connections={
        "vertices": [
            {
                "field": "query.raw"
            }
        ]
    },
)
print(resp)
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"
      }
    ]
  }
}

使用查询播种探索。此示例是在点击日志中搜索搜索词“midi”的人。

标识要包含在图中的顶点。此示例正在查找与搜索“midi”显着关联的产品代码。

查找连接。此示例正在查找导致人们点击与搜索“midi”相关联的产品的其他搜索词。

来自探索 API 的响应如下所示

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

发现的所有顶点的数组。顶点是索引术语，因此提供了字段和术语值。weight 属性指定显着性分数。depth 属性指定首次遇到术语时的跳跃级别。

数组中顶点之间的连接。source 和 target 属性已索引到顶点数组中，并指示哪个顶点术语在探索过程中导致了另一个顶点。doc_count 值指示样本集中有多少文档包含此术语对（这不是数据流或索引中所有文档的全局计数）。

可选控件

编辑

默认设置配置为删除嘈杂的数据并从您的数据中获取“全局视图”。此示例演示如何指定其他参数来影响图的构建方式。

有关调整设置以进行更详细的法证评估（其中每个文档都可能感兴趣）的技巧，请参阅故障排除指南。

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

禁用 use_significance 以包含所有关联的术语，而不仅仅是与查询显着关联的术语。

增加样本大小以考虑每个分片上的更大文档集。

限制图请求在返回结果之前运行的时间。

通过在特定单值字段（如类别字段）中为每个值设置文档数量限制来确保样本中的多样性。

控制每个字段返回的最大顶点术语数。

设置一个确定性阈值，指定在将一对术语视为有用的连接之前，必须有多少文档包含这对术语。

指定在将连接返回以供全局考虑之前，分片上有多少文档必须包含一对术语。

在探索连接的术语时限制考虑哪些文档。

蜘蛛式操作

编辑

在初始搜索之后，您通常需要选择感兴趣的顶点并查看连接了哪些其他顶点。在图的说法中，此操作称为“蜘蛛式”。通过提交一系列请求，您可以逐步构建相关信息的图。

要向外扩展，您需要指定两件事

  • 您要为其查找其他连接的顶点集
  • 您已经知道的并且要从蜘蛛式操作的结果中排除的顶点集。

您可以使用 include 和 exclude 子句指定此信息。例如，以下请求从产品 1854873 开始，并向外扩展以查找与该产品关联的其他搜索词。结果中排除了术语“midi”、“midi keyboard”和“synth”。

resp = client.graph.explore(
    index="clicklogs",
    vertices=[
        {
            "field": "product",
            "include": [
                "1854873"
            ]
        }
    ],
    connections={
        "vertices": [
            {
                "field": "query.raw",
                "exclude": [
                    "midi keyboard",
                    "midi",
                    "synth"
                ]
            }
        ]
    },
)
print(resp)
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"
            ]
         }
      ]
   }
}

您要开始的顶点指定为 include 子句中的术语数组。

exclude 子句阻止将您已经知道的术语包含在结果中。
« Fleet 多重搜索 API 索引 API »