Elasticsearch API

Base URL
http://api.example.com

Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.

Documentation source and versions

This documentation is derived from the 8.17 branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International. This documentation contains work-in-progress information for future Elastic Stack releases.

Last update on Jan 22, 2025.

This API is provided under license Apache 2.0.
























Create a behavioral analytics collection Technical preview

PUT /_application/analytics/{name}

Path parameters

  • name string Required

    The name of the analytics collection to be created or updated.

Responses

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

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

    • name string Required
PUT /_application/analytics/{name}
curl \
 -X PUT http://api.example.com/_application/analytics/{name}
Response examples (200)
{
  "acknowledged": true,
  "name": "string"
}





















































Get the cluster health status

GET /_cat/health

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: HH:MM:SS, which is human-readable but includes no date information; Unix epoch time, which is machine-sortable and includes date information. The latter format is useful for cluster recoveries that take multiple days. You can use the cat health API to verify cluster health across multiple nodes. You also can use the API to track the recovery of a large cluster over a longer period of time.

Query parameters

  • time string

    The unit used to display time values.

    Values are nanos, micros, ms, s, m, h, or d.

  • ts boolean

    If true, returns HH:MM:SS and Unix epoch timestamps.

Responses

GET /_cat/health
curl \
 -X GET http://api.example.com/_cat/health
Response examples (200)
[
  {
    "": 42.0,
    "timestamp": "string",
    "cluster": "string",
    "status": "string",
    "node.total": "string",
    "node.data": "string",
    "shards": "string",
    "pri": "string",
    "relo": "string",
    "init": "string",
    "unassign.pri": "string",
    "unassign": "string",
    "pending_tasks": "string",
    "max_task_wait_time": "string",
    "active_shards_percent": "string"
  }
]




















Get data frame analytics jobs Added in 7.7.0

GET /_cat/ml/data_frame/analytics/{id}

Get configuration and usage information about data frame analytics jobs.

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API.

Path parameters

  • id string Required

    The ID of the data frame analytics to fetch

Query parameters

  • Whether to ignore if a wildcard expression matches no configs. (This includes _all string or when no configs have been specified)

  • bytes string

    The unit in which to display byte values

    Values are b, kb, mb, gb, tb, or pb.

  • h string | array[string]

    Comma-separated list of column names to display.

  • s string | array[string]

    Comma-separated list of column names or column aliases used to sort the response.

  • time string

    Unit used to display time values.

    Values are nanos, micros, ms, s, m, h, or d.

Responses

GET /_cat/ml/data_frame/analytics/{id}
curl \
 -X GET http://api.example.com/_cat/ml/data_frame/analytics/{id}
Response examples (200)
[
  {
    "id": "string",
    "type": "string",
    "create_time": "string",
    "version": "string",
    "source_index": "string",
    "dest_index": "string",
    "description": "string",
    "model_memory_limit": "string",
    "state": "string",
    "failure_reason": "string",
    "progress": "string",
    "assignment_explanation": "string",
    "node.id": "string",
    "node.name": "string",
    "node.ephemeral_id": "string",
    "node.address": "string"
  }
]




























Get node information

GET /_cat/nodes

Get information about the nodes in a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.

Query parameters

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

  • full_id boolean | string

    If true, return the full node ID. If false, return the shortened node ID.

  • If true, the response includes information from segments that are not loaded into memory.

  • Period to wait for a connection to the master node.

  • time string

    Unit used to display time values.

    Values are nanos, micros, ms, s, m, h, or d.

Responses

GET /_cat/nodes
curl \
 -X GET http://api.example.com/_cat/nodes
Response examples (200)
[
  {
    "id": "string",
    "pid": "string",
    "ip": "string",
    "port": "string",
    "http_address": "string",
    "version": "string",
    "flavor": "string",
    "type": "string",
    "build": "string",
    "jdk": "string",
    "": "string",
    "heap.current": "string",
    "heap.max": "string",
    "ram.current": "string",
    "ram.max": "string",
    "file_desc.current": "string",
    "file_desc.max": "string",
    "cpu": "string",
    "load_1m": "string",
    "load_5m": "string",
    "load_15m": "string",
    "uptime": "string",
    "node.role": "string",
    "master": "string",
    "name": "string",
    "completion.size": "string",
    "fielddata.memory_size": "string",
    "fielddata.evictions": "string",
    "query_cache.memory_size": "string",
    "query_cache.evictions": "string",
    "query_cache.hit_count": "string",
    "query_cache.miss_count": "string",
    "request_cache.memory_size": "string",
    "request_cache.evictions": "string",
    "request_cache.hit_count": "string",
    "request_cache.miss_count": "string",
    "flush.total": "string",
    "flush.total_time": "string",
    "get.current": "string",
    "get.time": "string",
    "get.total": "string",
    "get.exists_time": "string",
    "get.exists_total": "string",
    "get.missing_time": "string",
    "get.missing_total": "string",
    "indexing.delete_current": "string",
    "indexing.delete_time": "string",
    "indexing.delete_total": "string",
    "indexing.index_current": "string",
    "indexing.index_time": "string",
    "indexing.index_total": "string",
    "indexing.index_failed": "string",
    "merges.current": "string",
    "merges.current_docs": "string",
    "merges.current_size": "string",
    "merges.total": "string",
    "merges.total_docs": "string",
    "merges.total_size": "string",
    "merges.total_time": "string",
    "refresh.total": "string",
    "refresh.time": "string",
    "refresh.external_total": "string",
    "refresh.external_time": "string",
    "refresh.listeners": "string",
    "script.compilations": "string",
    "script.cache_evictions": "string",
    "script.compilation_limit_triggered": "string",
    "search.fetch_current": "string",
    "search.fetch_time": "string",
    "search.fetch_total": "string",
    "search.open_contexts": "string",
    "search.query_current": "string",
    "search.query_time": "string",
    "search.query_total": "string",
    "search.scroll_current": "string",
    "search.scroll_time": "string",
    "search.scroll_total": "string",
    "segments.count": "string",
    "segments.memory": "string",
    "segments.index_writer_memory": "string",
    "segments.version_map_memory": "string",
    "segments.fixed_bitset_memory": "string",
    "suggest.current": "string",
    "suggest.time": "string",
    "suggest.total": "string",
    "bulk.total_operations": "string",
    "bulk.total_time": "string",
    "bulk.total_size_in_bytes": "string",
    "bulk.avg_time": "string",
    "bulk.avg_size_in_bytes": "string"
  }
]
























































































Get cluster-wide settings

GET /_cluster/settings

By default, it returns only settings that have been explicitly defined.

Query parameters

  • If true, returns settings in flat format.

  • If true, returns default cluster settings from the local node.

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

Responses

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

        Additional properties are allowed.

    • transient object Required
      Hide transient attribute Show transient attribute object
      • * object Additional properties

        Additional properties are allowed.

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

        Additional properties are allowed.

GET /_cluster/settings
curl \
 -X GET http://api.example.com/_cluster/settings
Response examples (200)
{
  "persistent": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "transient": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "defaults": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}

Update the cluster settings

PUT /_cluster/settings

Configure and update dynamic settings on a running cluster. You can also configure dynamic settings locally on an unstarted or shut down node in elasticsearch.yml.

Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a null value.

If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) elasticsearch.yml setting; 4) Default setting value. For example, you can apply a transient setting to override a persistent setting or elasticsearch.yml setting. However, a change to an elasticsearch.yml setting will not override a defined transient or persistent setting.

TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster. If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings. Only use elasticsearch.yml for static cluster settings and node settings. The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.

WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.

Query parameters

application/json

Body Required

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

      Additional properties are allowed.

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

      Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • persistent object Required
      Hide persistent attribute Show persistent attribute object
      • * object Additional properties

        Additional properties are allowed.

    • transient object Required
      Hide transient attribute Show transient attribute object
      • * object Additional properties

        Additional properties are allowed.

PUT /_cluster/settings
curl \
 -X PUT http://api.example.com/_cluster/settings \
 -H "Content-Type: application/json" \
 -d '"{\n  \"persistent\" : {\n    \"indices.recovery.max_bytes_per_sec\" : \"50mb\"\n  }\n}"'
Request example
An example of a persistent update.
{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}
Response examples (200)
{
  "acknowledged": true,
  "persistent": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "transient": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}












Get the pending cluster tasks

GET /_cluster/pending_tasks

Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.

Query parameters

  • local boolean

    If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.

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

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • tasks array[object] Required
      Hide tasks attributes Show tasks attributes object
      • executing boolean Required

        Indicates whether the pending tasks are currently executing or not.

      • insert_order number Required

        The number that represents when the task has been inserted into the task queue.

      • priority string Required

        The priority of the pending task. The valid priorities in descending priority order are: IMMEDIATE > URGENT > HIGH > NORMAL > LOW > LANGUID.

      • source string Required

        A general description of the cluster task that may include a reason and origin.

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

      • Time unit for milliseconds

GET /_cluster/pending_tasks
curl \
 -X GET http://api.example.com/_cluster/pending_tasks
Response examples (200)
{
  "tasks": [
    {
      "executing": true,
      "insert_order": 42.0,
      "priority": "string",
      "source": "string",
      "time_in_queue": "string",
      "": 42.0
    }
  ]
}




Reroute the cluster Added in 5.0.0

POST /_cluster/reroute

Manually change the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.

It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as cluster.routing.rebalance.enable) in order to remain in a balanced state. For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.

The cluster can be set to disable allocations using the cluster.routing.allocation.enable setting. If allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.

The cluster will attempt to allocate a shard a maximum of index.allocation.max_retries times in a row (defaults to 5), before giving up and leaving the shard unallocated. This scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.

Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the ?retry_failed URI query parameter, which will attempt a single retry round for these shards.

Query parameters

  • dry_run boolean

    If true, then the request simulates the operation. It will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes.

  • explain boolean

    If true, then the response contains an explanation of why the commands can or cannot run.

  • metric string | array[string]

    Limits the information returned to the specified metrics.

  • If true, then retries allocation of shards that are blocked due to too many subsequent allocation failures.

  • 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

  • commands array[object]

    Defines the commands to perform.

    Hide commands attributes Show commands attributes object
    • cancel object

      Additional properties are allowed.

      Hide cancel attributes Show cancel attributes object
    • move object

      Additional properties are allowed.

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

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

      Hide allocate_stale_primary attributes Show allocate_stale_primary attributes object
      • index string Required
      • shard number Required
      • node string Required
      • accept_data_loss boolean Required

        If a node which has a copy of the data rejoins the cluster later on, that data will be deleted. To ensure that these implications are well-understood, this command requires the flag accept_data_loss to be explicitly set to true

    • Additional properties are allowed.

      Hide allocate_empty_primary attributes Show allocate_empty_primary attributes object
      • index string Required
      • shard number Required
      • node string Required
      • accept_data_loss boolean Required

        If a node which has a copy of the data rejoins the cluster later on, that data will be deleted. To ensure that these implications are well-understood, this command requires the flag accept_data_loss to be explicitly set to true

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • explanations array[object]
      Hide explanations attributes Show explanations attributes object
    • state object

      There aren't any guarantees on the output/structure of the raw cluster state. Here you will find the internal representation of the cluster, which can differ from the external representation.

      Additional properties are allowed.

