Explore graph analytics

POST also GET /{index}/_graph/explore

Auth

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.

Learn more about graphs

Required privileges

Index privileges read

Path parameters

index union string | string[] required: Name of the index.

Query parameters

routing union string | string[]: Custom value used to route operations to a specific shard.
timeout union oneOf: 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.; Values: -1 0; Reference

Request body

connections object: Specifies or more fields from which you want to extract terms that are associated with the specified vertices.
controls object: Direct the Graph API how to build the graph.
query {} Query: A seed query that identifies the documents of interest. Can be any valid Elasticsearch query.
vertices object[]: Specifies one or more fields that contain the terms you want to include in the graph as vertices.

Response

application/json

connections object[] required
failures object[] required
timed_out boolean required
took number required
vertices object[] required

View as Markdown

Examples

Request Console 1 / 8 languages

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.

Console Kibana Dev Tools

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

JavaScript Elasticsearch JavaScript Client

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

Python Elasticsearch Python Client

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

curl Shell

curl -X POST "$ELASTICSEARCH_URL/clicklogs/_graph/explore" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "query.raw": "midi"
      }
    },
    "vertices": [
      {
        "field": "product"
      }
    ],
    "connections": {
      "vertices": [
        {
          "field": "query.raw"
        }
      ]
    }
  }'

Java Elasticsearch Java Client

client.graph().explore(e -> e
    .connections(c -> c
        .vertices(v -> v
            .field("query.raw")
        )
    )
    .index("clicklogs")
    .query(q -> q
        .match(m -> m
            .field("query.raw")
            .query(FieldValue.of("midi"))
        )
    )
    .vertices(v -> v
        .field("product")
    )
);

C# Elasticsearch .NET Client

var response = await client.Graph
    .ExploreAsync(indices: new[] { "clicklogs" }, d1 => d1
        .Connections(d2 => d2
            .Vertices(d3 => d3
                .Field(x => x.Query.Raw)
            )
        )
        .Query(d2 => d2
            .Match(d3 => d3
                .Field(x => x.Query.Raw)
                .Query("midi")
            )
        )
        .Vertices(d2 => d2
            .Field(x => x.Product)
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->graph()->explore([
    "index" => "clicklogs",
    "body" => [
        "query" => [
            "match" => [
                "query.raw" => "midi",
            ],
        ],
        "vertices" => array(
            [
                "field" => "product",
            ],
        ),
        "connections" => [
            "vertices" => array(
                [
                    "field" => "query.raw",
                ],
            ),
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

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

Response

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

Generated from the API spec