« Fleet APIs Index APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

图探索API

edit

图探索API

edit

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

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

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

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

请求

edit

POST /_graph/explore

描述

edit

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

请求体

edit
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 对象中，以探索数据中的其他关系。每一层嵌套都被视为一个跳跃，图中的接近度通常用跳跃深度来描述。

Properties for connections
query
一个可选的引导查询，用于约束 Graph API 在探索连接术语时的行为。例如，您可能希望通过指定一个查询来忽略旧数据，该查询标识最近的文档。
vertices

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

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

指导 Graph API 如何构建图表。

Properties for controls
use_significance
The use_significance 标志过滤关联术语，以便仅包含与您的查询显著关联的术语。有关用于计算显著性的算法的信息，请参阅 significant_terms 聚合。默认为 true。
sample_size
每个 hop 考虑每个分片上最佳匹配文档的样本。使用样本可以提高执行速度，并使探索集中在有意义连接的术语上。非常小的值（小于 50）可能无法提供足够的证据权重来识别术语之间的显著连接。非常大的样本量可能会稀释结果的质量并增加执行时间。默认为 100 个文档。
timeout
探索将在多少毫秒后停止，并返回迄今为止收集的结果。此超时是尽力而为的。如果遇到加载字段数据的长时间暂停，执行可能会超过此超时。
sample_diversity

为了避免顶部匹配的文档样本被单一的结果源所主导，有时需要在样本中请求多样性。您可以通过选择一个单值字段并为该字段的每个值设置最大文档数量来实现这一点。例如： 

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

示例

edit

基本探索

edit

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

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

可选控件

edit

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

有关在需要更详细的取证评估时调整设置的提示，请参阅故障排除指南。

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 以包含所有关联词，而不仅仅是那些与查询显著关联的词。

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

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

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

控制每个字段返回的顶点项的最大数量。

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

指定在分片上必须有多少文档包含一对术语，然后该连接才会被返回以供全局考虑。

限制在探索相关术语时考虑哪些文档。

爬取操作

edit

在初步搜索之后，您通常希望选择感兴趣的顶点并查看与之连接的其他顶点。在图论中，这个操作被称为“蜘蛛化”。通过提交一系列请求，您可以逐步构建一个相关信息的图。

要进行爬取，您需要指定两件事：

  • 您想要查找其他连接的顶点集
  • 您已经知道的顶点集，您希望将其从爬取操作的结果中排除。

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

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

您希望从其开始的顶点被指定为include子句中的术语数组。

The exclude 子句防止您已经知道的术语被包含在结果中。
« Fleet APIs Index APIs »