POST /_cluster/reroute
curl \
 -X POST http://api.example.com/_cluster/reroute \
 -H "Content-Type: application/json" \
 -d '"{\n  \"commands\": [\n    {\n      \"move\": {\n        \"index\": \"test\", \"shard\": 0,\n        \"from_node\": \"node1\", \"to_node\": \"node2\"\n      }\n    },\n    {\n      \"allocate_replica\": {\n        \"index\": \"test\", \"shard\": 1,\n        \"node\": \"node3\"\n      }\n    }\n  ]\n}"'
Request example
Run `POST /_cluster/reroute?metric=none` to changes the allocation of shards in a cluster.
{
  "commands": [
    {
      "move": {
        "index": "test", "shard": 0,
        "from_node": "node1", "to_node": "node2"
      }
    },
    {
      "allocate_replica": {
        "index": "test", "shard": 1,
        "node": "node3"
      }
    }
  ]
}
Response examples (200)
{
  "acknowledged": true,
  "explanations": [
    {
      "command": "string",
      "decisions": [
        {
          "decider": "string",
          "decision": "string",
          "explanation": "string"
        }
      ],
      "parameters": {
        "allow_primary": true,
        "index": "string",
        "node": "string",
        "shard": 42.0,
        "from_node": "string",
        "to_node": "string"
      }
    }
  ],
  "state": {}
}








Get the cluster state Added in 1.3.0

GET /_cluster/state/{metric}/{index}

Get comprehensive information about the state of the cluster.

The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.

The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. You may need to consult the Elasticsearch source code to determine the precise meaning of the response.

By default the API will route requests to the elected master node since this node is the authoritative source of cluster states. You can also retrieve the cluster state held on the node handling the API request by adding the ?local=true query parameter.

Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. If you use this API repeatedly, your cluster may become unstable.

WARNING: The response is a representation of an internal data structure. Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. Do not query this API using external monitoring tools. Instead, obtain the information you require using other more stable cluster APIs.

Path parameters

  • metric string | array[string] Required

    Limit the information returned to the specified metrics

  • index string | array[string] Required

    A comma-separated list of index names; use _all or empty string to perform the operation on all indices

Query parameters

  • Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)

  • expand_wildcards string | array[string]

    Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • Return settings in flat format (default: false)

  • Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • local boolean

    Return local information, do not retrieve the state from master node (default: false)

  • Specify timeout for connection to master

  • Wait for the metadata version to be equal or greater than the specified metadata version

  • The maximum time to wait for wait_for_metadata_version before timing out

Responses

  • 200 application/json

    Additional properties are allowed.

GET /_cluster/state/{metric}/{index}
curl \
 -X GET http://api.example.com/_cluster/state/{metric}/{index}
Response examples (200)
{}












































Reload the keystore on nodes in the cluster Added in 6.5.0

POST /_nodes/reload_secure_settings

Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. That is, you can change them on disk and reload them without restarting any nodes in the cluster. When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.

When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted. Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.

Query parameters

  • 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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _nodes object

      Additional properties are allowed.

      Hide _nodes attributes Show _nodes attributes object
      • failures array[object]
        Hide failures attributes Show failures 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.

      • total number Required

        Total number of nodes selected by the request.

      • successful number Required

        Number of nodes that responded successfully to the request.

      • failed number Required

        Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.

    • cluster_name string Required
    • nodes object Required
POST /_nodes/reload_secure_settings
curl \
 -X POST http://api.example.com/_nodes/reload_secure_settings \
 -H "Content-Type: application/json" \
 -d '"{\n  \"secure_settings_password\": \"keystore-password\"\n}"'
Request example
Run `POST _nodes/reload_secure_settings` to reload the keystore on nodes in the cluster.
{
  "secure_settings_password": "keystore-password"
}
Response examples (200)
A successful response when reloading keystore on nodes in your cluster.
{
  "_nodes": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "cluster_name": "my_cluster",
  "nodes": {
    "pQHNt5rXTTWNvUgOrdynKg": {
      "name": "node-0"
    }
  }
}










































































































Set a connector sync job error Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_error

Set the error field for a connector sync job and set its status to error.

To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

Path parameters

application/json

Body Required

  • error string Required

    The error for the connector sync job error field.

Responses

  • 200 application/json

    Additional properties are allowed.

PUT /_connector/_sync_job/{connector_sync_job_id}/_error
curl \
 -X PUT http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_error \
 -H "Content-Type: application/json" \
 -d '{"error":"string"}'
Request examples
{
  "error": "string"
}
Response examples (200)
{}







































































































































































































































































































Get term vector information

GET /{index}/_termvectors

Get information and statistics about terms in the fields of a particular document.

Path parameters

  • index string Required

    Name of the index that contains the document.

Query parameters

  • fields string | array[string]

    Comma-separated list or wildcard expressions of fields to include in the statistics. Used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.

  • If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.

  • offsets boolean

    If true, the response includes term offsets.

  • payloads boolean

    If true, the response includes term payloads.

  • positions boolean

    If true, the response includes term positions.

  • Specifies the node or shard the operation should be performed on. Random by default.

  • realtime boolean

    If true, the request is real-time as opposed to near-real-time.

  • routing string

    Custom value used to route operations to a specific shard.

  • If true, the response includes term frequency and document frequency.

  • version number

    If true, returns the document version as part of a hit.

  • Specific version type.

    Values are internal, external, external_gte, or force.

application/json

Body

  • doc object

    An artificial document (a document not present in the index) for which you want to retrieve term vectors.

    Additional properties are allowed.

  • filter object

    Additional properties are allowed.

    Hide filter attributes Show filter attributes object
    • Ignore words which occur in more than this many docs. Defaults to unbounded.

    • Maximum number of terms that must be returned per field.

    • Ignore words with more than this frequency in the source doc. Defaults to unbounded.

    • The maximum word length above which words will be ignored. Defaults to unbounded.

    • Ignore terms which do not occur in at least this many docs.

    • Ignore words with less than this frequency in the source doc.

    • The minimum word length below which words will be ignored.

  • Overrides the default per-field analyzer.

    Hide per_field_analyzer attribute Show per_field_analyzer attribute object
    • * string Additional properties

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • found boolean Required
    • _id string
    • _index string Required
    • Hide term_vectors attribute Show term_vectors attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
    • took number Required
    • _version number Required
GET /{index}/_termvectors
curl \
 -X GET http://api.example.com/{index}/_termvectors \
 -H "Content-Type: application/json" \
 -d '{"doc":{},"filter":{"max_doc_freq":42.0,"max_num_terms":42.0,"max_term_freq":42.0,"max_word_length":42.0,"min_doc_freq":42.0,"min_term_freq":42.0,"min_word_length":42.0},"per_field_analyzer":{"additionalProperty1":"string","additionalProperty2":"string"}}'
Request examples
{
  "doc": {},
  "filter": {
    "max_doc_freq": 42.0,
    "max_num_terms": 42.0,
    "max_term_freq": 42.0,
    "max_word_length": 42.0,
    "min_doc_freq": 42.0,
    "min_term_freq": 42.0,
    "min_word_length": 42.0
  },
  "per_field_analyzer": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}
Response examples (200)
{
  "found": true,
  "_id": "string",
  "_index": "string",
  "term_vectors": {
    "additionalProperty1": {
      "field_statistics": {
        "doc_count": 42.0,
        "sum_doc_freq": 42.0,
        "sum_ttf": 42.0
      },
      "terms": {
        "additionalProperty1": {
          "doc_freq": 42.0,
          "score": 42.0,
          "term_freq": 42.0,
          "tokens": [
            {}
          ],
          "ttf": 42.0
        },
        "additionalProperty2": {
          "doc_freq": 42.0,
          "score": 42.0,
          "term_freq": 42.0,
          "tokens": [
            {}
          ],
          "ttf": 42.0
        }
      }
    },
    "additionalProperty2": {
      "field_statistics": {
        "doc_count": 42.0,
        "sum_doc_freq": 42.0,
        "sum_ttf": 42.0
      },
      "terms": {
        "additionalProperty1": {
          "doc_freq": 42.0,
          "score": 42.0,
          "term_freq": 42.0,
          "tokens": [
            {}
          ],
          "ttf": 42.0
        },
        "additionalProperty2": {
          "doc_freq": 42.0,
          "score": 42.0,
          "term_freq": 42.0,
          "tokens": [
            {}
          ],
          "ttf": 42.0
        }
      }
    }
  },
  "took": 42.0,
  "_version": 42.0
}
















































































Get the features Added in 7.12.0

GET /_features

Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot. You can use this API to determine which feature states to include when taking a snapshot. By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.

A feature state includes one or more system indices necessary for a given feature to function. In order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.

The features listed by this API are a combination of built-in features and features defined by plugins. In order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
GET /_features
curl \
 -X GET http://api.example.com/_features
Response examples (200)
A successful response for retrieving a list of feature states that can be included when taking a snapshot.
{
  "features": [
    {
      "name": "tasks",
      "description": "Manages task results"
    },
    {
      "name": "kibana",
      "description": "Manages Kibana configuration and reports"
    }
  ]
}









