Explore graph analytics

GET /{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.

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

  • Additional properties are allowed.

    Hide connections attributes Show connections attributes object
    • Additional properties are allowed.

    • query object Required

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

      Additional properties are allowed.

    • 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
      • 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.

      • 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

    Additional properties are allowed.

    Hide controls attributes Show controls attributes object
    • Additional properties are allowed.

      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
    • 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.

    Additional properties are allowed.

  • 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
    • 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.

    • 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
    • failures array[object] Required
      Hide failures attributes Show failures attributes object
      • index string
      • node string
      • reason object Required

        Additional properties are allowed.

        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.

        • The server stack trace. Present only if the error_trace=true parameter was sent with the request.

        • Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • 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
GET /{index}/_graph/explore
curl \
 -X GET http://api.example.com/{index}/_graph/explore \
 -H "Content-Type: application/json" \
 -d '"{\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
    }
  ]
}



















































































































































































































































































































































































































































































Create an inference endpoint Added in 8.11.0

PUT /_inference/{inference_id}

When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. After creating the endpoint, wait for the model deployment to complete before using it. To verify the deployment status, use the get trained model statistics API. Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

Path parameters

application/json

Body Required

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
PUT /_inference/{inference_id}
curl \
 -X PUT http://api.example.com/_inference/{inference_id} \
 -H "Content-Type: application/json" \
 -d '{"service":"string","service_settings":{},"task_settings":{}}'
Request examples
{
  "service": "string",
  "service_settings": {},
  "task_settings": {}
}
Response examples (200)
{
  "service": "string",
  "service_settings": {},
  "task_settings": {},
  "inference_id": "string",
  "task_type": "sparse_embedding"
}






























































































































































































































































































































































































































































































































































































































































































































































































Create or update a script or search template

PUT /_scripts/{id}

Creates or updates a stored script or search template.

Path parameters

  • id string Required

    Identifier for the stored script or search template. Must be unique within the cluster.

Query parameters

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

application/json

Body Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_scripts/{id}
curl \
 -X PUT http://api.example.com/_scripts/{id} \
 -H "Content-Type: application/json" \
 -d '{"script":{"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"},"source":"string"}}'
Request examples
{
  "script": {
    "": "painless",
    "options": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    },
    "source": "string"
  }
}
Response examples (200)
{
  "acknowledged": true
}






































































































































































































































































































































































































































































































































































































































































































































































































Get policy information Added in 7.4.0

GET /_slm/policy/{policy_id}

Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.

Path parameters

  • policy_id string | array[string] Required

    Comma-separated list of snapshot lifecycle policies to retrieve

Query parameters

  • The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout string

    The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • Additional properties are allowed.

        Hide in_progress attributes Show in_progress attributes object
      • Additional properties are allowed.

        Hide last_failure attributes Show last_failure attributes object
      • Additional properties are allowed.

        Hide last_success attributes Show last_success attributes object
      • modified_date string | number

        A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

      • Time unit for milliseconds

      • next_execution string | number

        A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

      • Time unit for milliseconds

      • policy object Required

        Additional properties are allowed.

        Hide policy attributes Show policy attributes object
        • config object

          Additional properties are allowed.

          Hide config attributes Show config attributes object
          • If false, the snapshot fails if any data stream or index in indices is missing or closed. If true, the snapshot ignores missing or closed data streams and indices.

          • indices string | array[string]
          • If true, the current global state is included in the snapshot.

          • feature_states array[string]

            A list of feature states to be included in this snapshot. A list of features available for inclusion in the snapshot and their descriptions be can be retrieved using the get features API. Each feature state includes one or more system indices containing data necessary for the function of that feature. Providing an empty array will include no feature states in the snapshot, regardless of the value of include_global_state. By default, all available feature states will be included in the snapshot if include_global_state is true, or no feature states if include_global_state is false.

          • metadata object
            Hide metadata attribute Show metadata attribute object
            • * object Additional properties

              Additional properties are allowed.

          • partial boolean

            If false, the entire snapshot will fail if one or more indices included in the snapshot do not have all primary shards available.

        • name string Required
        • repository string Required
        • Additional properties are allowed.

          Hide retention attributes Show retention attributes object
          • expire_after string Required

            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.

          • max_count number Required

            Maximum number of snapshots to retain, even if the snapshots have not yet expired. If the number of snapshots in the repository exceeds this limit, the policy retains the most recent snapshots and deletes older snapshots.

          • min_count number Required

            Minimum number of snapshots to retain, even if the snapshots have expired.

        • schedule string Required
      • version number Required
      • stats object Required

        Additional properties are allowed.

        Hide stats attributes Show stats attributes object
GET /_slm/policy/{policy_id}
curl \
 -X GET http://api.example.com/_slm/policy/{policy_id}
Response examples (200)
{
  "additionalProperty1": {
    "in_progress": {
      "name": "string",
      "": 42.0,
      "state": "string",
      "uuid": "string"
    },
    "last_failure": {
      "snapshot_name": "string",
      "": "string"
    },
    "last_success": {
      "snapshot_name": "string",
      "": "string"
    },
    "": 42.0,
    "policy": {
      "config": {
        "ignore_unavailable": true,
        "indices": "string",
        "include_global_state": true,
        "feature_states": [
          "string"
        ],
        "metadata": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "partial": true
      },
      "name": "string",
      "repository": "string",
      "retention": {
        "expire_after": "string",
        "max_count": 42.0,
        "min_count": 42.0
      },
      "schedule": "string"
    },
    "version": 42.0,
    "stats": {
      "retention_deletion_time": "string",
      "": 42.0,
      "retention_failed": 42.0,
      "retention_runs": 42.0,
      "retention_timed_out": 42.0,
      "policy": "string",
      "total_snapshots_deleted": 42.0,
      "total_snapshot_deletion_failures": 42.0,
      "total_snapshots_failed": 42.0,
      "total_snapshots_taken": 42.0
    }
  },
  "additionalProperty2": {
    "in_progress": {
      "name": "string",
      "": 42.0,
      "state": "string",
      "uuid": "string"
    },
    "last_failure": {
      "snapshot_name": "string",
      "": "string"
    },
    "last_success": {
      "snapshot_name": "string",
      "": "string"
    },
    "": 42.0,
    "policy": {
      "config": {
        "ignore_unavailable": true,
        "indices": "string",
        "include_global_state": true,
        "feature_states": [
          "string"
        ],
        "metadata": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "partial": true
      },
      "name": "string",
      "repository": "string",
      "retention": {
        "expire_after": "string",
        "max_count": 42.0,
        "min_count": 42.0
      },
      "schedule": "string"
    },
    "version": 42.0,
    "stats": {
      "retention_deletion_time": "string",
      "": 42.0,
      "retention_failed": 42.0,
      "retention_runs": 42.0,
      "retention_timed_out": 42.0,
      "policy": "string",
      "total_snapshots_deleted": 42.0,
      "total_snapshot_deletion_failures": 42.0,
      "total_snapshots_failed": 42.0,
      "total_snapshots_taken": 42.0
    }
  }
}












Run a retention policy Added in 7.5.0

POST /_slm/_execute_retention

Manually apply the retention policy to force immediate removal of snapshots that are expired according to the snapshot lifecycle policy retention rules. The retention policy is normally applied according to its schedule.

Query parameters

  • The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout string

    The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_slm/_execute_retention
curl \
 -X POST http://api.example.com/_slm/_execute_retention
Response examples (200)
{
  "acknowledged": true
}