---
type: api
title: Explore graph analytics
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-graph-explore
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-graph-explore
products:
  - Elasticsearch
---

# Explore graph analytics


Availability:

## Paths

- `POST` (also `GET`) `/{index}/_graph/explore`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

#### Path Parameters

- `index` (union IndexName | [] IndexName)
  Name of the index.

## Description

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](https://www.elastic.co/docs/explore-analyze/visualize/graph)

## Query String Parameters

- `routing` (union Routing)
  Custom value used to route operations to a specific shard.
  One of: `string` or `string[]`
- `timeout` (string Duration)
  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.

## Request Body

`application/json`

- `connections` ({} Hop) — optional
  Specifies or more fields from which you want to extract terms that are associated with the specified vertices.
  - `connections` ({} Hop) — optional — recursive
    Specifies one or more fields from which you want to extract terms that are associated with the specified vertices.
    Same fields as `connections`
  - `query` ({} QueryContainer) — optional
    An optional guiding query that constrains the Graph API as it explores connected terms.
    See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
  - `vertices` ([] VertexDefinition) — required
    Contains the fields you are interested in.
    - `exclude` ([] string) — optional
      Prevents the specified terms from being included in the results.
    - `field` (string Field) — required
      Identifies a field in the documents of interest.
    - `include` ([] VertexInclude) — optional
      Identifies the terms of interest that form the starting points from which you want to spider out.
      - `boost` (number) — optional
      - `term` (string) — required
    - `min_doc_count` (number · default: 3) — optional
      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 · default: 2) — optional
      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 · default: 5) — optional
      Specifies the maximum number of vertex terms returned for each field.
- `controls` ({} ExploreControls) — optional
  Direct the Graph API how to build the graph.
  - `sample_diversity` ({} SampleDiversity) — optional
    To avoid the top-matching documents sample being dominated by a single source of results, it is sometimes necessary to request diversity in the sample.
You can do this by selecting a single-value field and setting a maximum number of documents per value for that field.
    - `field` (string Field) — required
    - `max_docs_per_value` (number) — required
  - `sample_size` (number · default: 100) — optional
    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 Duration) — optional
    The length of time in milliseconds after which exploration will be halted and the results gathered so far are returned.
This timeout is honored on a best-effort basis.
Execution might overrun this timeout if, for example, a long pause is encountered while FieldData is loaded for a field.
  - `use_significance` (boolean) — required
    Filters associated terms so only those that are significantly associated with your query are included.
- `query` ({} QueryContainer) — optional
  A seed query that identifies the documents of interest. Can be any valid Elasticsearch query.
  See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
- `vertices` ([] VertexDefinition) — optional
  Specifies one or more fields that contain the terms you want to include in the graph as vertices.
  - `exclude` ([] string) — optional
    Prevents the specified terms from being included in the results.
  - `field` (string Field) — required
    Identifies a field in the documents of interest.
  - `include` ([] VertexInclude) — optional
    Identifies the terms of interest that form the starting points from which you want to spider out.
    - `boost` (number) — optional
    - `term` (string) — required
  - `min_doc_count` (number · default: 3) — optional
    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 · default: 2) — optional
    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 · default: 5) — optional
    Specifies the maximum number of vertex terms returned for each field.

## Response

`application/json`

- `connections` ([] Connection)
  - `doc_count` (number)
  - `source` (number)
  - `target` (number)
  - `weight` (number)
- `failures` ([] ShardFailure)
  - `index` (string IndexName)
  - `node` (string)
  - `reason` ({} ErrorCause)
    - `type` (string)
      The type of error
    - `reason` (union string) — nullable
      A human-readable explanation of the error, in English.
      One of: `string`
    - `stack_trace` (string)
      The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
    - `caused_by` ({} ErrorCause) — recursive
      Same fields as `reason` in `failures`
    - `root_cause` ([] ErrorCause) — recursive
      Same fields as `reason` in `failures`
    - `suppressed` ([] ErrorCause) — recursive
      Same fields as `reason` in `failures`
  - `shard` (number)
  - `status` (string)
  - `primary` (boolean)
- `timed_out` (boolean)
- `took` (number)
- `vertices` ([] Vertex)
  - `depth` (number)
  - `field` (string Field)
  - `term` (string)
  - `weight` (number)
## Code Examples

#### Console

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

#### JavaScript

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

#### Python

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

#### curl

```curl
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

```java
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#

```c#
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

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

#### Ruby

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