Executes several [fleet searches](https://www.elastic.co/guide/en/elasticsearch/reference/current/fleet-search.html) with a single API request Technical preview

GET /_fleet/_fleet_msearch

The API follows the same structure as the multi search API. However, similar to the fleet search API, it supports the wait_for_checkpoints parameter.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.

  • expand_wildcards string | array[string]

    Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

  • If true, concrete, expanded or aliased indices are ignored when frozen.

  • If true, missing or closed indices are not included in the response.

  • Maximum number of concurrent searches the multi search API can execute.

  • Maximum number of concurrent shard requests that each sub-search request executes per node.

  • Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.

  • Indicates whether global term and document frequencies should be used when scoring returned documents.

    Values are query_then_fetch or dfs_query_then_fetch.

  • If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.

  • typed_keys boolean

    Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.

  • A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.

  • If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results which is true by default.

application/json

Body object Required

One of:

Responses

GET /_fleet/_fleet_msearch
curl \
 -X GET http://api.example.com/_fleet/_fleet_msearch \
 -H "Content-Type: application/json" \
 -d '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'
Request examples
[
  {
    "allow_no_indices": true,
    "expand_wildcards": "string",
    "ignore_unavailable": true,
    "index": "string",
    "preference": "string",
    "request_cache": true,
    "routing": "string",
    "search_type": "query_then_fetch",
    "ccs_minimize_roundtrips": true,
    "allow_partial_search_results": true,
    "ignore_throttled": true
  }
]
Response examples (200)
{
  "docs": [
    {
      "took": 42.0,
      "timed_out": true,
      "_shards": {
        "failed": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "failures": [
          {}
        ],
        "skipped": 42.0
      },
      "hits": {
        "hits": [
          {}
        ]
      },
      "aggregations": {},
      "_clusters": {
        "skipped": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "running": 42.0,
        "partial": 42.0,
        "failed": 42.0,
        "details": {}
      },
      "fields": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "max_score": 42.0,
      "num_reduce_phases": 42.0,
      "profile": {
        "shards": [
          {}
        ]
      },
      "pit_id": "string",
      "_scroll_id": "string",
      "suggest": {
        "additionalProperty1": [
          {}
        ],
        "additionalProperty2": [
          {}
        ]
      },
      "terminated_early": true,
      "status": 42.0
    }
  ]
}








Executes several [fleet searches](https://www.elastic.co/guide/en/elasticsearch/reference/current/fleet-search.html) with a single API request Technical preview

POST /{index}/_fleet/_fleet_msearch

The API follows the same structure as the multi search API. However, similar to the fleet search API, it supports the wait_for_checkpoints parameter.

Path parameters

  • index string Required

    A single target to search. If the target is an index alias, it must resolve to a single index.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.

  • expand_wildcards string | array[string]

    Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

  • If true, concrete, expanded or aliased indices are ignored when frozen.

  • If true, missing or closed indices are not included in the response.

  • Maximum number of concurrent searches the multi search API can execute.

  • Maximum number of concurrent shard requests that each sub-search request executes per node.

  • Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.

  • Indicates whether global term and document frequencies should be used when scoring returned documents.

    Values are query_then_fetch or dfs_query_then_fetch.

  • If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.

  • typed_keys boolean

    Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.

  • A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.

  • If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results which is true by default.

application/json

Body object Required

One of:

Responses

POST /{index}/_fleet/_fleet_msearch
curl \
 -X POST http://api.example.com/{index}/_fleet/_fleet_msearch \
 -H "Content-Type: application/json" \
 -d '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'
Request examples
[
  {
    "allow_no_indices": true,
    "expand_wildcards": "string",
    "ignore_unavailable": true,
    "index": "string",
    "preference": "string",
    "request_cache": true,
    "routing": "string",
    "search_type": "query_then_fetch",
    "ccs_minimize_roundtrips": true,
    "allow_partial_search_results": true,
    "ignore_throttled": true
  }
]
Response examples (200)
{
  "docs": [
    {
      "took": 42.0,
      "timed_out": true,
      "_shards": {
        "failed": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "failures": [
          {}
        ],
        "skipped": 42.0
      },
      "hits": {
        "hits": [
          {}
        ]
      },
      "aggregations": {},
      "_clusters": {
        "skipped": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "running": 42.0,
        "partial": 42.0,
        "failed": 42.0,
        "details": {}
      },
      "fields": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "max_score": 42.0,
      "num_reduce_phases": 42.0,
      "profile": {
        "shards": [
          {}
        ]
      },
      "pit_id": "string",
      "_scroll_id": "string",
      "suggest": {
        "additionalProperty1": [
          {}
        ],
        "additionalProperty2": [
          {}
        ]
      },
      "terminated_early": true,
      "status": 42.0
    }
  ]
}









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
    }
  ]
}













































































Close an index

POST /{index}/_close

A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. Closed indices do not have to maintain internal data structures for indexing or searching documents, which results in a smaller overhead on the cluster.

When opening or closing an index, the master node is responsible for restarting the index shards to reflect the new state of the index. The shards will then go through the normal recovery process. The data of opened and closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.

You can open and close multiple indices. An error is thrown if the request explicitly refers to a missing index. This behaviour can be turned off using the ignore_unavailable=true parameter.

By default, you must explicitly name the indices you are opening or closing. To open or close indices with _all, *, or other wildcard expressions, change theaction.destructive_requires_name setting to false. This setting can also be changed with the cluster update settings API.

Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be turned off with the cluster settings API by setting cluster.indices.close.enable to false.

Path parameters

  • index string | array[string] Required

    Comma-separated list or wildcard expression of index names used to limit the request.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • If false, the request returns an error if it targets a missing or closed index.

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

  • wait_for_active_shards number | string

    The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • indices object Required
      Hide indices attribute Show indices attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • closed boolean Required
        • shards object
          Hide shards attribute Show shards attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attribute Show * attribute object
            • failures array[object] Required

              Additional properties are allowed.

    • shards_acknowledged boolean Required
POST /{index}/_close
curl \
 -X POST http://api.example.com/{index}/_close
Response examples (200)
A successful response for closing an index.
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "indices": {
    "my-index-000001": {
      "closed": true
    }
  }
}




Create an index

PUT /{index}

You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:

  • Settings for the index.
  • Mappings for fields in the index.
  • Index aliases

Wait for active shards

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out. The index creation response will indicate what happened. For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out. Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful. These values simply indicate whether the operation completed before the timeout. If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon. If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).

You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards. Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.

Path parameters

  • index string Required

    Name of the index you wish to create.

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.

  • wait_for_active_shards number | string

    The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

application/json

Body

  • aliases object

    Aliases for the index.

    Hide aliases attribute Show aliases attribute object
  • mappings object

    Additional properties are allowed.

    Hide mappings attributes Show mappings attributes object
  • settings object Additional properties

    Additional properties are allowed.

    Hide settings attributes Show settings attributes object
    • index object Additional properties

      Additional properties are allowed.

    • mode string
    • Additional properties are allowed.

      Hide soft_deletes attributes Show soft_deletes attributes object
      • enabled boolean

        Indicates whether soft deletes are enabled on the index.

      • Additional properties are allowed.

        Hide retention_lease attribute Show retention_lease attribute object
        • period 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.

    • sort object

      Additional properties are allowed.

      Hide sort attributes Show sort attributes object
    • Values are true, false, or checksum.

    • codec string
    • routing_partition_size number | string

      Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

      Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

    • merge object

      Additional properties are allowed.

      Hide merge attribute Show merge attribute object
    • 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.

    • blocks object

      Additional properties are allowed.

      Hide blocks attributes Show blocks attributes object
    • analyze object

      Additional properties are allowed.

      Hide analyze attribute Show analyze attribute object
    • Additional properties are allowed.

      Hide highlight attribute Show highlight attribute object
    • routing object

      Additional properties are allowed.

      Hide routing attributes Show routing attributes object
    • 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.

    • Additional properties are allowed.

      Hide lifecycle attributes Show lifecycle attributes object
      • name string
      • indexing_complete boolean | string

        Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

        Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

      • If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds.

      • Set to true to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern .*-{date_format}-\d+, where the date_format is yyyy.MM.dd and the trailing digits are optional. An index that was rolled over would normally match the full format, for example logs-2016.10.31-000002). If the index name doesn’t match the pattern, index creation fails.

      • step object

        Additional properties are allowed.

        Hide step attribute Show step attribute object
        • 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.

      • The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see Rollover.

    • creation_date number | string

      Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.

      Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.

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

    • uuid string
    • version object

      Additional properties are allowed.

      Hide version attributes Show version attributes object
    • translog object

      Additional properties are allowed.

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

      Hide query_string attribute Show query_string attribute object
    • analysis object

      Additional properties are allowed.

      Hide analysis attributes Show analysis attributes object
    • settings object Additional properties

      Additional properties are allowed.

    • Additional properties are allowed.

      Hide time_series attributes Show time_series attributes object
    • queries object

      Additional properties are allowed.

      Hide queries attribute Show queries attribute object
      • cache object

        Additional properties are allowed.

        Hide cache attribute Show cache attribute object
    • Configure custom similarity settings to customize how search results are scored.

    • mapping object

      Additional properties are allowed.

      Hide mapping attributes Show mapping attributes object
      • coerce boolean
      • Additional properties are allowed.

        Hide total_fields attributes Show total_fields attributes object
        • limit number | string

          The maximum number of fields in an index. Field and object mappings, as well as field aliases count towards this limit. The limit is in place to prevent mappings and searches from becoming too large. Higher values can lead to performance degradations and memory issues, especially in clusters with a high load or few resources.

        • ignore_dynamic_beyond_limit boolean | string

          This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Limit of total fields [X] has been exceeded. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field.

      • depth object

        Additional properties are allowed.

        Hide depth attribute Show depth attribute object
        • limit number

          The maximum depth for a field, which is measured as the number of inner objects. For instance, if all fields are defined at the root object level, then the depth is 1. If there is one object mapping, then the depth is 2, etc.

      • Additional properties are allowed.

        Hide nested_fields attribute Show nested_fields attribute object
        • limit number

          The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index.

      • Additional properties are allowed.

        Hide nested_objects attribute Show nested_objects attribute object
        • limit number

          The maximum number of nested JSON objects that a single document can contain across all nested types. This limit helps to prevent out of memory errors when a document contains too many nested objects.

      • Additional properties are allowed.

        Hide field_name_length attribute Show field_name_length attribute object
        • limit number

          Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is Long.MAX_VALUE (no limit).

      • Additional properties are allowed.

        Hide dimension_fields attribute Show dimension_fields attribute object
        • limit number

          [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

    • Additional properties are allowed.

      Hide indexing.slowlog attributes Show indexing.slowlog attributes object
      • level string
      • source number
      • reformat boolean
      • Additional properties are allowed.

        Hide threshold attribute Show threshold attribute object
        • index object

          Additional properties are allowed.

          Hide index attributes Show index attributes object
          • warn 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.

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

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

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

    • Additional properties are allowed.

      Hide indexing_pressure attribute Show indexing_pressure attribute object
      • memory object Required

        Additional properties are allowed.

        Hide memory attribute Show memory attribute object
        • limit number

          Number of outstanding bytes that may be consumed by indexing requests. When this limit is reached or exceeded, the node will reject new coordinating and primary operations. When replica operations consume 1.5x this limit, the node will reject new replica operations. Defaults to 10% of the heap.

    • store object

      Additional properties are allowed.

      Hide store attributes Show store attributes object
      • type string Required

      • allow_mmap boolean

        You can restrict the use of the mmapfs and the related hybridfs store type via the setting node.store.allow_mmap. This is a boolean setting indicating whether or not memory-mapping is allowed. The default is to allow it. This setting is useful, for example, if you are in an environment where you can not control the ability to create a lot of memory maps so you need disable the ability to use memory-mapping.

Responses

PUT /{index}
curl \
 -X PUT http://api.example.com/{index} \
 -H "Content-Type: application/json" \
 -d '"{\n  \"settings\": {\n    \"number_of_shards\": 3,\n    \"number_of_replicas\": 2\n  }\n}"'
This request specifies the `number_of_shards` and `number_of_replicas`.
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}
You can provide mapping definitions in the create index API requests.
{
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "field1": { "type": "text" }
    }
  }
}
Response examples (200)
{
  "index": "string",
  "shards_acknowledged": true,
  "acknowledged": true
}

Delete indices

DELETE /{index}

Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.

You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. You can then use the delete index API to delete the previous write index.

Path parameters

  • index string | array[string] Required

    Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (*) or _all. To use wildcards or _all, set the action.destructive_requires_name cluster setting to false.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • If false, the request returns an error if it targets a missing or closed index.

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

Responses

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

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

    • _shards object

      Additional properties are allowed.

      Hide _shards attributes Show _shards attributes object
DELETE /{index}
curl \
 -X DELETE http://api.example.com/{index}
Response examples (200)
{
  "acknowledged": true,
  "_shards": {
    "failed": 42.0,
    "successful": 42.0,
    "total": 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"
      }
    ],
    "skipped": 42.0
  }
}




Get aliases

GET /{index}/_alias/{name}

Retrieves information for one or more data stream or index aliases.

Path parameters

  • index string | array[string] Required

    Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

  • name string | array[string] Required

    Comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • If false, the request returns an error if it targets a missing or closed index.

  • local boolean Deprecated

    If true, the request retrieves information from the local node only.

