› ›

图探索 API

编辑

图探索 API编辑

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

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

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

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

请求编辑

POST <target>/_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
}

示例编辑

基本探索编辑

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

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` 值指示样本集中有多少个文档包含这对术语（这不是数据流或索引中所有文档的全局计数）。

可选控制编辑

默认设置配置为删除噪声数据并从您的数据中获取“大局”。此示例展示了如何指定其他参数来影响图的构建方式。

有关调整设置以进行更详细的取证评估（其中每个文档都可能很重要）的提示，请参阅故障排除指南。

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”已从结果中排除。

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

	您要从中开始的顶点作为 `include` 子句中的术语数组指定。
	`exclude` 子句阻止您已经知道的术语包含在结果中。

« Fleet 多搜索 API 索引 API »