Explore graph analytics

POST /{index}/_graph/explore

Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. The easiest way to understand the behavior of this API is to use the Graph UI to explore connections. An initial request to the _explore API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph. Subsequent requests enable you to spider out from one more vertices of interest. You can exclude vertices that have already been returned.

External documentation

Path parameters

index string | array[string] Required

Name of the index.

Query parameters

routing string

Custom value used to route operations to a specific shard.
timeout string

Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.

application/json

Body

connections object
Hide connections attributes Show connections attributes object
- connections object
- query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- vertices array[object] Required
  
  Contains the fields you are interested in.
  Hide vertices attributes Show vertices attributes object
  
  exclude array[string]
  
  Prevents the specified terms from being included in the results.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  include array[object]
  
  Identifies the terms of interest that form the starting points from which you want to spider out.
  
  Hide include attributes Show include attributes object
  
  boost number Required
  
  term string Required
  
  min_doc_count number
  
  Specifies how many documents must contain a pair of terms before it is considered to be a useful connection. This setting acts as a certainty threshold.
  
  shard_min_doc_count number
  
  Controls how many documents on a particular shard have to contain a pair of terms before the connection is returned for global consideration.
  
  size number
  
  Specifies the maximum number of vertex terms returned for each field.
controls object
Hide controls attributes Show controls attributes object
- sample_diversity object
  Hide sample_diversity attributes Show sample_diversity attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  max_docs_per_value number Required
- sample_size number
  
  Each hop considers a sample of the best-matching documents on each shard. Using samples improves the speed of execution and keeps exploration focused on meaningfully-connected terms. Very small values (less than 50) might not provide sufficient weight-of-evidence to identify significant connections between terms. Very large sample sizes can dilute the quality of the results and increase execution times.
- timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- use_significance boolean Required
  
  Filters associated terms so only those that are significantly associated with your query are included.
query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
vertices array[object]

Specifies one or more fields that contain the terms you want to include in the graph as vertices.
Hide vertices attributes Show vertices attributes object
- exclude array[string]
  
  Prevents the specified terms from being included in the results.
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- include array[object]
  
  Identifies the terms of interest that form the starting points from which you want to spider out.
  Hide include attributes Show include attributes object
  
  boost number Required
  
  term string Required
- min_doc_count number
  
  Specifies how many documents must contain a pair of terms before it is considered to be a useful connection. This setting acts as a certainty threshold.
- shard_min_doc_count number
  
  Controls how many documents on a particular shard have to contain a pair of terms before the connection is returned for global consideration.
- size number
  
  Specifies the maximum number of vertex terms returned for each field.

Responses

200 application/json
Hide response attributes Show response attributes object
- connections array[object] Required
  
  Hide connections attributes Show connections attributes object
  
  doc_count number Required
  
  source number Required
  
  target number Required
  
  weight number Required
- failures array[object] Required
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
- timed_out boolean Required
- took number Required
- vertices array[object] Required
  
  Hide vertices attributes Show vertices attributes object
  
  depth number Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  term string Required
  
  weight number Required

POST /{index}/_graph/explore

curl \
 --request POST http://api.example.com/{index}/_graph/explore \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"match\": {\n      \"query.raw\": \"midi\"\n    }\n  },\n  \"vertices\": [\n    {\n      \"field\": \"product\"\n    }\n  ],\n  \"connections\": {\n    \"vertices\": [\n      {\n        \"field\": \"query.raw\"\n      }\n    ]\n  }\n}"'

Request example

Run `POST clicklogs/_graph/explore` for a basic exploration An initial graph explore query typically begins with a query to identify strongly related terms. Seed the exploration with a query. This example is searching `clicklogs` for people who searched for the term `midi`.Identify the vertices to include in the graph. This example is looking for product codes that are significantly associated with searches for `midi`. Find the connections. This example is looking for other search terms that led people to click on the products that are associated with searches for `midi`.

{
  "query": {
    "match": {
      "query.raw": "midi"
    }
  },
  "vertices": [
    {
      "field": "product"
    }
  ],
  "connections": {
    "vertices": [
      {
        "field": "query.raw"
      }
    ]
  }
}

Response examples (200)

{
  "connections": [
    {
      "doc_count": 42.0,
      "source": 42.0,
      "target": 42.0,
      "weight": 42.0
    }
  ],
  "failures": [
    {
      "index": "string",
      "node": "string",
      "reason": {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      },
      "shard": 42.0,
      "status": "string"
    }
  ],
  "timed_out": true,
  "took": 42.0,
  "vertices": [
    {
      "depth": 42.0,
      "field": "string",
      "term": "string",
      "weight": 42.0
    }
  ]
}