Responses

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

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • aliases object Required
        Hide aliases attribute Show aliases attribute object
        • * object Additional properties

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • filter object

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

            Additional properties are allowed.

          • Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.

          • If true, the index is the write index for the alias.

          • routing string

            Value used to route indexing and search operations to a specific shard.

          • Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.

          • is_hidden boolean

            If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

GET /{index}/_alias/{name}
curl \
 -X GET http://api.example.com/{index}/_alias/{name}
Response examples (200)
{
  "additionalProperty1": {
    "aliases": {
      "additionalProperty1": {
        "filter": {},
        "index_routing": "string",
        "is_write_index": true,
        "routing": "string",
        "search_routing": "string",
        "is_hidden": true
      },
      "additionalProperty2": {
        "filter": {},
        "index_routing": "string",
        "is_write_index": true,
        "routing": "string",
        "search_routing": "string",
        "is_hidden": true
      }
    }
  },
  "additionalProperty2": {
    "aliases": {
      "additionalProperty1": {
        "filter": {},
        "index_routing": "string",
        "is_write_index": true,
        "routing": "string",
        "search_routing": "string",
        "is_hidden": true
      },
      "additionalProperty2": {
        "filter": {},
        "index_routing": "string",
        "is_write_index": true,
        "routing": "string",
        "search_routing": "string",
        "is_hidden": true
      }
    }
  }
}
































































































































































































Refresh an index

POST /_refresh

A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.

By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. You can change this default interval with the index.refresh_interval setting.

Refresh requests are synchronous and do not return a response until the refresh operation completes.

Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option. This option ensures the indexing operation waits for a periodic refresh before running the search.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • If false, the request returns an error if it targets a missing or closed index.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • _shards object

      Additional properties are allowed.

      Hide _shards attributes Show _shards attributes object
      • failed number Required
      • successful number Required
      • total number Required
      • failures array[object]
        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
      • skipped number
POST /_refresh
curl \
 -X POST http://api.example.com/_refresh
Response examples (200)
{
  "_shards": {
    "failed": 42.0,
    "successful": 42.0,
    "total": 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"
      }
    ],
    "skipped": 42.0
  }
}
































































































































































































































Get GeoIP database configurations Added in 8.15.0

GET /_ingest/geoip/database/{id}

Get information about one or more IP geolocation database configurations.

Path parameters

  • id string | array[string] Required

    Comma-separated list of database configuration IDs to retrieve. Wildcard (*) expressions are supported. To get all database configurations, omit this parameter or use *.

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.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • databases array[object] Required
      Hide databases attributes Show databases attributes object
      • id string Required
      • version number Required
      • Time unit for milliseconds

      • database object

        The configuration necessary to identify which IP geolocation provider to use to download a database, as well as any provider-specific configuration necessary for such downloading. At present, the only supported providers are maxmind and ipinfo, and the maxmind provider requires that an account_id (string) is configured. A provider (either maxmind or ipinfo) must be specified. The web and local providers can be returned as read only configurations.

        Additional properties are allowed.

        Hide database attributes Show database attributes object
        • name string Required
        • maxmind object

          Additional properties are allowed.

          Hide maxmind attribute Show maxmind attribute object
        • ipinfo object

          Additional properties are allowed.

GET /_ingest/geoip/database/{id}
curl \
 -X GET http://api.example.com/_ingest/geoip/database/{id}
Response examples (200)
{
  "databases": [
    {
      "id": "string",
      "version": 42.0,
      "": {
        "name": "string",
        "maxmind": {
          "account_id": "string"
        },
        "ipinfo": {}
      }
    }
  ]
}




























































































































































Get calendar configuration info Added in 6.2.0

GET /_ml/calendars/{calendar_id}

Path parameters

  • calendar_id string Required

    A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using _all or * or by omitting the calendar identifier.

Query parameters

  • from number

    Skips the specified number of calendars. This parameter is supported only when you omit the calendar identifier.

  • size number

    Specifies the maximum number of calendars to obtain. This parameter is supported only when you omit the calendar identifier.

application/json

Body

  • page object

    Additional properties are allowed.

    Hide page attributes Show page attributes object
    • from number

      Skips the specified number of items.

    • size number

      Specifies the maximum number of items to obtain.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • calendars array[object] Required
      Hide calendars attributes Show calendars attributes object
    • count number Required
GET /_ml/calendars/{calendar_id}
curl \
 -X GET http://api.example.com/_ml/calendars/{calendar_id} \
 -H "Content-Type: application/json" \
 -d '{"page":{"from":42.0,"size":42.0}}'
Request examples
{
  "page": {
    "from": 42.0,
    "size": 42.0
  }
}
Response examples (200)
{
  "calendars": [
    {
      "calendar_id": "string",
      "description": "string",
      "job_ids": [
        "string"
      ]
    }
  ],
  "count": 42.0
}









































































































































































































































































































Explain data frame analytics config Added in 7.3.0

GET /_ml/data_frame/analytics/_explain

This API provides explanations for a data frame analytics config that either exists already or one that has not been created yet. The following explanations are provided:

  • which fields are included or not in the analysis and why,
  • how much memory is estimated to be required. The estimate can be used when deciding the appropriate value for model_memory_limit setting later on. If you have object fields or fields that are excluded via source filtering, they are not included in the explanation.
application/json

Body

  • source object

    Additional properties are allowed.

    Hide source attributes Show source attributes object
    • index string | array[string] Required
    • Hide runtime_mappings attribute Show runtime_mappings attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • fields object

          For type composite

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

            Additional properties are allowed.

            Hide * attribute Show * attribute object
            • type string Required

              Values are boolean, composite, date, double, geo_point, ip, keyword, long, or lookup.

        • fetch_fields array[object]

          For type lookup

          Hide fetch_fields attributes Show fetch_fields attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • format string
        • format string

          A custom format for date type runtime fields.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • source string

            The script source.

          • id string
          • params object

            Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

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

              Additional properties are allowed.

          • lang string

            Any of:

            Values are painless, expression, mustache, or java.

          • options object
            Hide options attribute Show options attribute object
            • * string Additional properties
        • type string Required

          Values are boolean, composite, date, double, geo_point, ip, keyword, long, or lookup.

    • _source object

      Additional properties are allowed.

      Hide _source attributes Show _source attributes object
      • includes array[string] Required

        An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.

      • excludes array[string] Required

        An array of strings that defines the fields that will be included in the analysis.

    • query object

      The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.

      Additional properties are allowed.

  • dest object

    Additional properties are allowed.

    Hide dest attributes Show dest attributes object
    • index string Required
    • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • analysis object

    Additional properties are allowed.

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

      Hide classification attributes Show classification attributes object
      • alpha number

        Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.

      • dependent_variable string Required

        Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.

      • Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.

      • Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.

      • eta number

        Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.

      • Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.

      • Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.

      • feature_processors array[object]

        Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.

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

          Hide frequency_encoding attributes Show frequency_encoding attributes object
          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • frequency_map object Required

            The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.

        • Additional properties are allowed.

          Hide multi_encoding attribute Show multi_encoding attribute object
          • processors array[number] Required

            The ordered array of custom processors to execute. Must be more than 1.

        • Additional properties are allowed.

          Hide n_gram_encoding attributes Show n_gram_encoding attributes object
          • The feature name prefix. Defaults to ngram__.

          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • length number

            Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.

          • n_grams array[number] Required

            Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.

          • start number

            Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.

          • custom boolean
        • Additional properties are allowed.

          Hide one_hot_encoding attributes Show one_hot_encoding attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • hot_map string Required

            The one hot map mapping the field value with the column name.

        • Additional properties are allowed.

          Hide target_mean_encoding attributes Show target_mean_encoding attributes object
          • default_value number Required

            The default value if field value is not found in the target_map.

          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • target_map object Required

            The field value to target mean transition map.

      • gamma number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • lambda number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.

      • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).

      • Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.

      • Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.

      • Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.

    • Additional properties are allowed.

      Hide outlier_detection attributes Show outlier_detection attributes object
      • Specifies whether the feature influence calculation is enabled.

      • The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.

      • method string

        The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.

      • Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.

      • The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.

      • If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).

    • Additional properties are allowed.

      Hide regression attributes Show regression attributes object
      • alpha number

        Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.

      • dependent_variable string Required

        Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.

      • Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.

      • Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.

      • eta number

        Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.

      • Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.

      • Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.

      • feature_processors array[object]

        Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.

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

          Hide frequency_encoding attributes Show frequency_encoding attributes object
          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • frequency_map object Required

            The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.

        • Additional properties are allowed.

          Hide multi_encoding attribute Show multi_encoding attribute object
          • processors array[number] Required

            The ordered array of custom processors to execute. Must be more than 1.

        • Additional properties are allowed.

          Hide n_gram_encoding attributes Show n_gram_encoding attributes object
          • The feature name prefix. Defaults to ngram__.

          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • length number

            Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.

          • n_grams array[number] Required

            Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.

          • start number

            Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.

          • custom boolean
        • Additional properties are allowed.

          Hide one_hot_encoding attributes Show one_hot_encoding attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • hot_map string Required

            The one hot map mapping the field value with the column name.

        • Additional properties are allowed.

          Hide target_mean_encoding attributes Show target_mean_encoding attributes object
          • default_value number Required

            The default value if field value is not found in the target_map.

          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • target_map object Required

            The field value to target mean transition map.

      • gamma number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • lambda number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.

      • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).

      • Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.

      • Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.

      • The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).

      • A positive number that is used as a parameter to the loss_function.

  • A description of the job.

  • The approximate maximum amount of memory resources that are permitted for analytical processing. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting.

  • The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.

  • Additional properties are allowed.

    Hide analyzed_fields attributes Show analyzed_fields attributes object
    • includes array[string] Required

      An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.

    • excludes array[string] Required

      An array of strings that defines the fields that will be included in the analysis.

  • Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • field_selection array[object] Required

      An array of objects that explain selection for each field, sorted by the field names.

      Hide field_selection attributes Show field_selection attributes object
      • is_included boolean Required

        Whether the field is selected to be included in the analysis.

      • is_required boolean Required

        Whether the field is required.

      • The feature type of this field for the analysis. May be categorical or numerical.

      • mapping_types array[string] Required

        The mapping types of the field.

      • name string Required

        Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • reason string

        The reason a field is not selected to be included in the analysis.

    • memory_estimation object Required

      Additional properties are allowed.

      Hide memory_estimation attributes Show memory_estimation attributes object
      • Estimated memory usage under the assumption that overflowing to disk is allowed during data frame analytics. expected_memory_with_disk is usually smaller than expected_memory_without_disk as using disk allows to limit the main memory needed to perform data frame analytics.

      • Estimated memory usage under the assumption that the whole data frame analytics should happen in memory (i.e. without overflowing to disk).

GET /_ml/data_frame/analytics/_explain
curl \
 -X GET http://api.example.com/_ml/data_frame/analytics/_explain \
 -H "Content-Type: application/json" \
 -d '{"source":{"index":"string","runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"_source":{"includes":["string"],"excludes":["string"]},"query":{}},"dest":{"index":"string","results_field":"string"},"analysis":{"":{"alpha":42.0,"dependent_variable":"string","downsample_factor":42.0,"early_stopping_enabled":true,"eta":42.0,"eta_growth_rate_per_tree":42.0,"feature_bag_fraction":42.0,"feature_processors":[{"frequency_encoding":{"feature_name":"string","field":"string","frequency_map":{}},"multi_encoding":{"processors":[42.0]},"n_gram_encoding":{"feature_prefix":"string","field":"string","length":42.0,"n_grams":[42.0],"start":42.0,"custom":true},"one_hot_encoding":{"field":"string","hot_map":"string"},"target_mean_encoding":{"default_value":42.0,"feature_name":"string","field":"string","target_map":{}}}],"gamma":42.0,"lambda":42.0,"max_optimization_rounds_per_hyperparameter":42.0,"max_trees":42.0,"num_top_feature_importance_values":42.0,"prediction_field_name":"string","randomize_seed":42.0,"soft_tree_depth_limit":42.0,"soft_tree_depth_tolerance":42.0,"":"string","loss_function":"string","loss_function_parameter":42.0},"outlier_detection":{"compute_feature_influence":true,"feature_influence_threshold":42.0,"method":"string","n_neighbors":42.0,"outlier_fraction":42.0,"standardization_enabled":true}},"description":"string","model_memory_limit":"string","max_num_threads":42.0,"analyzed_fields":{"includes":["string"],"excludes":["string"]},"allow_lazy_start":true}'
Request examples
{
  "source": {
    "index": "string",
    "runtime_mappings": {
      "additionalProperty1": {
        "fields": {
          "additionalProperty1": {
            "type": "boolean"
          },
          "additionalProperty2": {
            "type": "boolean"
          }
        },
        "fetch_fields": [
          {
            "field": "string",
            "format": "string"
          }
        ],
        "format": "string",
        "input_field": "string",
        "target_field": "string",
        "target_index": "string",
        "script": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        },
        "type": "boolean"
      },
      "additionalProperty2": {
        "fields": {
          "additionalProperty1": {
            "type": "boolean"
          },
          "additionalProperty2": {
            "type": "boolean"
          }
        },
        "fetch_fields": [
          {
            "field": "string",
            "format": "string"
          }
        ],
        "format": "string",
        "input_field": "string",
        "target_field": "string",
        "target_index": "string",
        "script": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        },
        "type": "boolean"
      }
    },
    "_source": {
      "includes": [
        "string"
      ],
      "excludes": [
        "string"
      ]
    },
    "query": {}
  },
  "dest": {
    "index": "string",
    "results_field": "string"
  },
  "analysis": {
    "": {
      "alpha": 42.0,
      "dependent_variable": "string",
      "downsample_factor": 42.0,
      "early_stopping_enabled": true,
      "eta": 42.0,
      "eta_growth_rate_per_tree": 42.0,
      "feature_bag_fraction": 42.0,
      "feature_processors": [
        {
          "frequency_encoding": {
            "feature_name": "string",
            "field": "string",
            "frequency_map": {}
          },
          "multi_encoding": {
            "processors": [
              42.0
            ]
          },
          "n_gram_encoding": {
            "feature_prefix": "string",
            "field": "string",
            "length": 42.0,
            "n_grams": [
              42.0
            ],
            "start": 42.0,
            "custom": true
          },
          "one_hot_encoding": {
            "field": "string",
            "hot_map": "string"
          },
          "target_mean_encoding": {
            "default_value": 42.0,
            "feature_name": "string",
            "field": "string",
            "target_map": {}
          }
        }
      ],
      "gamma": 42.0,
      "lambda": 42.0,
      "max_optimization_rounds_per_hyperparameter": 42.0,
      "max_trees": 42.0,
      "num_top_feature_importance_values": 42.0,
      "prediction_field_name": "string",
      "randomize_seed": 42.0,
      "soft_tree_depth_limit": 42.0,
      "soft_tree_depth_tolerance": 42.0,
      "": "string",
      "loss_function": "string",
      "loss_function_parameter": 42.0
    },
    "outlier_detection": {
      "compute_feature_influence": true,
      "feature_influence_threshold": 42.0,
      "method": "string",
      "n_neighbors": 42.0,
      "outlier_fraction": 42.0,
      "standardization_enabled": true
    }
  },
  "description": "string",
  "model_memory_limit": "string",
  "max_num_threads": 42.0,
  "analyzed_fields": {
    "includes": [
      "string"
    ],
    "excludes": [
      "string"
    ]
  },
  "allow_lazy_start": true
}
Response examples (200)
{
  "field_selection": [
    {
      "is_included": true,
      "is_required": true,
      "feature_type": "string",
      "mapping_types": [
        "string"
      ],
      "name": "string",
      "reason": "string"
    }
  ],
  "memory_estimation": {
    "expected_memory_with_disk": "string",
    "expected_memory_without_disk": "string"
  }
}

Explain data frame analytics config Added in 7.3.0

POST /_ml/data_frame/analytics/_explain

This API provides explanations for a data frame analytics config that either exists already or one that has not been created yet. The following explanations are provided:

  • which fields are included or not in the analysis and why,
  • how much memory is estimated to be required. The estimate can be used when deciding the appropriate value for model_memory_limit setting later on. If you have object fields or fields that are excluded via source filtering, they are not included in the explanation.
application/json

Body

  • source object

    Additional properties are allowed.

    Hide source attributes Show source attributes object
    • index string | array[string] Required
    • Hide runtime_mappings attribute Show runtime_mappings attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • fields object

          For type composite

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

            Additional properties are allowed.

            Hide * attribute Show * attribute object
            • type string Required

              Values are boolean, composite, date, double, geo_point, ip, keyword, long, or lookup.

        • fetch_fields array[object]

          For type lookup

          Hide fetch_fields attributes Show fetch_fields attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • format string
        • format string

          A custom format for date type runtime fields.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • script object

          Additional properties are allowed.

          Hide script attributes Show script attributes object
          • source string

            The script source.

          • id string
          • params object

            Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

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

              Additional properties are allowed.

          • lang string

            Any of:

            Values are painless, expression, mustache, or java.

          • options object
            Hide options attribute Show options attribute object
            • * string Additional properties
        • type string Required

          Values are boolean, composite, date, double, geo_point, ip, keyword, long, or lookup.

    • _source object

      Additional properties are allowed.

      Hide _source attributes Show _source attributes object
      • includes array[string] Required

        An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.

      • excludes array[string] Required

        An array of strings that defines the fields that will be included in the analysis.

    • query object

      The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.

      Additional properties are allowed.

  • dest object

    Additional properties are allowed.

    Hide dest attributes Show dest attributes object
    • index string Required
    • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • analysis object

    Additional properties are allowed.

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

      Hide classification attributes Show classification attributes object
      • alpha number

        Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.

      • dependent_variable string Required

        Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.

      • Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.

      • Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.

      • eta number

        Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.

      • Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.

      • Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.

      • feature_processors array[object]

        Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.

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

          Hide frequency_encoding attributes Show frequency_encoding attributes object
          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • frequency_map object Required

            The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.

        • Additional properties are allowed.

          Hide multi_encoding attribute Show multi_encoding attribute object
          • processors array[number] Required

            The ordered array of custom processors to execute. Must be more than 1.

        • Additional properties are allowed.

          Hide n_gram_encoding attributes Show n_gram_encoding attributes object
          • The feature name prefix. Defaults to ngram__.

          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • length number

            Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.

          • n_grams array[number] Required

            Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.

          • start number

            Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.

          • custom boolean
        • Additional properties are allowed.

          Hide one_hot_encoding attributes Show one_hot_encoding attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • hot_map string Required

            The one hot map mapping the field value with the column name.

        • Additional properties are allowed.

          Hide target_mean_encoding attributes Show target_mean_encoding attributes object
          • default_value number Required

            The default value if field value is not found in the target_map.

          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • target_map object Required

            The field value to target mean transition map.

      • gamma number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • lambda number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.

      • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).

      • Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.

      • Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.

      • Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.

    • Additional properties are allowed.

      Hide outlier_detection attributes Show outlier_detection attributes object
      • Specifies whether the feature influence calculation is enabled.

      • The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.

      • method string

        The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.

      • Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.

      • The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.

      • If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).

    • Additional properties are allowed.

      Hide regression attributes Show regression attributes object
      • alpha number

        Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.

      • dependent_variable string Required

        Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.

      • Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.

      • Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.

      • eta number

        Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.

      • Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.

      • Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.

      • feature_processors array[object]

        Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.

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

          Hide frequency_encoding attributes Show frequency_encoding attributes object
          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • frequency_map object Required

            The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.

        • Additional properties are allowed.

          Hide multi_encoding attribute Show multi_encoding attribute object
          • processors array[number] Required

            The ordered array of custom processors to execute. Must be more than 1.

        • Additional properties are allowed.

          Hide n_gram_encoding attributes Show n_gram_encoding attributes object
          • The feature name prefix. Defaults to ngram__.

          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • length number

            Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.

          • n_grams array[number] Required

            Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.

          • start number

            Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.

          • custom boolean
        • Additional properties are allowed.

          Hide one_hot_encoding attributes Show one_hot_encoding attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • hot_map string Required

            The one hot map mapping the field value with the column name.

        • Additional properties are allowed.

          Hide target_mean_encoding attributes Show target_mean_encoding attributes object
          • default_value number Required

            The default value if field value is not found in the target_map.

          • feature_name string Required
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • target_map object Required

            The field value to target mean transition map.

      • gamma number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • lambda number

        Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.

      • Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.

      • Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.

      • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).

      • Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.

      • Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.

      • The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).

      • A positive number that is used as a parameter to the loss_function.

  • A description of the job.

  • The approximate maximum amount of memory resources that are permitted for analytical processing. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting.

  • The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.

  • Additional properties are allowed.

    Hide analyzed_fields attributes Show analyzed_fields attributes object
    • includes array[string] Required

      An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.

    • excludes array[string] Required

      An array of strings that defines the fields that will be included in the analysis.

  • Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • field_selection array[object] Required

      An array of objects that explain selection for each field, sorted by the field names.

      Hide field_selection attributes Show field_selection attributes object
      • is_included boolean Required

        Whether the field is selected to be included in the analysis.

      • is_required boolean Required

        Whether the field is required.

      • The feature type of this field for the analysis. May be categorical or numerical.

      • mapping_types array[string] Required

        The mapping types of the field.

      • name string Required

        Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • reason string

        The reason a field is not selected to be included in the analysis.

    • memory_estimation object Required

      Additional properties are allowed.

      Hide memory_estimation attributes Show memory_estimation attributes object
      • Estimated memory usage under the assumption that overflowing to disk is allowed during data frame analytics. expected_memory_with_disk is usually smaller than expected_memory_without_disk as using disk allows to limit the main memory needed to perform data frame analytics.

      • Estimated memory usage under the assumption that the whole data frame analytics should happen in memory (i.e. without overflowing to disk).

POST /_ml/data_frame/analytics/_explain
curl \
 -X POST http://api.example.com/_ml/data_frame/analytics/_explain \
 -H "Content-Type: application/json" \
 -d '{"source":{"index":"string","runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"_source":{"includes":["string"],"excludes":["string"]},"query":{}},"dest":{"index":"string","results_field":"string"},"analysis":{"":{"alpha":42.0,"dependent_variable":"string","downsample_factor":42.0,"early_stopping_enabled":true,"eta":42.0,"eta_growth_rate_per_tree":42.0,"feature_bag_fraction":42.0,"feature_processors":[{"frequency_encoding":{"feature_name":"string","field":"string","frequency_map":{}},"multi_encoding":{"processors":[42.0]},"n_gram_encoding":{"feature_prefix":"string","field":"string","length":42.0,"n_grams":[42.0],"start":42.0,"custom":true},"one_hot_encoding":{"field":"string","hot_map":"string"},"target_mean_encoding":{"default_value":42.0,"feature_name":"string","field":"string","target_map":{}}}],"gamma":42.0,"lambda":42.0,"max_optimization_rounds_per_hyperparameter":42.0,"max_trees":42.0,"num_top_feature_importance_values":42.0,"prediction_field_name":"string","randomize_seed":42.0,"soft_tree_depth_limit":42.0,"soft_tree_depth_tolerance":42.0,"":"string","loss_function":"string","loss_function_parameter":42.0},"outlier_detection":{"compute_feature_influence":true,"feature_influence_threshold":42.0,"method":"string","n_neighbors":42.0,"outlier_fraction":42.0,"standardization_enabled":true}},"description":"string","model_memory_limit":"string","max_num_threads":42.0,"analyzed_fields":{"includes":["string"],"excludes":["string"]},"allow_lazy_start":true}'
Request examples
{
  "source": {
    "index": "string",
    "runtime_mappings": {
      "additionalProperty1": {
        "fields": {
          "additionalProperty1": {
            "type": "boolean"
          },
          "additionalProperty2": {
            "type": "boolean"
          }
        },
        "fetch_fields": [
          {
            "field": "string",
            "format": "string"
          }
        ],
        "format": "string",
        "input_field": "string",
        "target_field": "string",
        "target_index": "string",
        "script": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        },
        "type": "boolean"
      },
      "additionalProperty2": {
        "fields": {
          "additionalProperty1": {
            "type": "boolean"
          },
          "additionalProperty2": {
            "type": "boolean"
          }
        },
        "fetch_fields": [
          {
            "field": "string",
            "format": "string"
          }
        ],
        "format": "string",
        "input_field": "string",
        "target_field": "string",
        "target_index": "string",
        "script": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        },
        "type": "boolean"
      }
    },
    "_source": {
      "includes": [
        "string"
      ],
      "excludes": [
        "string"
      ]
    },
    "query": {}
  },
  "dest": {
    "index": "string",
    "results_field": "string"
  },
  "analysis": {
    "": {
      "alpha": 42.0,
      "dependent_variable": "string",
      "downsample_factor": 42.0,
      "early_stopping_enabled": true,
      "eta": 42.0,
      "eta_growth_rate_per_tree": 42.0,
      "feature_bag_fraction": 42.0,
      "feature_processors": [
        {
          "frequency_encoding": {
            "feature_name": "string",
            "field": "string",
            "frequency_map": {}
          },
          "multi_encoding": {
            "processors": [
              42.0
            ]
          },
          "n_gram_encoding": {
            "feature_prefix": "string",
            "field": "string",
            "length": 42.0,
            "n_grams": [
              42.0
            ],
            "start": 42.0,
            "custom": true
          },
          "one_hot_encoding": {
            "field": "string",
            "hot_map": "string"
          },
          "target_mean_encoding": {
            "default_value": 42.0,
            "feature_name": "string",
            "field": "string",
            "target_map": {}
          }
        }
      ],
      "gamma": 42.0,
      "lambda": 42.0,
      "max_optimization_rounds_per_hyperparameter": 42.0,
      "max_trees": 42.0,
      "num_top_feature_importance_values": 42.0,
      "prediction_field_name": "string",
      "randomize_seed": 42.0,
      "soft_tree_depth_limit": 42.0,
      "soft_tree_depth_tolerance": 42.0,
      "": "string",
      "loss_function": "string",
      "loss_function_parameter": 42.0
    },
    "outlier_detection": {
      "compute_feature_influence": true,
      "feature_influence_threshold": 42.0,
      "method": "string",
      "n_neighbors": 42.0,
      "outlier_fraction": 42.0,
      "standardization_enabled": true
    }
  },
  "description": "string",
  "model_memory_limit": "string",
  "max_num_threads": 42.0,
  "analyzed_fields": {
    "includes": [
      "string"
    ],
    "excludes": [
      "string"
    ]
  },
  "allow_lazy_start": true
}
Response examples (200)
{
  "field_selection": [
    {
      "is_included": true,
      "is_required": true,
      "feature_type": "string",
      "mapping_types": [
        "string"
      ],
      "name": "string",
      "reason": "string"
    }
  ],
  "memory_estimation": {
    "expected_memory_with_disk": "string",
    "expected_memory_without_disk": "string"
  }
}
































































































































































Get the shutdown status Added in 7.13.0

GET /_nodes/shutdown

Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled. The API returns status information for each part of the shut down process.

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

If the operator privileges feature is enabled, you must be an operator to use this API.

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.

    Values are nanos, micros, ms, s, m, h, or d.

  • timeout string

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

    Values are nanos, micros, ms, s, m, h, or d.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • nodes array[object] Required
      Hide nodes attributes Show nodes attributes object
      • node_id string Required
      • type string Required

        Values are remove or restart.

      • reason string Required
      • Time unit for milliseconds

      • status string Required

        Values are not_started, in_progress, stalled, or complete.

      • shard_migration object Required

        Additional properties are allowed.

        Hide shard_migration attribute Show shard_migration attribute object
        • status string Required

          Values are not_started, in_progress, stalled, or complete.

      • persistent_tasks object Required

        Additional properties are allowed.

        Hide persistent_tasks attribute Show persistent_tasks attribute object
        • status string Required

          Values are not_started, in_progress, stalled, or complete.

      • plugins object Required

        Additional properties are allowed.

        Hide plugins attribute Show plugins attribute object
        • status string Required

          Values are not_started, in_progress, stalled, or complete.

GET /_nodes/shutdown
curl \
 -X GET http://api.example.com/_nodes/shutdown
Response examples (200)
{
  "nodes": [
    {
      "node_id": "string",
      "type": "remove",
      "reason": "string",
      "": 42.0,
      "status": "not_started",
      "shard_migration": {
        "status": "not_started"
      },
      "persistent_tasks": {
        "status": "not_started"
      },
      "plugins": {
        "status": "not_started"
      }
    }
  ]
}


























































Get the rollup index capabilities Deprecated Technical preview

GET /{index}/_rollup/data

Get the rollup capabilities of all jobs inside of a rollup index. A single rollup index may store the data for multiple rollup jobs and may have a variety of capabilities depending on those jobs. This API enables you to determine:

  • What jobs are stored in an index (or indices specified via a pattern)?
  • What target indices were rolled up, what fields were used in those rollups, and what aggregations can be performed on each job?

Path parameters

  • index string | array[string] Required

    Data stream or index to check for rollup capabilities. Wildcard (*) expressions are supported.

Responses

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

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • rollup_jobs array[object] Required
        Hide rollup_jobs attributes Show rollup_jobs attributes object
GET /{index}/_rollup/data
curl \
 -X GET http://api.example.com/{index}/_rollup/data
Response examples (200)
{
  "additionalProperty1": {
    "rollup_jobs": [
      {
        "fields": {
          "additionalProperty1": [
            {}
          ],
          "additionalProperty2": [
            {}
          ]
        },
        "index_pattern": "string",
        "job_id": "string",
        "rollup_index": "string"
      }
    ]
  },
  "additionalProperty2": {
    "rollup_jobs": [
      {
        "fields": {
          "additionalProperty1": [
            {}
          ],
          "additionalProperty2": [
            {}
          ]
        },
        "index_pattern": "string",
        "job_id": "string",
        "rollup_index": "string"
      }
    ]
  }
}

































Get script contexts

GET /_script_context

Get a list of supported script contexts and their methods.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • contexts array[object] Required
      Hide contexts attributes Show contexts attributes object
      • methods array[object] Required
        Hide methods attributes Show methods attributes object
      • name string Required
GET /_script_context
curl \
 -X GET http://api.example.com/_script_context
Response examples (200)
{
  "contexts": [
    {
      "methods": [
        {
          "name": "string",
          "return_type": "string",
          "params": [
            {}
          ]
        }
      ],
      "name": "string"
    }
  ]
}

Get script languages

GET /_script_language

Get a list of available script types, languages, and contexts.

Responses

GET /_script_language
curl \
 -X GET http://api.example.com/_script_language
Response examples (200)
{
  "language_contexts": [
    {
      "contexts": [
        "string"
      ],
      "": "painless"
    }
  ],
  "types_allowed": [
    "string"
  ]
}












Run a script Technical preview

POST /_scripts/painless/_execute

Runs a script and returns a result.

application/json

Body

  • context string

    The context that the script should run in.

  • Additional properties are allowed.

    Hide context_setup attributes Show context_setup attributes object
    • document object Required

      Document that’s temporarily indexed in-memory and accessible from the script.

      Additional properties are allowed.

    • index string Required
    • query object

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

      Additional properties are allowed.

  • script object

    Additional properties are allowed.

    Hide script attributes Show script attributes object
    • source string

      The script source.

    • id string
    • params object

      Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

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

        Additional properties are allowed.

    • lang string

      Any of:

      Values are painless, expression, mustache, or java.

    • options object
      Hide options attribute Show options attribute object
      • * string Additional properties

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result object Required

      Additional properties are allowed.

POST /_scripts/painless/_execute
curl \
 -X POST http://api.example.com/_scripts/painless/_execute \
 -H "Content-Type: application/json" \
 -d '{"context":"string","context_setup":{"document":{},"index":"string","query":{}},"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}}}'
Request examples
{
  "context": "string",
  "context_setup": {
    "document": {},
    "index": "string",
    "query": {}
  },
  "script": {
    "source": "string",
    "id": "string",
    "params": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "": "painless",
    "options": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    }
  }
}
Response examples (200)
{
  "result": {}
}





















































































































































Render a search template

GET /_render/template

Render a search template as a search request body.

application/json

Body

  • file string
  • params object

    Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.

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

      Additional properties are allowed.

  • source string

    An inline search template. Supports the same parameters as the search API's request body. These parameters also support Mustache variables. If no id or <templated-id> is specified, this parameter is required.

Responses

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

        Additional properties are allowed.

GET /_render/template
curl \
 -X GET http://api.example.com/_render/template \
 -H "Content-Type: application/json" \
 -d '{"file":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string"}'
Request examples
{
  "file": "string",
  "params": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "source": "string"
}
Response examples (200)
{
  "template_output": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}








































Get the search shards

POST /_search_shards

Get the indices and shards that a search request would be run against. This information can be useful for working out issues or planning optimizations with routing and shard preferences. When filtered aliases are used, the filter is returned as part of the indices section.

Query parameters

  • If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • expand_wildcards string | array[string]

    Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • If false, the request returns an error if it targets a missing or closed index.

  • local boolean

    If true, the request retrieves information from the local node only.

  • Specifies the node or shard the operation should be performed on. Random by default.

  • routing string

    Custom value used to route operations to a specific shard.

Responses

POST /_search_shards
curl \
 -X POST http://api.example.com/_search_shards
Response examples (200)
{
  "nodes": {
    "additionalProperty1": {
      "name": "string",
      "ephemeral_id": "string",
      "transport_address": "string",
      "external_id": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "roles": [
        "master"
      ],
      "version": "string",
      "min_index_version": 42.0,
      "max_index_version": 42.0
    },
    "additionalProperty2": {
      "name": "string",
      "ephemeral_id": "string",
      "transport_address": "string",
      "external_id": "string",
      "attributes": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "roles": [
        "master"
      ],
      "version": "string",
      "min_index_version": 42.0,
      "max_index_version": 42.0
    }
  },
  "shards": [
    [
      {
        "state": "UNASSIGNED",
        "primary": true,
        "node": "string",
        "shard": 42.0,
        "index": "string",
        "allocation_id": {
          "*": "string"
        },
        "recovery_source": {
          "*": "string"
        },
        "unassigned_info": {
          "": "string",
          "last_allocation_status": "string",
          "reason": "INDEX_CREATED",
          "details": "string",
          "failed_allocation_attempts": 42.0,
          "delayed": true,
          "allocation_status": "string"
        },
        "relocating_node": "string",
        "relocation_failure_info": {
          "failed_attempts": 42.0
        }
      }
    ]
  ],
  "indices": {
    "additionalProperty1": {
      "aliases": [
        "string"
      ],
      "filter": {}
    },
    "additionalProperty2": {
      "aliases": [
        "string"
      ],
      "filter": {}
    }
  }
}















































































































Bulk update API keys Added in 8.5.0

POST /_security/api_key/_bulk_update

Update the attributes for multiple API keys.

IMPORTANT: It is not possible to use an API key as the authentication credential for this API. To update API keys, the owner user's credentials are required.

This API is similar to the update API key API but enables you to apply the same update to multiple API keys in one API call. This operation can greatly improve performance over making individual updates.

It is not possible to update expired or invalidated API keys.

This API supports updates to API key access scope, metadata and expiration. The access scope of each API key is derived from the role_descriptors you specify in the request and a snapshot of the owner user's permissions at the time of the request. The snapshot of the owner's permissions is updated automatically on every call.

IMPORTANT: If you don't specify role_descriptors in the request, a call to this API might still change an API key's access scope. This change can occur if the owner user's permissions have changed since the API key was created or last modified.

A successful request returns a JSON structure that contains the IDs of all updated API keys, the IDs of API keys that already had the requested changes and did not require an update, and error details for any failed update.

application/json

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

  • ids string | array[string] Required

    The API key identifiers.

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

      Additional properties are allowed.

  • The role descriptors to assign to the API keys. An API key's effective permissions are an intersection of its assigned privileges and the point-in-time snapshot of permissions of the owner user. You can assign new privileges by specifying them in this parameter. To remove assigned privileges, supply the role_descriptors parameter as an empty object {}. If an API key has no assigned privileges, it inherits the owner user's full permissions. The snapshot of the owner's permissions is always updated, whether you supply the role_descriptors parameter. The structure of a role descriptor is the same as the request for the create API keys API.

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • cluster array[string]

        A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

      • indices array[object]

        A list of indices permissions entries.

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

          Hide field_security attributes Show field_security attributes object
        • names string | array[string]

          A list of indices (or index name patterns) to which the permissions in this entry apply.

        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query string | object

          While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

          Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

          One of:
        • Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      • remote_indices array[object]

        A list of indices permissions for remote clusters.

        Hide remote_indices attributes Show remote_indices attributes object
        • clusters string | array[string] Required
        • Additional properties are allowed.

          Hide field_security attributes Show field_security attributes object
        • names string | array[string]

          A list of indices (or index name patterns) to which the permissions in this entry apply.

        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query string | object

          While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

          Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

          One of:
        • Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      • remote_cluster array[object]

        A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

        Hide remote_cluster attributes Show remote_cluster attributes object
        • clusters string | array[string] Required
        • privileges array[string] Required

          The cluster level privileges that owners of the role have on the remote cluster.

          Values are monitor_enrich or monitor_stats.

      • global array[object] | object

        An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

        One of:
        Hide attribute Show attribute object
        • application object Required

          Additional properties are allowed.

          Hide application attribute Show application attribute object
          • manage object Required

            Additional properties are allowed.

      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

          A list of strings, where each element is the name of an application privilege or action.

        • resources array[string] Required

          A list resources to which the privileges are applied.

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

          Additional properties are allowed.

      • run_as array[string]

        A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

      • Optional description of the role descriptor

      • Additional properties are allowed.

        Hide restriction attribute Show restriction attribute object
        • workflows array[string] Required

          A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

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

          Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • errors object

      Additional properties are allowed.

      Hide errors attributes Show errors attributes object
      • count number Required

        The number of errors

      • details object Required

        Details about the errors, keyed by role name

        Hide details attribute Show details attribute object
        • * object

          Additional properties are allowed.

          Hide * attributes Show * 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.

    • noops array[string] Required
    • updated array[string] Required
POST /_security/api_key/_bulk_update
curl \
 -X POST http://api.example.com/_security/api_key/_bulk_update \
 -H "Content-Type: application/json" \
 -d '{"ids":["VuaCfGcBCdbkQm-e5aOx","H3_AhoIBA9hmeQJdg7ij"],"metadata":{"environment":{"tags":["production"],"level":2,"trusted":true}},"expiration":"30d","role_descriptors":{"role-a":{"indices":[{"names":["*"],"privileges":["write"]}]}}}'
Request examples
Assign new role descriptors and metadata and update the expiration time for two API keys.
{
  "ids": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "metadata": {
    "environment": {
      "tags": [
        "production"
      ],
      "level": 2,
      "trusted": true
    }
  },
  "expiration": "30d",
  "role_descriptors": {
    "role-a": {
      "indices": [
        {
          "names": [
            "*"
          ],
          "privileges": [
            "write"
          ]
        }
      ]
    }
  }
}
Remove the previously assigned permissions for two API keys, making them inherit the owner user's full permissions.
{
  "ids": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ],
  "role_descriptors": {}
}
Response examples (200)
A successful response from updating two API keys.
{
  "noops": [],
  "updated": [
    "VuaCfGcBCdbkQm-e5aOx",
    "H3_AhoIBA9hmeQJdg7ij"
  ]
}




















































































Get roles

GET /_security/role/{name}

Get roles in the native realm. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The get roles API cannot retrieve roles that are defined in roles files.

Path parameters

  • name string | array[string] Required

    The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.

Responses

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • cluster array[string] Required
      • indices array[object] Required
        Hide indices attributes Show indices attributes object
        • Additional properties are allowed.

          Hide field_security attributes Show field_security attributes object
        • names string | array[string]

          A list of indices (or index name patterns) to which the permissions in this entry apply.

        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query string | object

          While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

          Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

          One of:
        • Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      • remote_indices array[object]
        Hide remote_indices attributes Show remote_indices attributes object
        • clusters string | array[string] Required
        • Additional properties are allowed.

          Hide field_security attributes Show field_security attributes object
        • names string | array[string]

          A list of indices (or index name patterns) to which the permissions in this entry apply.

        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query string | object

          While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

          Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

          One of:
        • Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

      • remote_cluster array[object]
        Hide remote_cluster attributes Show remote_cluster attributes object
        • clusters string | array[string] Required
        • privileges array[string] Required

          The cluster level privileges that owners of the role have on the remote cluster.

          Values are monitor_enrich or monitor_stats.

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

          Additional properties are allowed.

      • run_as array[string] Required
      • Hide transient_metadata attribute Show transient_metadata attribute object
        • * object Additional properties

          Additional properties are allowed.

      • applications array[object] Required
        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

          A list of strings, where each element is the name of an application privilege or action.

        • resources array[string] Required

          A list resources to which the privileges are applied.

      • role_templates array[object]
        Hide role_templates attributes Show role_templates attributes object
        • format string

          Values are string or json.

        • template object Required

          Additional properties are allowed.

          Hide template attributes Show template attributes object
          • source string

            The script source.

          • id string
          • params object

            Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

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

              Additional properties are allowed.

          • lang string

            Any of:

            Values are painless, expression, mustache, or java.

          • options object
            Hide options attribute Show options attribute object
            • * string Additional properties
      • global object
        Hide global attribute Show global attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • * array[string] Additional properties
GET /_security/role/{name}
curl \
 -X GET http://api.example.com/_security/role/{name}
Response examples (200)
{
  "additionalProperty1": {
    "cluster": [
      "string"
    ],
    "indices": [
      {
        "field_security": {
          "except": "string",
          "grant": "string"
        },
        "names": "string",
        "privileges": [
          "string"
        ],
        "": "string",
        "allow_restricted_indices": true
      }
    ],
    "remote_indices": [
      {
        "clusters": "string",
        "field_security": {
          "except": "string",
          "grant": "string"
        },
        "names": "string",
        "privileges": [
          "string"
        ],
        "": "string",
        "allow_restricted_indices": true
      }
    ],
    "remote_cluster": [
      {
        "clusters": "string",
        "privileges": [
          "monitor_enrich"
        ]
      }
    ],
    "metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "run_as": [
      "string"
    ],
    "transient_metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "applications": [
      {
        "application": "string",
        "privileges": [
          "string"
        ],
        "resources": [
          "string"
        ]
      }
    ],
    "role_templates": [
      {
        "format": "string",
        "template": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        }
      }
    ],
    "global": {
      "additionalProperty1": {
        "additionalProperty1": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        },
        "additionalProperty2": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        }
      },
      "additionalProperty2": {
        "additionalProperty1": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        },
        "additionalProperty2": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        }
      }
    }
  },
  "additionalProperty2": {
    "cluster": [
      "string"
    ],
    "indices": [
      {
        "field_security": {
          "except": "string",
          "grant": "string"
        },
        "names": "string",
        "privileges": [
          "string"
        ],
        "": "string",
        "allow_restricted_indices": true
      }
    ],
    "remote_indices": [
      {
        "clusters": "string",
        "field_security": {
          "except": "string",
          "grant": "string"
        },
        "names": "string",
        "privileges": [
          "string"
        ],
        "": "string",
        "allow_restricted_indices": true
      }
    ],
    "remote_cluster": [
      {
        "clusters": "string",
        "privileges": [
          "monitor_enrich"
        ]
      }
    ],
    "metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "run_as": [
      "string"
    ],
    "transient_metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "applications": [
      {
        "application": "string",
        "privileges": [
          "string"
        ],
        "resources": [
          "string"
        ]
      }
    ],
    "role_templates": [
      {
        "format": "string",
        "template": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        }
      }
    ],
    "global": {
      "additionalProperty1": {
        "additionalProperty1": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        },
        "additionalProperty2": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        }
      },
      "additionalProperty2": {
        "additionalProperty1": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        },
        "additionalProperty2": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        }
      }
    }
  }
}
















Create or update role mappings Added in 5.5.0

PUT /_security/role_mapping/{name}

Role mappings define which roles are assigned to each user. Each mapping has rules that identify users and a list of roles that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.

NOTE: This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using the create or update roles API or roles files.

Role templates

The most common use for role mappings is to create a mapping from a known value on the user to a fixed role name. For example, all users in the cn=admin,dc=example,dc=com LDAP group should be given the superuser role in Elasticsearch. The roles field is used for this purpose.

For more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user. The role_templates field is used for this purpose.

NOTE: To use role templates successfully, the relevant scripting feature must be enabled. Otherwise, all attempts to create a role mapping with role templates fail.

All of the user fields that are available in the role mapping rules are also available in the role templates. Thus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated.

By default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user. If the format of the template is set to "json" then the template is expected to produce a JSON string or an array of JSON strings for the role names.

Path parameters

  • name string Required

    The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

application/json

Body Required

  • enabled boolean

    Mappings that have enabled set to false are ignored when role mapping is performed.

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

      Additional properties are allowed.

  • roles array[string]

    A list of role names that are granted to the users that match the role mapping rules. Exactly one of roles or role_templates must be specified.

  • role_templates array[object]

    A list of Mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules. Exactly one of roles or role_templates must be specified.

    Hide role_templates attributes Show role_templates attributes object
    • format string

      Values are string or json.

    • template object Required

      Additional properties are allowed.

      Hide template attributes Show template attributes object
      • source string

        The script source.

      • id string
      • params object

        Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

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

          Additional properties are allowed.

      • lang string

        Any of:

        Values are painless, expression, mustache, or java.

      • options object
        Hide options attribute Show options attribute object
        • * string Additional properties
  • rules object

    Additional properties are allowed.

    Hide rules attributes Show rules attributes object
    • any array[object]

      Additional properties are allowed.

    • all array[object]

      Additional properties are allowed.

    • field object

      Additional properties are allowed.

      Hide field attributes Show field attributes object
    • except object

      Additional properties are allowed.

  • run_as array[string]

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • created boolean
    • role_mapping object Required

      Additional properties are allowed.

      Hide role_mapping attribute Show role_mapping attribute object
PUT /_security/role_mapping/{name}
curl \
 -X PUT http://api.example.com/_security/role_mapping/{name} \
 -H "Content-Type: application/json" \
 -d '{"enabled":true,"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"roles":["string"],"role_templates":[{"format":"string","template":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}}}],"rules":{"any":[{}],"all":[{}],"field":{"username":"string","dn":"string","groups":"string"},"except":{}},"run_as":["string"]}'
Request examples
{
  "enabled": true,
  "metadata": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "roles": [
    "string"
  ],
  "role_templates": [
    {
      "format": "string",
      "template": {
        "source": "string",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "": "painless",
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      }
    }
  ],
  "rules": {
    "any": [
      {}
    ],
    "all": [
      {}
    ],
    "field": {
      "username": "string",
      "dn": "string",
      "groups": "string"
    },
    "except": {}
  },
  "run_as": [
    "string"
  ]
}
Response examples (200)
{
  "created": true,
  "role_mapping": {
    "created": true
  }
}




























Disable users

POST /_security/user/{username}/_disable

Disable users in the native realm. By default, when you create users, they are enabled. You can use this API to revoke a user's access to Elasticsearch.

Path parameters

  • username string Required

    An identifier for the user.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

Responses

  • 200 application/json

    Additional properties are allowed.

POST /_security/user/{username}/_disable
curl \
 -X POST http://api.example.com/_security/user/{username}/_disable
Response examples (200)
{}












































Create or update application privileges Added in 6.4.0

POST /_security/privilege

To use this API, you must have one of the following privileges:

  • The manage_security cluster privilege (or a greater privilege such as all).
  • The "Manage Application Privileges" global privilege for the application being referenced in the request.

Application names are formed from a prefix, with an optional suffix that conform to the following rules:

  • The prefix must begin with a lowercase ASCII letter.
  • The prefix must contain only ASCII letters or digits.
  • The prefix must be at least 3 characters long.
  • If the suffix exists, it must begin with either a dash - or _.
  • The suffix cannot contain any of the following characters: \, /, *, ?, ", <, >, |, ,, *.
  • No part of the name can contain whitespace.

Privilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters _, -, and ..

Action names can contain any number of printable ASCII characters and must contain at least one of the following characters: /, *, :.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

application/json

Body Required

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object

Responses

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

        Additional properties are allowed.

        Hide * attribute Show * attribute object
POST /_security/privilege
curl \
 -X POST http://api.example.com/_security/privilege \
 -H "Content-Type: application/json" \
 -d '{"additionalProperty1":{"additionalProperty1":{"actions":["string"],"application":"string","name":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"additionalProperty2":{"actions":["string"],"application":"string","name":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}}}},"additionalProperty2":{"additionalProperty1":{"actions":["string"],"application":"string","name":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"additionalProperty2":{"actions":["string"],"application":"string","name":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}}}}}'
Request examples
{
  "additionalProperty1": {
    "additionalProperty1": {
      "actions": [
        "string"
      ],
      "application": "string",
      "name": "string",
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    },
    "additionalProperty2": {
      "actions": [
        "string"
      ],
      "application": "string",
      "name": "string",
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  },
  "additionalProperty2": {
    "additionalProperty1": {
      "actions": [
        "string"
      ],
      "application": "string",
      "name": "string",
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    },
    "additionalProperty2": {
      "actions": [
        "string"
      ],
      "application": "string",
      "name": "string",
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  }
}
Response examples (200)
{
  "additionalProperty1": {
    "*": {
      "created": true
    }
  },
  "additionalProperty2": {
    "*": {
      "created": true
    }
  }
}




Get role mappings Added in 5.5.0

GET /_security/role_mapping

Role mappings define which roles are assigned to each user. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The get role mappings API cannot retrieve role mappings that are defined in role mapping files.

Responses

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • enabled boolean Required
      • metadata object Required
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties

          Additional properties are allowed.

      • roles array[string]
      • role_templates array[object]
        Hide role_templates attributes Show role_templates attributes object
        • format string

          Values are string or json.

        • template object Required

          Additional properties are allowed.

          Hide template attributes Show template attributes object
          • source string

            The script source.

          • id string
          • params object

            Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

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

              Additional properties are allowed.

          • lang string

            Any of:

            Values are painless, expression, mustache, or java.

          • options object
            Hide options attribute Show options attribute object
            • * string Additional properties
      • rules object Required

        Additional properties are allowed.

        Hide rules attributes Show rules attributes object
        • any array[object]

          Additional properties are allowed.

        • all array[object]

          Additional properties are allowed.

        • field object

          Additional properties are allowed.

          Hide field attributes Show field attributes object
        • except object

          Additional properties are allowed.

GET /_security/role_mapping
curl \
 -X GET http://api.example.com/_security/role_mapping
Response examples (200)
{
  "additionalProperty1": {
    "enabled": true,
    "metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "roles": [
      "string"
    ],
    "role_templates": [
      {
        "format": "string",
        "template": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        }
      }
    ],
    "rules": {
      "any": [
        {}
      ],
      "all": [
        {}
      ],
      "field": {
        "username": "string",
        "dn": "string",
        "groups": "string"
      },
      "except": {}
    }
  },
  "additionalProperty2": {
    "enabled": true,
    "metadata": {
      "additionalProperty1": {},
      "additionalProperty2": {}
    },
    "roles": [
      "string"
    ],
    "role_templates": [
      {
        "format": "string",
        "template": {
          "source": "string",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "": "painless",
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        }
      }
    ],
    "rules": {
      "any": [
        {}
      ],
      "all": [
        {}
      ],
      "field": {
        "username": "string",
        "dn": "string",
        "groups": "string"
      },
      "except": {}
    }
  }
}




Get service accounts Added in 7.13.0

GET /_security/service/{namespace}

Get a list of service accounts that match the provided path parameters.

NOTE: Currently, only the elastic/fleet-server service account is available.

Path parameters

  • namespace string Required

    The name of the namespace. Omit this parameter to retrieve information about all service accounts. If you omit this parameter, you must also omit the service parameter.

Responses

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

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • role_descriptor object Required

        Additional properties are allowed.

        Hide role_descriptor attributes Show role_descriptor attributes object
        • cluster array[string] Required

          A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

        • indices array[object] Required

          A list of indices permissions entries.

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

            Hide field_security attributes Show field_security attributes object
          • names string | array[string]

            A list of indices (or index name patterns) to which the permissions in this entry apply.

          • privileges array[string] Required

            The index level privileges that owners of the role have on the specified indices.

          • query string | object

            While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

            Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

            One of:
          • Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

        • remote_indices array[object]

          A list of indices permissions for remote clusters.

          Hide remote_indices attributes Show remote_indices attributes object
          • clusters string | array[string] Required
          • Additional properties are allowed.

            Hide field_security attributes Show field_security attributes object
          • names string | array[string]

            A list of indices (or index name patterns) to which the permissions in this entry apply.

          • privileges array[string] Required

            The index level privileges that owners of the role have on the specified indices.

          • query string | object

            While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.

            Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.

            One of:
          • Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

        • remote_cluster array[object]

          A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

          Hide remote_cluster attributes Show remote_cluster attributes object
          • clusters string | array[string] Required
          • privileges array[string] Required

            The cluster level privileges that owners of the role have on the remote cluster.

            Values are monitor_enrich or monitor_stats.

        • global array[object] | object

          An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

          One of:
          Hide attribute Show attribute object
        • applications array[object]

          A list of application privilege entries

          Hide applications attributes Show applications attributes object
          • application string Required

            The name of the application to which this entry applies.

          • privileges array[string] Required

            A list of strings, where each element is the name of an application privilege or action.

          • resources array[string] Required

            A list resources to which the privileges are applied.

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

            Additional properties are allowed.

        • run_as array[string]

          A list of users that the API keys can impersonate.

        • An optional description of the role descriptor.

        • Additional properties are allowed.

          Hide restriction attribute Show restriction attribute object
          • workflows array[string] Required

            A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

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

            Additional properties are allowed.

GET /_security/service/{namespace}
curl \
 -X GET http://api.example.com/_security/service/{namespace}
Response examples (200)
{
  "additionalProperty1": {
    "role_descriptor": {
      "cluster": [
        "string"
      ],
      "indices": [
        {
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_indices": [
        {
          "clusters": "string",
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_cluster": [
        {
          "clusters": "string",
          "privileges": [
            "monitor_enrich"
          ]
        }
      ],
      "global": [
        {
          "application": {}
        }
      ],
      "applications": [
        {
          "application": "string",
          "privileges": [
            "string"
          ],
          "resources": [
            "string"
          ]
        }
      ],
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "run_as": [
        "string"
      ],
      "description": "string",
      "restriction": {
        "workflows": [
          "string"
        ]
      },
      "transient_metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  },
  "additionalProperty2": {
    "role_descriptor": {
      "cluster": [
        "string"
      ],
      "indices": [
        {
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_indices": [
        {
          "clusters": "string",
          "field_security": {
            "except": "string",
            "grant": "string"
          },
          "names": "string",
          "privileges": [
            "string"
          ],
          "": "string",
          "allow_restricted_indices": true
        }
      ],
      "remote_cluster": [
        {
          "clusters": "string",
          "privileges": [
            "monitor_enrich"
          ]
        }
      ],
      "global": [
        {
          "application": {}
        }
      ],
      "applications": [
        {
          "application": "string",
          "privileges": [
            "string"
          ],
          "resources": [
            "string"
          ]
        }
      ],
      "metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "run_as": [
        "string"
      ],
      "description": "string",
      "restriction": {
        "workflows": [
          "string"
        ]
      },
      "transient_metadata": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  }
}