Get behavioral analytics collections Deprecated Technical preview

GET /_application/analytics
Api key auth

Responses

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

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • event_data_stream object Required

        Additional properties are allowed.

        Hide event_data_stream attribute Show event_data_stream attribute object
GET /_application/analytics 
curl \
 --request GET http://api.example.com/_application/analytics \
 --header "Authorization: $API_KEY"
Response examples (200)
A successful response from `GET _application/analytics/my*` 
{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}

Get index information

GET /_cat/indices
Api key auth

Get high-level information about indices in a cluster, including backing indices for data streams.

Use this request to get the following information for each index in a cluster:

  • shard count
  • document count
  • deleted document count
  • primary store size
  • total store size of all shards, including shard replicas

These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. To get an accurate count of Elasticsearch documents, use the cat count or count APIs.

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 an index endpoint.

Query parameters

  • bytes string

    The unit used to display byte values.

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

  • expand_wildcards string | array[string]

    The type of index that wildcard patterns can match.

  • health string

    The health status used to limit returned indices. By default, the response includes indices of any health status.

    Values are green, GREEN, yellow, YELLOW, red, or RED.

  • include_unloaded_segments boolean

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

  • pri boolean

    If true, the response only includes information from primary shards.

  • time string

    The unit used to display time values.

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

  • master_timeout string

    Period to wait for a connection to the master node.

  • h string | array[string]

    List of columns to appear in the response. Supports simple wildcards.

  • s string | array[string]

    List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

Responses

GET /_cat/indices 
curl \
 --request GET http://api.example.com/_cat/indices \
 --header "Authorization: $API_KEY"

Get a connector sync job Beta

GET /_connector/_sync_job/{connector_sync_job_id}
Api key auth

Path parameters

Responses

GET /_connector/_sync_job/{connector_sync_job_id} 
curl \
 --request GET http://api.example.com/_connector/_sync_job/{connector_sync_job_id} \
 --header "Authorization: $API_KEY"

Get all connector sync jobs Beta

GET /_connector/_sync_job
Api key auth

Get information about all stored connector sync jobs listed by their creation date in ascending order.

Query parameters

  • from number

    Starting offset (default: 0)

  • size number

    Specifies a max number of results to get

  • status string

    A sync job status to fetch connector sync jobs for

    Values are canceling, canceled, completed, error, in_progress, pending, or suspended.

  • connector_id string

    A connector id to fetch connector sync jobs for

  • job_type string | array[string]

    A comma-separated list of job types to fetch the sync jobs for

Responses

GET /_connector/_sync_job 
curl \
 --request GET http://api.example.com/_connector/_sync_job \
 --header "Authorization: $API_KEY"

Create or update a document in an index

POST /{index}/_doc
Api key auth

Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.

NOTE: You cannot use this API to send update requests for existing documents in a data stream.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

  • To add or overwrite a document using the PUT /<target>/_doc/<_id> request format, you must have the create, index, or write index privilege.
  • To add a document using the POST /<target>/_doc/ request format, you must have the create_doc, create, index, or write index privilege.
  • To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.

Automatic data stream creation requires a matching index template with data stream enabled.

NOTE: Replica shards might not all be started when an indexing operation returns successfully. By default, only the primary is required. Set wait_for_active_shards to change this default behavior.

Automatically create data streams and indices

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.

Automatic index creation is controlled by the action.auto_create_index setting. If it is true, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow.

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. It does not affect the creation of data streams.

Optimistic concurrency control

Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

Routing

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

Distributed

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

Active shards

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. To alter this behavior per operation, use the wait_for_active_shards request parameter.

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). Specifying a negative value or a number greater than the number of shard copies will throw an error.

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

No operation (noop) updates

When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. If this isn't acceptable use the _update API with detect_noop set to true. The detect_noop option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.

There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.

Versioning

Each indexed document is given a version number. By default, internal versioning is used that starts at 1 and increments with each update, deletes included. Optionally, the version number can be set to an external value (for example, if maintained in a database). To enable this functionality, version_type should be set to external. The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18.

NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks.

When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:

PUT my-index-000001/_doc/1?version=2&version_type=external
{
  "user": {
    "id": "elkbee"
  }
}

In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).

A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
External documentation

Path parameters

  • index string Required

    The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream. If the target doesn't exist and doesn't match a data stream template, this request creates the index. You can check for existing targets with the resolve index API.

Query parameters

  • if_primary_term number

    Only perform the operation if the document has this primary term.

  • if_seq_no number

    Only perform the operation if the document has this sequence number.

  • include_source_on_error boolean

    True or false if to include the document source in the error message in case of parsing errors.

  • op_type string

    Set to create to only index the document if it does not already exist (put if absent). If a document with the specified _id already exists, the indexing operation will fail. The behavior is the same as using the <index>/_create endpoint. If a document ID is specified, this paramater defaults to index. Otherwise, it defaults to create. If the request targets a data stream, an op_type of create is required.

    Values are index or create.

  • pipeline string

    The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

  • refresh string

    If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

    Values are true, false, or wait_for.

  • routing string

    A custom value that is used to route operations to a specific shard.

  • timeout string

    The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.

    This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.

  • version number

    An explicit version number for concurrency control. It must be a non-negative long number.

  • version_type string

    The version type.

    Values are internal, external, external_gte, or force.

  • wait_for_active_shards number | string

    The number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

  • require_alias boolean

    If true, the destination must be an index alias.

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required
    • _index string Required
    • _primary_term number

      The primary term assigned to the document for the indexing operation.

    • result string Required

      Values are created, updated, deleted, not_found, or noop.

    • _seq_no number
    • _shards object Required

      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.

          • stack_trace string

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

          • caused_by object

            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
    • _version number Required
    • forced_refresh boolean
POST /{index}/_doc 
curl \
 --request POST http://api.example.com/{index}/_doc \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"@timestamp\": \"2099-11-15T13:12:00\",\n  \"message\": \"GET /search HTTP/1.1 200 1070000\",\n  \"user\": {\n    \"id\": \"kimchy\"\n  }\n}"'
Request examples
Run `POST my-index-000001/_doc/` to index a document. When you use the `POST /<target>/_doc/` request format, the `op_type` is automatically set to `create` and the index operation generates a unique ID for the document. 
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}
Run `PUT my-index-000001/_doc/1` to insert a JSON document into the `my-index-000001` index with an `_id` of 1. 
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}
Response examples (200)
A successful response from `POST my-index-000001/_doc/`, which contains an automated document ID. 
{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "W0tpsmIBdwcYyG50zbta",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}
A successful response from `PUT my-index-000001/_doc/1`. 
{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}

Get multiple term vectors

GET /{index}/_mtermvectors
Api key auth

Get multiple term vectors with a single request. You can specify existing documents by index and ID or provide artificial documents in the body of the request. You can specify the index in the request body or request URI. The response contains a docs array with all the fetched termvectors. Each element has the structure provided by the termvectors API.

Artificial documents

You can also use mtermvectors to generate term vectors for artificial documents provided in the body of the request. The mapping used is determined by the specified _index.

Path parameters

  • index string Required

    The name of the index that contains the documents.

Query parameters

  • ids array[string]

    A comma-separated list of documents ids. You must define ids as parameter or set "ids" or "docs" in the request body

  • fields string | array[string]

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

  • field_statistics boolean

    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.

  • preference string

    The node or shard the operation should be performed on. It is random by default.

  • realtime boolean

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

  • routing string

    A custom value used to route operations to a specific shard.

  • term_statistics boolean

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

  • version number

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

  • version_type string

    The version type.

    Values are internal, external, external_gte, or force.

application/json

Body

  • docs array[object]

    An array of existing or artificial documents.

    Hide docs attributes Show docs attributes object
    • _id string
    • _index string
    • doc object

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

      Additional properties are allowed.

    • fields string | array[string]
    • field_statistics boolean

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

    • filter object

      Additional properties are allowed.

      Hide filter attributes Show filter attributes object
      • max_doc_freq number

        Ignore words which occur in more than this many docs. Defaults to unbounded.

      • max_num_terms number

        The maximum number of terms that must be returned per field.

      • max_term_freq number

        Ignore words with more than this frequency in the source doc. It defaults to unbounded.

      • max_word_length number

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

      • min_doc_freq number

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

      • min_term_freq number

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

      • min_word_length number

        The minimum word length below which words will be ignored.

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

    • routing string
    • term_statistics boolean

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

    • version number
    • version_type string

      Values are internal, external, external_gte, or force.

  • ids array[string]

    A simplified syntax to specify documents by their ID if they're in the same index.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • docs array[object] Required
      Hide docs attributes Show docs attributes object
      • _id string
      • _index string Required
      • _version number
      • took number
      • found boolean
      • term_vectors object
        Hide term_vectors attribute Show term_vectors attribute object
        • * object Additional properties

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • field_statistics object

            Additional properties are allowed.

            Hide field_statistics attributes Show field_statistics attributes object
          • terms object Required
            Hide terms attribute Show terms attribute object
            • * object Additional properties

              Additional properties are allowed.

      • error object

        Additional properties are allowed.

        Hide error attributes Show error attributes object
        • type string Required

          The type of error

        • reason string

          A human-readable explanation of the error, in English.

        • stack_trace string

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

        • caused_by object

          Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.
GET /{index}/_mtermvectors 
curl \
 --request GET http://api.example.com/{index}/_mtermvectors \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"docs\": [\n      {\n        \"_id\": \"2\",\n        \"fields\": [\n            \"message\"\n        ],\n        \"term_statistics\": true\n      },\n      {\n        \"_id\": \"1\"\n      }\n  ]\n}"'
Request examples
Run `POST /my-index-000001/_mtermvectors`. When you specify an index in the request URI, the index does not need to be specified for each documents in the request body. 
{
  "docs": [
      {
        "_id": "2",
        "fields": [
            "message"
        ],
        "term_statistics": true
      },
      {
        "_id": "1"
      }
  ]
}
Run `POST /my-index-000001/_mtermvectors`. If all requested documents are in same index and the parameters are the same, you can use a simplified syntax. 
{
  "ids": [ "1", "2" ],
  "parameters": {
    "fields": [
      "message"
    ],
    "term_statistics": true
  }
}
Run `POST /_mtermvectors` to generate term vectors for artificial documents provided in the body of the request. The mapping used is determined by the specified `_index`. 
{
  "docs": [
      {
        "_index": "my-index-000001",
        "doc" : {
            "message" : "test test test"
        }
      },
      {
        "_index": "my-index-000001",
        "doc" : {
          "message" : "Another test ..."
        }
      }
  ]
}

Enrich

Run an enrich policy Added in 7.5.0

PUT /_enrich/policy/{name}/_execute
Api key auth

Create the enrich index for an existing enrich policy.

Path parameters

  • name string Required

    Enrich policy to execute.

Query parameters

  • master_timeout string

    Period to wait for a connection to the master node.

  • wait_for_completion boolean

    If true, the request blocks other enrich policy execution requests until complete.

Responses

PUT /_enrich/policy/{name}/_execute 
curl \
 --request PUT http://api.example.com/_enrich/policy/{name}/_execute \
 --header "Authorization: $API_KEY"

Index

Index APIs enable you to manage individual indices, index settings, aliases, mappings, and index templates.

Get tokens from text analysis

POST /_analyze
Api key auth

The analyze API performs analysis on a text string and returns the resulting tokens.

Generating excessive amount of tokens may cause a node to run out of memory. The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. If more than this limit of tokens gets generated, an error occurs. The _analyze endpoint without a specified index will always use 10000 as its limit.

External documentation
application/json

Body

Responses

POST /_analyze 
curl \
 --request POST http://api.example.com/_analyze \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"text":"this is a test","analyzer":"standard"}'
Request example
You can apply any of the built-in analyzers to the text string without specifying an index. 
{
  "text": "this is a test",
  "analyzer": "standard"
}

Get tokens from text analysis

GET /{index}/_analyze
Api key auth

The analyze API performs analysis on a text string and returns the resulting tokens.

Generating excessive amount of tokens may cause a node to run out of memory. The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. If more than this limit of tokens gets generated, an error occurs. The _analyze endpoint without a specified index will always use 10000 as its limit.

External documentation

Path parameters

  • index string Required

    Index used to derive the analyzer. If specified, the analyzer or field parameter overrides this value. If no index is specified or the index does not have a default analyzer, the analyze API uses the standard analyzer.

application/json

Body

Responses

GET /{index}/_analyze 
curl \
 --request GET http://api.example.com/{index}/_analyze \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"text":"this is a test","analyzer":"standard"}'
Request example
You can apply any of the built-in analyzers to the text string without specifying an index. 
{
  "text": "this is a test",
  "analyzer": "standard"
}

Get mapping definitions

GET /_mapping
Api key auth

For data streams, the API retrieves mappings for the stream’s backing indices.

Query parameters

  • allow_no_indices boolean

    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.

  • ignore_unavailable boolean

    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.

  • master_timeout string

    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

GET /_mapping 
curl \
 --request GET http://api.example.com/_mapping \
 --header "Authorization: $API_KEY"

Update field mappings

POST /{index}/_mapping
Api key auth

Add new fields to an existing data stream or index. You can also use this API to change the search settings of existing fields and add new properties to existing object fields. For data streams, these changes are applied to all backing indices by default.

Add multi-fields to an existing field

Multi-fields let you index the same field in different ways. You can use this API to update the fields mapping parameter and enable multi-fields for an existing field. WARNING: If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. You can populate the new multi-field with the update by query API.

Change supported mapping parameters for an existing field

The documentation for each mapping parameter indicates whether you can update it for an existing field using this API. For example, you can use the update mapping API to update the ignore_above parameter.

Change the mapping of an existing field

Except for supported mapping parameters, you can't change the mapping or field type of an existing field. Changing an existing field could invalidate data that's already indexed.

If you need to change the mapping of a field in a data stream's backing indices, refer to documentation about modifying data streams. If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.

Rename a field

Renaming a field would invalidate data already indexed under the old field name. Instead, add an alias field to create an alternate field name.

External documentation

Path parameters

  • index string | array[string] Required

    A comma-separated list of index names the mapping should be added to (supports wildcards); use _all or omit to add the mapping on all indices.

Query parameters

  • allow_no_indices boolean

    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.

  • ignore_unavailable boolean

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

  • master_timeout string

    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.

  • write_index_only boolean

    If true, the mappings are applied only to the current write index for the target.

application/json

Body Required

  • date_detection boolean

    Controls whether dynamic date detection is enabled.

  • dynamic string

    Values are strict, runtime, true, or false.

  • dynamic_date_formats array[string]

    If date detection is enabled then new string fields are checked against 'dynamic_date_formats' and if the value matches then a new date field is added instead of string.

  • dynamic_templates array[object]

    Specify dynamic templates for the mapping.

  • _field_names object

    Additional properties are allowed.

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

      Additional properties are allowed.

  • numeric_detection boolean

    Automatically map strings into numeric data types for all fields.

  • properties object

    Mapping for a field. For new fields, this mapping can include:

    • Field name
    • Field data type
    • Mapping parameters
  • _routing object

    Additional properties are allowed.

    Hide _routing attribute Show _routing attribute object
  • _source object

    Additional properties are allowed.

    Hide _source attributes Show _source attributes object
  • runtime object
    Hide runtime attribute Show runtime 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.

      • input_field string

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

      • target_field string

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

      • target_index string
      • 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:
          _types:ScriptLanguage string _types:ScriptLanguage string

          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.

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
POST /{index}/_mapping 
curl \
 --request POST http://api.example.com/{index}/_mapping \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"properties":{"user":{"properties":{"name":{"type":"keyword"}}}}}'
Request example
The update mapping API can be applied to multiple data streams or indices with a single request. For example, run `PUT /my-index-000001,my-index-000002/_mapping` to update mappings for the `my-index-000001` and `my-index-000002` indices at the same time. 
{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}

Ingest

Ingest APIs enable you to manage tasks and resources related to ingest pipelines and processors.

Simulate a pipeline Added in 5.0.0

POST /_ingest/pipeline/_simulate
Api key auth

Run an ingest pipeline against a set of provided documents. You can either specify an existing pipeline to use with the provided documents or supply a pipeline definition in the body of the request.

Query parameters

  • verbose boolean

    If true, the response includes output data for each processor in the executed pipeline.

application/json

Body Required

  • docs array[object] Required

    Sample documents to test in the pipeline.

    Hide docs attributes Show docs attributes object
    • _id string
    • _index string
    • _source object Required

      JSON body for the document.

      Additional properties are allowed.

  • pipeline object Additional properties

    Additional properties are allowed.

    Hide pipeline attributes Show pipeline attributes object
    • description string

      Description of the ingest pipeline.

    • on_failure array[object]

      Processors to run immediately after a processor failure.

      Hide on_failure attributes Show on_failure attributes object
      • append object

        Additional properties are allowed.

        Hide append attributes Show append attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • value object Required

          Additional properties are allowed.

        • allow_duplicates boolean

          If false, the processor does not append values already present in the field.

      • attachment object

        Additional properties are allowed.

        Hide attachment attributes Show attachment attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • indexed_chars number

          The number of chars being used for extraction to prevent huge fields. Use -1 for no limit.

        • indexed_chars_field string

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

        • properties array[string]

          Array of properties to select to be stored. Can be content, title, name, author, keywords, date, content_type, content_length, language.

        • target_field string

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

        • remove_binary boolean

          If true, the binary field will be removed from the document

        • resource_name string

          Field containing the name of the resource to decode. If specified, the processor passes this resource name to the underlying Tika library to enable Resource Name Based Detection.

      • bytes object

        Additional properties are allowed.

        Hide bytes attributes Show bytes attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • circle object

        Additional properties are allowed.

        Hide circle attributes Show circle attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • error_distance number Required

          The difference between the resulting inscribed distance from center to side and the circle’s radius (measured in meters for geo_shape, unit-less for shape).

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • shape_type string Required

          Values are geo_shape or shape.

        • target_field string

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

      • community_id object

        Additional properties are allowed.

        Hide community_id attributes Show community_id attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • source_ip string

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

        • source_port string

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

        • destination_ip string

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

        • destination_port string

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

        • iana_number string

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

        • icmp_type string

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

        • icmp_code string

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

        • transport string

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

        • target_field string

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

        • seed number

          Seed for the community ID hash. Must be between 0 and 65535 (inclusive). The seed can prevent hash collisions between network domains, such as a staging and production network that use the same addressing scheme.

        • ignore_missing boolean

          If true and any required fields are missing, the processor quietly exits without modifying the document.

      • convert object

        Additional properties are allowed.

        Hide convert attributes Show convert attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

        • type string Required

          Values are integer, long, double, float, boolean, ip, string, or auto.

      • csv object

        Additional properties are allowed.

        Hide csv attributes Show csv attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • empty_value object

          Value used to fill empty fields. Empty fields are skipped if this is not provided. An empty field is one with no value (2 consecutive separators) or empty quotes ("").

          Additional properties are allowed.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • quote string

          Quote used in CSV, has to be single character string.

        • separator string

          Separator used in CSV, has to be single character string.

        • target_fields string | array[string] Required
        • trim boolean

          Trim whitespaces in unquoted fields.

      • date object

        Additional properties are allowed.

        Hide date attributes Show date attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • formats array[string] Required

          An array of the expected date formats. Can be a java time pattern or one of the following formats: ISO8601, UNIX, UNIX_MS, or TAI64N.

        • locale string

          The locale to use when parsing the date, relevant when parsing month names or week days. Supports template snippets.

        • target_field string

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

        • timezone string

          The timezone to use when parsing the date. Supports template snippets.

        • output_format string

          The format to use when writing the date to target_field. Must be a valid java time pattern.

      • date_index_name object

        Additional properties are allowed.

        Hide date_index_name attributes Show date_index_name attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • date_formats array[string]

          An array of the expected date formats for parsing dates / timestamps in the document being preprocessed. Can be a java time pattern or one of the following formats: ISO8601, UNIX, UNIX_MS, or TAI64N.

        • date_rounding string Required

          How to round the date when formatting the date into the index name. Valid values are: y (year), M (month), w (week), d (day), h (hour), m (minute) and s (second). Supports template snippets.

        • field string Required

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

        • index_name_format string

          The format to be used when printing the parsed date into the index name. A valid java time pattern is expected here. Supports template snippets.

        • index_name_prefix string

          A prefix of the index name to be prepended before the printed date. Supports template snippets.

        • locale string

          The locale to use when parsing the date from the document being preprocessed, relevant when parsing month names or week days.

        • timezone string

          The timezone to use when parsing the date and when date math index supports resolves expressions into concrete index names.

      • dissect object

        Additional properties are allowed.

        Hide dissect attributes Show dissect attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • append_separator string

          The character(s) that separate the appended fields.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • pattern string Required

          The pattern to apply to the field.

      • dot_expander object

        Additional properties are allowed.

        Hide dot_expander attributes Show dot_expander attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • override boolean

          Controls the behavior when there is already an existing nested object that conflicts with the expanded field. When false, the processor will merge conflicts by combining the old and the new values into an array. When true, the value from the expanded field will overwrite the existing value.

        • path string

          The field that contains the field to expand. Only required if the field to expand is part another object field, because the field option can only understand leaf fields.

      • drop object

        Additional properties are allowed.

        Hide drop attributes Show drop attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

      • enrich object

        Additional properties are allowed.

        Hide enrich attributes Show enrich attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • max_matches number

          The maximum number of matched documents to include under the configured target field. The target_field will be turned into a json array if max_matches is higher than 1, otherwise target_field will become a json object. In order to avoid documents getting too large, the maximum allowed value is 128.

        • override boolean

          If processor will update fields with pre-existing non-null-valued field. When set to false, such fields will not be touched.

        • policy_name string Required

          The name of the enrich policy to use.

        • shape_relation string

          Values are intersects, disjoint, within, or contains.

        • target_field string Required

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

      • fail object

        Additional properties are allowed.

        Hide fail attributes Show fail attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • message string Required

          The error message thrown by the processor. Supports template snippets.

      • fingerprint object

        Additional properties are allowed.

        Hide fingerprint attributes Show fingerprint attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • fields string | array[string] Required
        • target_field string

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

        • salt string

          Salt value for the hash function.

        • method string

          Values are MD5, SHA-1, SHA-256, SHA-512, or MurmurHash3.

        • ignore_missing boolean

          If true, the processor ignores any missing fields. If all fields are missing, the processor silently exits without modifying the document.

      • foreach object

        Additional properties are allowed.

        Hide foreach attributes Show foreach attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true, the processor silently exits without changing the document if the field is null or missing.

        • processor object Required

          Additional properties are allowed.

      • ip_location object

        Additional properties are allowed.

        Hide ip_location attributes Show ip_location attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • database_file string

          The database filename referring to a database the module ships with (GeoLite2-City.mmdb, GeoLite2-Country.mmdb, or GeoLite2-ASN.mmdb) or a custom database in the ingest-geoip config directory.

        • field string Required

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

        • first_only boolean

          If true, only the first found IP location data will be returned, even if the field contains an array.

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • properties array[string]

          Controls what properties are added to the target_field based on the IP location lookup.

        • target_field string

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

        • download_database_on_pipeline_creation boolean

          If true (and if ingest.geoip.downloader.eager.download is false), the missing database is downloaded when the pipeline is created. Else, the download is triggered by when the pipeline is used as the default_pipeline or final_pipeline in an index.

      • geo_grid object

        Additional properties are allowed.

        Hide geo_grid attributes Show geo_grid attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

          The field to interpret as a geo-tile.= The field format is determined by the tile_type.

        • tile_type string Required

          Values are geotile, geohex, or geohash.

        • target_field string

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

        • parent_field string

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

        • children_field string

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

        • non_children_field string

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

        • precision_field string

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • target_format string

          Values are geojson or wkt.

      • geoip object

        Additional properties are allowed.

        Hide geoip attributes Show geoip attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • database_file string

          The database filename referring to a database the module ships with (GeoLite2-City.mmdb, GeoLite2-Country.mmdb, or GeoLite2-ASN.mmdb) or a custom database in the ingest-geoip config directory.

        • field string Required

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

        • first_only boolean

          If true, only the first found geoip data will be returned, even if the field contains an array.

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • properties array[string]

          Controls what properties are added to the target_field based on the geoip lookup.

        • target_field string

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

        • download_database_on_pipeline_creation boolean

          If true (and if ingest.geoip.downloader.eager.download is false), the missing database is downloaded when the pipeline is created. Else, the download is triggered by when the pipeline is used as the default_pipeline or final_pipeline in an index.

      • grok object

        Additional properties are allowed.

        Hide grok attributes Show grok attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • ecs_compatibility string

          Must be disabled or v1. If v1, the processor uses patterns with Elastic Common Schema (ECS) field names.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • pattern_definitions object

          A map of pattern-name and pattern tuples defining custom patterns to be used by the current processor. Patterns matching existing names will override the pre-existing definition.

          Hide pattern_definitions attribute Show pattern_definitions attribute object
          • * string Additional properties
        • patterns array[string] Required

          An ordered list of grok expression to match and extract named captures with. Returns on the first expression in the list that matches.

        • trace_match boolean

          When true, _ingest._grok_match_index will be inserted into your matched document’s metadata with the index into the pattern found in patterns that matched.

      • gsub object

        Additional properties are allowed.

        Hide gsub attributes Show gsub attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • pattern string Required

          The pattern to be replaced.

        • replacement string Required

          The string to replace the matching patterns with.

        • target_field string

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

      • html_strip object

        Additional properties are allowed.

        Hide html_strip attributes Show html_strip attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document,

        • target_field string

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

      • inference object

        Additional properties are allowed.

        Hide inference attributes Show inference attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • model_id string Required
        • target_field string

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

        • field_map object

          Maps the document field names to the known field names of the model. This mapping takes precedence over any default mappings provided in the model configuration.

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

            Additional properties are allowed.

        • inference_config object

          Additional properties are allowed.

          Hide inference_config attributes Show inference_config attributes object
      • join object

        Additional properties are allowed.

        Hide join attributes Show join attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • separator string Required

          The separator character.

        • target_field string

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

      • json object

        Additional properties are allowed.

        Hide json attributes Show json attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • add_to_root boolean

          Flag that forces the parsed JSON to be added at the top level of the document. target_field must not be set when this option is chosen.

        • add_to_root_conflict_strategy string

          Values are replace or merge.

        • allow_duplicate_keys boolean

          When set to true, the JSON parser will not fail if the JSON contains duplicate keys. Instead, the last encountered value for any duplicate key wins.

        • field string Required

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

        • target_field string

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

      • kv object

        Additional properties are allowed.

        Hide kv attributes Show kv attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • exclude_keys array[string]

          List of keys to exclude from document.

        • field string Required

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

        • field_split string Required

          Regex pattern to use for splitting key-value pairs.

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • include_keys array[string]

          List of keys to filter and insert into document. Defaults to including all keys.

        • prefix string

          Prefix to be added to extracted keys.

        • strip_brackets boolean

          If true. strip brackets (), <>, [] as well as quotes ' and " from extracted values.

        • target_field string

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

        • trim_key string

          String of characters to trim from extracted keys.

        • trim_value string

          String of characters to trim from extracted values.

        • value_split string Required

          Regex pattern to use for splitting the key from the value within a key-value pair.

      • lowercase object

        Additional properties are allowed.

        Hide lowercase attributes Show lowercase attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • network_direction object

        Additional properties are allowed.

        Hide network_direction attributes Show network_direction attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • source_ip string

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

        • destination_ip string

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

        • target_field string

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

        • internal_networks array[string]

          List of internal networks. Supports IPv4 and IPv6 addresses and ranges in CIDR notation. Also supports the named ranges listed below. These may be constructed with template snippets. Must specify only one of internal_networks or internal_networks_field.

        • internal_networks_field string

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

        • ignore_missing boolean

          If true and any required fields are missing, the processor quietly exits without modifying the document.

      • pipeline object

        Additional properties are allowed.

        Hide pipeline attributes Show pipeline attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • name string Required
        • ignore_missing_pipeline boolean

          Whether to ignore missing pipelines instead of failing.

      • redact object

        Additional properties are allowed.

        Hide redact attributes Show redact attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • patterns array[string] Required

          A list of grok expressions to match and redact named captures with

        • pattern_definitions object
          Hide pattern_definitions attribute Show pattern_definitions attribute object
          • * string Additional properties
        • prefix string

          Start a redacted section with this token

        • suffix string

          End a redacted section with this token

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • skip_if_unlicensed boolean

          If true and the current license does not support running redact processors, then the processor quietly exits without modifying the document

        • trace_redact boolean

          If true then ingest metadata _ingest._redact._is_redacted is set to true if the document has been redacted

      • registered_domain object

        Additional properties are allowed.

        Hide registered_domain attributes Show registered_domain attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • target_field string

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

        • ignore_missing boolean

          If true and any required fields are missing, the processor quietly exits without modifying the document.

      • remove object

        Additional properties are allowed.

        Hide remove attributes Show remove attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string | array[string] Required
        • keep string | array[string]
        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

      • rename object

        Additional properties are allowed.

        Hide rename attributes Show rename attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • target_field string Required

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

      • reroute object

        Additional properties are allowed.

        Hide reroute attributes Show reroute attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • destination string

          A static value for the target. Can’t be set when the dataset or namespace option is set.

        • dataset string
        • namespace string
      • script object

        Additional properties are allowed.

        Hide script attributes Show script attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • id string
        • lang string

          Script language.

        • params object

          Object containing parameters for the script.

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

            Additional properties are allowed.

        • source string

          Inline script. If no id is specified, this parameter is required.

      • set object

        Additional properties are allowed.

        Hide set attributes Show set attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • copy_from string

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

        • field string Required

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

        • ignore_empty_value boolean

          If true and value is a template snippet that evaluates to null or the empty string, the processor quietly exits without modifying the document.

        • media_type string

          The media type for encoding value. Applies only when value is a template snippet. Must be one of application/json, text/plain, or application/x-www-form-urlencoded.

        • override boolean

          If true processor will update fields with pre-existing non-null-valued field. When set to false, such fields will not be touched.

        • value object

          The value to be set for the field. Supports template snippets. May specify only one of value or copy_from.

          Additional properties are allowed.

      • set_security_user object

        Additional properties are allowed.

        Hide set_security_user attributes Show set_security_user attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • properties array[string]

          Controls what user related properties are added to the field.

      • sort object

        Additional properties are allowed.

        Hide sort attributes Show sort attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • order string

          Values are asc or desc.

        • target_field string

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

      • split object

        Additional properties are allowed.

        Hide split attributes Show split attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • preserve_trailing boolean

          Preserves empty trailing fields, if any.

        • separator string Required

          A regex which matches the separator, for example, , or \s+.

        • target_field string

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

      • terminate object

        Additional properties are allowed.

        Hide terminate attributes Show terminate attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

      • trim object

        Additional properties are allowed.

        Hide trim attributes Show trim attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • target_field string

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

      • uppercase object

        Additional properties are allowed.

        Hide uppercase attributes Show uppercase attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • urldecode object

        Additional properties are allowed.

        Hide urldecode attributes Show urldecode attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • uri_parts object

        Additional properties are allowed.

        Hide uri_parts attributes Show uri_parts attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • keep_original boolean

          If true, the processor copies the unparsed URI to <target_field>.original.

        • remove_if_successful boolean

          If true, the processor removes the field after parsing the URI string. If parsing fails, the processor does not remove the field.

        • target_field string

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

      • user_agent object

        Additional properties are allowed.

        Hide user_agent attributes Show user_agent attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • regex_file string

          The name of the file in the config/ingest-user-agent directory containing the regular expressions for parsing the user agent string. Both the directory and the file have to be created before starting Elasticsearch. If not specified, ingest-user-agent will use the regexes.yaml from uap-core it ships with.

        • target_field string

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

        • properties array[string]

          Controls what properties are added to target_field.

          Values are name, os, device, original, or version.

        • extract_device_type boolean Beta

          Extracts device type from the user agent string on a best-effort basis.

    • processors array[object]

      Processors used to perform transformations on documents before indexing. Processors run sequentially in the order specified.

      Hide processors attributes Show processors attributes object
      • append object

        Additional properties are allowed.

        Hide append attributes Show append attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • value object Required

          Additional properties are allowed.

        • allow_duplicates boolean

          If false, the processor does not append values already present in the field.

      • attachment object

        Additional properties are allowed.

        Hide attachment attributes Show attachment attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • indexed_chars number

          The number of chars being used for extraction to prevent huge fields. Use -1 for no limit.

        • indexed_chars_field string

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

        • properties array[string]

          Array of properties to select to be stored. Can be content, title, name, author, keywords, date, content_type, content_length, language.

        • target_field string

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

        • remove_binary boolean

          If true, the binary field will be removed from the document

        • resource_name string

          Field containing the name of the resource to decode. If specified, the processor passes this resource name to the underlying Tika library to enable Resource Name Based Detection.

      • bytes object

        Additional properties are allowed.

        Hide bytes attributes Show bytes attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • circle object

        Additional properties are allowed.

        Hide circle attributes Show circle attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • error_distance number Required

          The difference between the resulting inscribed distance from center to side and the circle’s radius (measured in meters for geo_shape, unit-less for shape).

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • shape_type string Required

          Values are geo_shape or shape.

        • target_field string

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

      • community_id object

        Additional properties are allowed.

        Hide community_id attributes Show community_id attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • source_ip string

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

        • source_port string

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

        • destination_ip string

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

        • destination_port string

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

        • iana_number string

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

        • icmp_type string

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

        • icmp_code string

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

        • transport string

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

        • target_field string

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

        • seed number

          Seed for the community ID hash. Must be between 0 and 65535 (inclusive). The seed can prevent hash collisions between network domains, such as a staging and production network that use the same addressing scheme.

        • ignore_missing boolean

          If true and any required fields are missing, the processor quietly exits without modifying the document.

      • convert object

        Additional properties are allowed.

        Hide convert attributes Show convert attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

        • type string Required

          Values are integer, long, double, float, boolean, ip, string, or auto.

      • csv object

        Additional properties are allowed.

        Hide csv attributes Show csv attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • empty_value object

          Value used to fill empty fields. Empty fields are skipped if this is not provided. An empty field is one with no value (2 consecutive separators) or empty quotes ("").

          Additional properties are allowed.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • quote string

          Quote used in CSV, has to be single character string.

        • separator string

          Separator used in CSV, has to be single character string.

        • target_fields string | array[string] Required
        • trim boolean

          Trim whitespaces in unquoted fields.

      • date object

        Additional properties are allowed.

        Hide date attributes Show date attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • formats array[string] Required

          An array of the expected date formats. Can be a java time pattern or one of the following formats: ISO8601, UNIX, UNIX_MS, or TAI64N.

        • locale string

          The locale to use when parsing the date, relevant when parsing month names or week days. Supports template snippets.

        • target_field string

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

        • timezone string

          The timezone to use when parsing the date. Supports template snippets.

        • output_format string

          The format to use when writing the date to target_field. Must be a valid java time pattern.

      • date_index_name object

        Additional properties are allowed.

        Hide date_index_name attributes Show date_index_name attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • date_formats array[string]

          An array of the expected date formats for parsing dates / timestamps in the document being preprocessed. Can be a java time pattern or one of the following formats: ISO8601, UNIX, UNIX_MS, or TAI64N.

        • date_rounding string Required

          How to round the date when formatting the date into the index name. Valid values are: y (year), M (month), w (week), d (day), h (hour), m (minute) and s (second). Supports template snippets.

        • field string Required

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

        • index_name_format string

          The format to be used when printing the parsed date into the index name. A valid java time pattern is expected here. Supports template snippets.

        • index_name_prefix string

          A prefix of the index name to be prepended before the printed date. Supports template snippets.

        • locale string

          The locale to use when parsing the date from the document being preprocessed, relevant when parsing month names or week days.

        • timezone string

          The timezone to use when parsing the date and when date math index supports resolves expressions into concrete index names.

      • dissect object

        Additional properties are allowed.

        Hide dissect attributes Show dissect attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • append_separator string

          The character(s) that separate the appended fields.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • pattern string Required

          The pattern to apply to the field.

      • dot_expander object

        Additional properties are allowed.

        Hide dot_expander attributes Show dot_expander attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • override boolean

          Controls the behavior when there is already an existing nested object that conflicts with the expanded field. When false, the processor will merge conflicts by combining the old and the new values into an array. When true, the value from the expanded field will overwrite the existing value.

        • path string

          The field that contains the field to expand. Only required if the field to expand is part another object field, because the field option can only understand leaf fields.

      • drop object

        Additional properties are allowed.

        Hide drop attributes Show drop attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

      • enrich object

        Additional properties are allowed.

        Hide enrich attributes Show enrich attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • max_matches number

          The maximum number of matched documents to include under the configured target field. The target_field will be turned into a json array if max_matches is higher than 1, otherwise target_field will become a json object. In order to avoid documents getting too large, the maximum allowed value is 128.

        • override boolean

          If processor will update fields with pre-existing non-null-valued field. When set to false, such fields will not be touched.

        • policy_name string Required

          The name of the enrich policy to use.

        • shape_relation string

          Values are intersects, disjoint, within, or contains.

        • target_field string Required

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

      • fail object

        Additional properties are allowed.

        Hide fail attributes Show fail attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • message string Required

          The error message thrown by the processor. Supports template snippets.

      • fingerprint object

        Additional properties are allowed.

        Hide fingerprint attributes Show fingerprint attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • fields string | array[string] Required
        • target_field string

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

        • salt string

          Salt value for the hash function.

        • method string

          Values are MD5, SHA-1, SHA-256, SHA-512, or MurmurHash3.

        • ignore_missing boolean

          If true, the processor ignores any missing fields. If all fields are missing, the processor silently exits without modifying the document.

      • foreach object

        Additional properties are allowed.

        Hide foreach attributes Show foreach attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true, the processor silently exits without changing the document if the field is null or missing.

        • processor object Required

          Additional properties are allowed.

      • ip_location object

        Additional properties are allowed.

        Hide ip_location attributes Show ip_location attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • database_file string

          The database filename referring to a database the module ships with (GeoLite2-City.mmdb, GeoLite2-Country.mmdb, or GeoLite2-ASN.mmdb) or a custom database in the ingest-geoip config directory.

        • field string Required

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

        • first_only boolean

          If true, only the first found IP location data will be returned, even if the field contains an array.

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • properties array[string]

          Controls what properties are added to the target_field based on the IP location lookup.

        • target_field string

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

        • download_database_on_pipeline_creation boolean

          If true (and if ingest.geoip.downloader.eager.download is false), the missing database is downloaded when the pipeline is created. Else, the download is triggered by when the pipeline is used as the default_pipeline or final_pipeline in an index.

      • geo_grid object

        Additional properties are allowed.

        Hide geo_grid attributes Show geo_grid attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

          The field to interpret as a geo-tile.= The field format is determined by the tile_type.

        • tile_type string Required

          Values are geotile, geohex, or geohash.

        • target_field string

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

        • parent_field string

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

        • children_field string

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

        • non_children_field string

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

        • precision_field string

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • target_format string

          Values are geojson or wkt.

      • geoip object

        Additional properties are allowed.

        Hide geoip attributes Show geoip attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • database_file string

          The database filename referring to a database the module ships with (GeoLite2-City.mmdb, GeoLite2-Country.mmdb, or GeoLite2-ASN.mmdb) or a custom database in the ingest-geoip config directory.

        • field string Required

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

        • first_only boolean

          If true, only the first found geoip data will be returned, even if the field contains an array.

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • properties array[string]

          Controls what properties are added to the target_field based on the geoip lookup.

        • target_field string

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

        • download_database_on_pipeline_creation boolean

          If true (and if ingest.geoip.downloader.eager.download is false), the missing database is downloaded when the pipeline is created. Else, the download is triggered by when the pipeline is used as the default_pipeline or final_pipeline in an index.

      • grok object

        Additional properties are allowed.

        Hide grok attributes Show grok attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • ecs_compatibility string

          Must be disabled or v1. If v1, the processor uses patterns with Elastic Common Schema (ECS) field names.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • pattern_definitions object

          A map of pattern-name and pattern tuples defining custom patterns to be used by the current processor. Patterns matching existing names will override the pre-existing definition.

          Hide pattern_definitions attribute Show pattern_definitions attribute object
          • * string Additional properties
        • patterns array[string] Required

          An ordered list of grok expression to match and extract named captures with. Returns on the first expression in the list that matches.

        • trace_match boolean

          When true, _ingest._grok_match_index will be inserted into your matched document’s metadata with the index into the pattern found in patterns that matched.

      • gsub object

        Additional properties are allowed.

        Hide gsub attributes Show gsub attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • pattern string Required

          The pattern to be replaced.

        • replacement string Required

          The string to replace the matching patterns with.

        • target_field string

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

      • html_strip object

        Additional properties are allowed.

        Hide html_strip attributes Show html_strip attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document,

        • target_field string

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

      • inference object

        Additional properties are allowed.

        Hide inference attributes Show inference attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • model_id string Required
        • target_field string

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

        • field_map object

          Maps the document field names to the known field names of the model. This mapping takes precedence over any default mappings provided in the model configuration.

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

            Additional properties are allowed.

        • inference_config object

          Additional properties are allowed.

          Hide inference_config attributes Show inference_config attributes object
      • join object

        Additional properties are allowed.

        Hide join attributes Show join attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • separator string Required

          The separator character.

        • target_field string

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

      • json object

        Additional properties are allowed.

        Hide json attributes Show json attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • add_to_root boolean

          Flag that forces the parsed JSON to be added at the top level of the document. target_field must not be set when this option is chosen.

        • add_to_root_conflict_strategy string

          Values are replace or merge.

        • allow_duplicate_keys boolean

          When set to true, the JSON parser will not fail if the JSON contains duplicate keys. Instead, the last encountered value for any duplicate key wins.

        • field string Required

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

        • target_field string

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

      • kv object

        Additional properties are allowed.

        Hide kv attributes Show kv attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • exclude_keys array[string]

          List of keys to exclude from document.

        • field string Required

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

        • field_split string Required

          Regex pattern to use for splitting key-value pairs.

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • include_keys array[string]

          List of keys to filter and insert into document. Defaults to including all keys.

        • prefix string

          Prefix to be added to extracted keys.

        • strip_brackets boolean

          If true. strip brackets (), <>, [] as well as quotes ' and " from extracted values.

        • target_field string

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

        • trim_key string

          String of characters to trim from extracted keys.

        • trim_value string

          String of characters to trim from extracted values.

        • value_split string Required

          Regex pattern to use for splitting the key from the value within a key-value pair.

      • lowercase object

        Additional properties are allowed.

        Hide lowercase attributes Show lowercase attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • network_direction object

        Additional properties are allowed.

        Hide network_direction attributes Show network_direction attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • source_ip string

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

        • destination_ip string

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

        • target_field string

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

        • internal_networks array[string]

          List of internal networks. Supports IPv4 and IPv6 addresses and ranges in CIDR notation. Also supports the named ranges listed below. These may be constructed with template snippets. Must specify only one of internal_networks or internal_networks_field.

        • internal_networks_field string

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

        • ignore_missing boolean

          If true and any required fields are missing, the processor quietly exits without modifying the document.

      • pipeline object

        Additional properties are allowed.

        Hide pipeline attributes Show pipeline attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • name string Required
        • ignore_missing_pipeline boolean

          Whether to ignore missing pipelines instead of failing.

      • redact object

        Additional properties are allowed.

        Hide redact attributes Show redact attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • patterns array[string] Required

          A list of grok expressions to match and redact named captures with

        • pattern_definitions object
          Hide pattern_definitions attribute Show pattern_definitions attribute object
          • * string Additional properties
        • prefix string

          Start a redacted section with this token

        • suffix string

          End a redacted section with this token

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • skip_if_unlicensed boolean

          If true and the current license does not support running redact processors, then the processor quietly exits without modifying the document

        • trace_redact boolean

          If true then ingest metadata _ingest._redact._is_redacted is set to true if the document has been redacted

      • registered_domain object

        Additional properties are allowed.

        Hide registered_domain attributes Show registered_domain attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • target_field string

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

        • ignore_missing boolean

          If true and any required fields are missing, the processor quietly exits without modifying the document.

      • remove object

        Additional properties are allowed.

        Hide remove attributes Show remove attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string | array[string] Required
        • keep string | array[string]
        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

      • rename object

        Additional properties are allowed.

        Hide rename attributes Show rename attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • target_field string Required

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

      • reroute object

        Additional properties are allowed.

        Hide reroute attributes Show reroute attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • destination string

          A static value for the target. Can’t be set when the dataset or namespace option is set.

        • dataset string
        • namespace string
      • script object

        Additional properties are allowed.

        Hide script attributes Show script attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • id string
        • lang string

          Script language.

        • params object

          Object containing parameters for the script.

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

            Additional properties are allowed.

        • source string

          Inline script. If no id is specified, this parameter is required.

      • set object

        Additional properties are allowed.

        Hide set attributes Show set attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • copy_from string

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

        • field string Required

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

        • ignore_empty_value boolean

          If true and value is a template snippet that evaluates to null or the empty string, the processor quietly exits without modifying the document.

        • media_type string

          The media type for encoding value. Applies only when value is a template snippet. Must be one of application/json, text/plain, or application/x-www-form-urlencoded.

        • override boolean

          If true processor will update fields with pre-existing non-null-valued field. When set to false, such fields will not be touched.

        • value object

          The value to be set for the field. Supports template snippets. May specify only one of value or copy_from.

          Additional properties are allowed.

      • set_security_user object

        Additional properties are allowed.

        Hide set_security_user attributes Show set_security_user attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • properties array[string]

          Controls what user related properties are added to the field.

      • sort object

        Additional properties are allowed.

        Hide sort attributes Show sort attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • order string

          Values are asc or desc.

        • target_field string

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

      • split object

        Additional properties are allowed.

        Hide split attributes Show split attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • preserve_trailing boolean

          Preserves empty trailing fields, if any.

        • separator string Required

          A regex which matches the separator, for example, , or \s+.

        • target_field string

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

      • terminate object

        Additional properties are allowed.

        Hide terminate attributes Show terminate attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

      • trim object

        Additional properties are allowed.

        Hide trim attributes Show trim attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • target_field string

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

      • uppercase object

        Additional properties are allowed.

        Hide uppercase attributes Show uppercase attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • urldecode object

        Additional properties are allowed.

        Hide urldecode attributes Show urldecode attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist or is null, the processor quietly exits without modifying the document.

        • target_field string

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

      • uri_parts object

        Additional properties are allowed.

        Hide uri_parts attributes Show uri_parts attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • keep_original boolean

          If true, the processor copies the unparsed URI to <target_field>.original.

        • remove_if_successful boolean

          If true, the processor removes the field after parsing the URI string. If parsing fails, the processor does not remove the field.

        • target_field string

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

      • user_agent object

        Additional properties are allowed.

        Hide user_agent attributes Show user_agent attributes object
        • description string

          Description of the processor. Useful for describing the purpose of the processor or its configuration.

        • if object

          Additional properties are allowed.

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

          • lang
          • options object
        • ignore_failure boolean

          Ignore failures for the processor.

        • on_failure array[object]

          Handle failures for the processor.

          Additional properties are allowed.

        • tag string

          Identifier for the processor. Useful for debugging and metrics.

        • field string Required

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

        • ignore_missing boolean

          If true and field does not exist, the processor quietly exits without modifying the document.

        • regex_file string

          The name of the file in the config/ingest-user-agent directory containing the regular expressions for parsing the user agent string. Both the directory and the file have to be created before starting Elasticsearch. If not specified, ingest-user-agent will use the regexes.yaml from uap-core it ships with.

        • target_field string

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

        • properties array[string]

          Controls what properties are added to target_field.

          Values are name, os, device, original, or version.

        • extract_device_type boolean Beta

          Extracts device type from the user agent string on a best-effort basis.

    • version number
    • deprecated boolean

      Marks this ingest pipeline as deprecated. When a deprecated ingest pipeline is referenced as the default or final pipeline when creating or updating a non-deprecated index template, Elasticsearch will emit a deprecation warning.

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

        Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • docs array[object] Required
      Hide docs attributes Show docs attributes object
      • doc object

        Additional properties are allowed.

        Hide doc attributes Show doc attributes object
        • _id string Required
        • _index string Required
        • _ingest object Required

          Additional properties are allowed.

          Hide _ingest attributes Show _ingest attributes object
        • _routing string

          Value used to send the document to a specific primary shard.

        • _source object Required

          JSON body for the document.

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

            Additional properties are allowed.

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

          One of:
          _types:VersionNumber number _spec_utils:StringifiedVersionNumber string
        • _version_type string

          Values are internal, external, external_gte, or force.

      • error object

        Additional properties are allowed.

        Hide error attributes Show error attributes object
        • type string Required

          The type of error

        • reason string

          A human-readable explanation of the error, in English.

        • stack_trace string

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

        • caused_by object

          Additional properties are allowed.

        • root_cause array[object]

          Additional properties are allowed.

        • suppressed array[object]

          Additional properties are allowed.

      • processor_results array[object]
        Hide processor_results attributes Show processor_results attributes object
        • doc object

          Additional properties are allowed.

          Hide doc attributes Show doc attributes object
        • tag string
        • processor_type string
        • status string

          Values are success, failure, simulated, or throttled.

        • description string
        • ignored_error object

          Additional properties are allowed.

          Hide ignored_error attributes Show ignored_error attributes object
          • type string Required

            The type of error

          • reason string

            A human-readable explanation of the error, in English.

          • stack_trace string

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

          • caused_by object

            Additional properties are allowed.

          • root_cause array[object]
          • suppressed array[object]
        • error object

          Additional properties are allowed.

          Hide error attributes Show error attributes object
          • type string Required

            The type of error

          • reason string

            A human-readable explanation of the error, in English.

          • stack_trace string

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

          • caused_by object

            Additional properties are allowed.

          • root_cause array[object]
          • suppressed array[object]
POST /_ingest/pipeline/_simulate 
curl \
 --request POST http://api.example.com/_ingest/pipeline/_simulate \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"pipeline\" :\n  {\n    \"description\": \"_description\",\n    \"processors\": [\n      {\n        \"set\" : {\n          \"field\" : \"field2\",\n          \"value\" : \"_value\"\n        }\n      }\n    ]\n  },\n  \"docs\": [\n    {\n      \"_index\": \"index\",\n      \"_id\": \"id\",\n      \"_source\": {\n        \"foo\": \"bar\"\n      }\n    },\n    {\n      \"_index\": \"index\",\n      \"_id\": \"id\",\n      \"_source\": {\n        \"foo\": \"rab\"\n      }\n    }\n  ]\n}"'
Request example
You can specify the used pipeline either in the request body or as a path parameter. 
{
  "pipeline" :
  {
    "description": "_description",
    "processors": [
      {
        "set" : {
          "field" : "field2",
          "value" : "_value"
        }
      }
    ]
  },
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}
Response examples (200)
A successful response for running an ingest pipeline against a set of provided documents. 
{
   "docs": [
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "bar"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.187Z"
            }
         }
      },
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "rab"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.188Z"
            }
         }
      }
   ]
}

Get Logstash pipelines Added in 7.12.0

GET /_logstash/pipeline/{id}
Api key auth

Get pipelines that are used for Logstash Central Management.

External documentation

Path parameters

  • id string | array[string] Required

    A comma-separated list of pipeline identifiers.

Responses

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • description string Required

        A description of the pipeline. This description is not used by Elasticsearch or Logstash.

      • last_modified string | number Required

        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.

        One of:
        _types:DateTime string _types:UnitMillis number
      • pipeline string Required

        The configuration for the pipeline.

        External documentation
      • pipeline_metadata object Required

        Additional properties are allowed.

        Hide pipeline_metadata attributes Show pipeline_metadata attributes object
      • pipeline_settings object Required

        Additional properties are allowed.

        Hide pipeline_settings attributes Show pipeline_settings attributes object
        • pipeline.workers number Required

          The number of workers that will, in parallel, execute the filter and output stages of the pipeline.

        • pipeline.batch.size number Required

          The maximum number of events an individual worker thread will collect from inputs before attempting to execute its filters and outputs.

        • pipeline.batch.delay number Required

          When creating pipeline event batches, how long in milliseconds to wait for each event before dispatching an undersized batch to pipeline workers.

        • queue.type string Required

          The internal queuing model to use for event buffering.

        • queue.max_bytes.number number Required

          The total capacity of the queue (queue.type: persisted) in number of bytes.

        • queue.max_bytes.units string Required

          The total capacity of the queue (queue.type: persisted) in terms of units of bytes.

        • queue.checkpoint.writes number Required

          The maximum number of written events before forcing a checkpoint when persistent queues are enabled (queue.type: persisted).

      • username string Required

        The user who last updated the pipeline.
GET /_logstash/pipeline/{id} 
curl \
 --request GET http://api.example.com/_logstash/pipeline/{id} \
 --header "Authorization: $API_KEY"

Get datafeeds configuration info Added in 5.5.0

GET /_ml/datafeeds/{datafeed_id}
Api key auth

You can get information for multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a wildcard expression. You can get information for all datafeeds by using _all, by specifying * as the <feed_id>, or by omitting the <feed_id>. This API returns a maximum of 10,000 datafeeds.

Path parameters

  • datafeed_id string | array[string] Required

    Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the API returns information about all datafeeds.

Query parameters

  • allow_no_match boolean

    Specifies what to do when the request:

    1. Contains wildcard expressions and there are no datafeeds that match.
    2. Contains the _all string or no identifiers and there are no matches.
    3. Contains wildcard expressions and there are only partial matches.

    The default value is true, which returns an empty datafeeds array when there are no matches and the subset of results when there are partial matches. If this parameter is false, the request returns a 404 status code when there are no matches or only partial matches.

  • exclude_generated boolean

    Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required
    • datafeeds array[object] Required
      Hide datafeeds attributes Show datafeeds attributes object
      • aggregations object
      • authorization object

        Additional properties are allowed.

        Hide authorization attributes Show authorization attributes object
        • api_key object

          Additional properties are allowed.

          Hide api_key attributes Show api_key attributes object
          • id string Required

            The identifier for the API key.

          • name string Required

            The name of the API key.

        • roles array[string]

          If a user ID was used for the most recent update to the datafeed, its roles at the time of the update are listed in the response.

        • service_account string

          If a service account was used for the most recent update to the datafeed, the account name is listed in the response.

      • chunking_config object

        Additional properties are allowed.

        Hide chunking_config attributes Show chunking_config attributes object
        • mode string Required

          Values are auto, manual, or off.

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

      • datafeed_id string Required
      • frequency 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.

      • indices array[string] Required
      • indexes array[string]
      • job_id string Required
      • max_empty_searches number
      • query_delay 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.

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

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            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.

            • lang
            • options object
          • ignore_failure boolean
      • scroll_size number
      • delayed_data_check_config object Required

        Additional properties are allowed.

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

        • enabled boolean Required

          Specifies whether the datafeed periodically checks for delayed data.

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

          • fetch_fields array[object]

            For type lookup

            Additional properties are allowed.

          • format string

            A custom format for date type runtime fields.

          • input_field string

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

          • target_field string

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

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

            • lang
            • options object
          • type string Required

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

      • indices_options object

        Additional properties are allowed.

        Hide indices_options attributes Show indices_options attributes object
        • allow_no_indices boolean

          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]
        • ignore_unavailable boolean

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

        • ignore_throttled boolean

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

      • query object Required

        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": {"boost": 1}}.

        Additional properties are allowed.

        Query DSL
GET /_ml/datafeeds/{datafeed_id} 
curl \
 --request GET http://api.example.com/_ml/datafeeds/{datafeed_id} \
 --header "Authorization: $API_KEY"

Get overall bucket results Added in 6.1.0

GET /_ml/anomaly_detectors/{job_id}/results/overall_buckets
Api key auth

Retrievs overall bucket results that summarize the bucket results of multiple anomaly detection jobs.

The overall_score is calculated by combining the scores of all the buckets within the overall bucket span. First, the maximum anomaly_score per anomaly detection job in the overall bucket is calculated. Then the top_n of those scores are averaged to result in the overall_score. This means that you can fine-tune the overall_score so that it is more or less sensitive to the number of jobs that detect an anomaly at the same time. For example, if you set top_n to 1, the overall_score is the maximum bucket score in the overall bucket. Alternatively, if you set top_n to the number of jobs, the overall_score is high only when all jobs detect anomalies in that overall bucket. If you set the bucket_span parameter (to a value greater than its default), the overall_score is the maximum overall_score of the overall buckets that have a span equal to the jobs' largest bucket span.

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression.

    You can summarize the bucket results for all anomaly detection jobs by using _all or by specifying * as the <job_id>.

Query parameters

  • allow_no_match boolean

    Specifies what to do when the request:

    1. Contains wildcard expressions and there are no jobs that match.
    2. Contains the _all string or no identifiers and there are no matches.
    3. Contains wildcard expressions and there are only partial matches.

    If true, the request returns an empty jobs array when there are no matches and the subset of results when there are partial matches. If this parameter is false, the request returns a 404 status code when there are no matches or only partial matches.

  • bucket_span string

    The span of the overall buckets. Must be greater or equal to the largest bucket span of the specified anomaly detection jobs, which is the default value.

    By default, an overall bucket has a span equal to the largest bucket span of the specified anomaly detection jobs. To override that behavior, use the optional bucket_span parameter.

  • end string | number

    Returns overall buckets with timestamps earlier than this time.

  • exclude_interim boolean

    If true, the output excludes interim results.

  • overall_score number | string

    Returns overall buckets with overall scores greater than or equal to this value.

  • start string | number

    Returns overall buckets with timestamps after this time.

  • top_n number

    The number of top anomaly detection job bucket scores to be used in the overall_score calculation.

application/json

Body

  • allow_no_match boolean

    Refer to the description for the allow_no_match query parameter.

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

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

    One of:
    _types:DateTime string _types:UnitMillis number
  • exclude_interim boolean

    Refer to the description for the exclude_interim query parameter.

  • overall_score number | string

    Refer to the description for the overall_score query parameter.

    One of:
    number-1 number string-2 string

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

    One of:
    _types:DateTime string _types:UnitMillis number
  • top_n number

    Refer to the description for the top_n query parameter.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required
    • overall_buckets array[object] Required

      Array of overall bucket objects

      Hide overall_buckets attributes Show overall_buckets attributes object
      • bucket_span number

        Time unit for seconds

      • is_interim boolean Required

        If true, this is an interim result. In other words, the results are calculated based on partial input data.

      • jobs array[object] Required

        An array of objects that contain the max_anomaly_score per job_id.

        Hide jobs attributes Show jobs attributes object
      • overall_score number Required

        The top_n average of the maximum bucket anomaly_score per job.

      • result_type string Required

        Internal. This is always set to overall_bucket.

      • timestamp number

        Time unit for milliseconds

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

        One of:
        _types:DateTime string _types:UnitMillis number
GET /_ml/anomaly_detectors/{job_id}/results/overall_buckets 
curl \
 --request GET http://api.example.com/_ml/anomaly_detectors/{job_id}/results/overall_buckets \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"allow_no_match":true,"bucket_span":"string","":"string","exclude_interim":true,"overall_score":42.0,"top_n":42.0}'

Preview a datafeed Added in 5.4.0

GET /_ml/datafeeds/{datafeed_id}/_preview
Api key auth

This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. You can also use secondary authorization headers to supply the credentials.

Path parameters

  • datafeed_id string Required

    A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters. NOTE: If you use this path parameter, you cannot provide datafeed or anomaly detection job configuration details in the request body.

Query parameters

  • start string | number

    The start time from where the datafeed preview should begin

  • end string | number

    The end time when the datafeed preview should stop

application/json

Body

  • datafeed_config object

    Additional properties are allowed.

    Hide datafeed_config attributes Show datafeed_config attributes object
    • aggregations object

      If set, the datafeed performs aggregation searches. Support for aggregations is limited and should be used only with low cardinality data.

    • chunking_config object

      Additional properties are allowed.

      Hide chunking_config attributes Show chunking_config attributes object
      • mode string Required

        Values are auto, manual, or off.

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

    • datafeed_id string
    • delayed_data_check_config object

      Additional properties are allowed.

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

      • enabled boolean Required

        Specifies whether the datafeed periodically checks for delayed data.

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

    • indices string | array[string]
    • indices_options object

      Additional properties are allowed.

      Hide indices_options attributes Show indices_options attributes object
      • allow_no_indices boolean

        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]
      • ignore_unavailable boolean

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

      • ignore_throttled boolean

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

    • job_id string
    • max_empty_searches number

      If a real-time datafeed has never seen any data (including during any initial training period) then it will automatically stop itself and close its associated job after this many real-time searches that return no documents. In other words, it will stop after frequency times max_empty_searches of real-time operation. If not set then a datafeed with no end time that sees no data will remain started until it is explicitly stopped.

    • query object

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

      Additional properties are allowed.

      External documentation
    • query_delay 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.

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

        • input_field string

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

        • target_field string

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

        • target_index string
        • 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:
            _types:ScriptLanguage string _types:ScriptLanguage string

            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.

    • script_fields object

      Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields.

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

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • script object Required

          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:
            _types:ScriptLanguage string _types:ScriptLanguage string

            Values are painless, expression, mustache, or java.

          • options object
            Hide options attribute Show options attribute object
            • * string Additional properties
        • ignore_failure boolean
    • scroll_size number

      The size parameter that is used in Elasticsearch searches when the datafeed does not use aggregations. The maximum value is the value of index.max_result_window, which is 10,000 by default.

  • job_config object

    Additional properties are allowed.

    Hide job_config attributes Show job_config attributes object
    • allow_lazy_open boolean

      Advanced configuration option. Specifies whether this job can open when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

    • analysis_config object Required

      Additional properties are allowed.

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

      • categorization_analyzer string | object

        One of:
        _types:CategorizationAnalyzer string _types:CategorizationAnalyzerDefinition object
      • categorization_field_name string

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

      • categorization_filters array[string]

        If categorization_field_name is specified, you can also define optional filters. This property expects an array of regular expressions. The expressions are used to filter out matching sequences from the categorization field values. You can use this functionality to fine tune the categorization by excluding sequences from consideration when categories are defined. For example, you can exclude SQL statements that appear in your log files. This property cannot be used at the same time as categorization_analyzer. If you only want to define simple regular expression filters that are applied prior to tokenization, setting this property is the easiest method. If you also want to customize the tokenizer or post-tokenization filtering, use the categorization_analyzer property instead and include the filters as pattern_replace character filters. The effect is exactly the same.

      • detectors array[object] Required

        Detector configuration objects specify which data fields a job analyzes. They also specify which analytical functions are used. You can specify multiple detectors for a job. If the detectors array does not contain at least one detector, no analysis can occur and an error is returned.

        Hide detectors attributes Show detectors attributes object
        • by_field_name string

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

        • custom_rules array[object]

          Custom rules enable you to customize the way detectors operate. For example, a rule may dictate conditions under which results should be skipped. Kibana refers to custom rules as job rules.

          Hide custom_rules attributes Show custom_rules attributes object
          • actions array[string]

            The set of actions to be triggered when the rule applies. If more than one action is specified the effects of all actions are combined.

            Values are skip_result or skip_model_update.

          • conditions array[object]

            An array of numeric conditions when the rule applies. A rule must either have a non-empty scope or at least one condition. Multiple conditions are combined together with a logical AND.

          • scope object

            A scope of series where the rule applies. A rule must either have a non-empty scope or at least one condition. By default, the scope includes all series. Scoping is allowed for any of the fields that are also specified in by_field_name, over_field_name, or partition_field_name.

        • detector_description string

          A description of the detector.

        • detector_index number

          A unique identifier for the detector. This identifier is based on the order of the detectors in the analysis_config, starting at zero. If you specify a value for this property, it is ignored.

        • exclude_frequent string

          Values are all, none, by, or over.

        • field_name string

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

        • function string

          The analysis function that is used. For example, count, rare, mean, min, max, or sum.

        • over_field_name string

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

        • partition_field_name string

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

        • use_null boolean

          Defines whether a new series is used as the null series when there is no value for the by or partition fields.

      • influencers array[string]

        A comma separated list of influencer field names. Typically these can be the by, over, or partition fields that are used in the detector configuration. You might also want to use a field name that is not specifically named in a detector, but is available as part of the input data. When you use multiple detectors, the use of influencers is recommended as it aggregates results for each influencer entity.

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

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

      • multivariate_by_fields boolean

        This functionality is reserved for internal use. It is not supported for use in customer environments and is not subject to the support SLA of official GA features. If set to true, the analysis will automatically find correlations between metrics for a given by field value and report anomalies when those correlations cease to hold. For example, suppose CPU and memory usage on host A is usually highly correlated with the same metrics on host B. Perhaps this correlation occurs because they are running a load-balanced application. If you enable this property, anomalies will be reported when, for example, CPU usage on host A is high and the value of CPU usage on host B is low. That is to say, you’ll see an anomaly when the CPU of host A is unusual given the CPU of host B. To use the multivariate_by_fields property, you must also specify by_field_name in your detector.

      • per_partition_categorization object

        Additional properties are allowed.

        Hide per_partition_categorization attributes Show per_partition_categorization attributes object
        • enabled boolean

          To enable this setting, you must also set the partition_field_name property to the same value in every detector that uses the keyword mlcategory. Otherwise, job creation fails.

        • stop_on_warn boolean

          This setting can be set to true only if per-partition categorization is enabled. If true, both categorization and subsequent anomaly detection stops for partitions where the categorization status changes to warn. This setting makes it viable to have a job where it is expected that categorization works well for some partitions but not others; you do not pay the cost of bad categorization forever in the partitions where it works badly.

      • summary_count_field_name string

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

    • analysis_limits object

      Additional properties are allowed.

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

    • custom_settings object

      Custom metadata about the job

      Additional properties are allowed.

    • daily_model_snapshot_retention_after_days number

      Advanced configuration option, which affects the automatic removal of old model snapshots for this job. It specifies a period of time (in days) after which only the first snapshot per day is retained. This period is relative to the timestamp of the most recent snapshot for this job.

    • data_description object Required

      Additional properties are allowed.

      Hide data_description attributes Show data_description attributes object
      • format string

        Only JSON format is supported at this time.

      • time_field string

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

      • time_format string

        The time format, which can be epoch, epoch_ms, or a custom pattern. The value epoch refers to UNIX or Epoch time (the number of seconds since 1 Jan 1970). The value epoch_ms indicates that time is measured in milliseconds since the epoch. The epoch and epoch_ms time formats accept either integer or real values. Custom patterns must conform to the Java DateTimeFormatter class. When you use date-time formatting patterns, it is recommended that you provide the full date, time and time zone. For example: yyyy-MM-dd'T'HH:mm:ssX. If the pattern that you specify is not sufficient to produce a complete timestamp, job creation fails.

      • field_delimiter string
    • datafeed_config object

      Additional properties are allowed.

      Hide datafeed_config attributes Show datafeed_config attributes object
      • aggregations object

        If set, the datafeed performs aggregation searches. Support for aggregations is limited and should be used only with low cardinality data.

      • chunking_config object

        Additional properties are allowed.

        Hide chunking_config attributes Show chunking_config attributes object
        • mode string Required

          Values are auto, manual, or off.

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

      • datafeed_id string
      • delayed_data_check_config object

        Additional properties are allowed.

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

        • enabled boolean Required

          Specifies whether the datafeed periodically checks for delayed data.

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

      • indices string | array[string]
      • indices_options object

        Additional properties are allowed.

        Hide indices_options attributes Show indices_options attributes object
        • allow_no_indices boolean

          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]
        • ignore_unavailable boolean

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

        • ignore_throttled boolean

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

      • job_id string
      • max_empty_searches number

        If a real-time datafeed has never seen any data (including during any initial training period) then it will automatically stop itself and close its associated job after this many real-time searches that return no documents. In other words, it will stop after frequency times max_empty_searches of real-time operation. If not set then a datafeed with no end time that sees no data will remain started until it is explicitly stopped.

      • query object

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

        Additional properties are allowed.

        External documentation
      • query_delay 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.

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

          • input_field string

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

          • target_field string

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

          • target_index string
          • 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:
              _types:ScriptLanguage string _types:ScriptLanguage string

              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.

      • script_fields object

        Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields.

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

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            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:
              _types:ScriptLanguage string _types:ScriptLanguage string

              Values are painless, expression, mustache, or java.

            • options object
              Hide options attribute Show options attribute object
              • * string Additional properties
          • ignore_failure boolean
      • scroll_size number

        The size parameter that is used in Elasticsearch searches when the datafeed does not use aggregations. The maximum value is the value of index.max_result_window, which is 10,000 by default.

    • description string

      A description of the job.

    • groups array[string]

      A list of job groups. A job can belong to no groups or many.

    • job_id string
    • job_type string

      Reserved for future use, currently set to anomaly_detector.

    • model_plot_config object

      Additional properties are allowed.

      Hide model_plot_config attributes Show model_plot_config attributes object
      • annotations_enabled boolean

        If true, enables calculation and storage of the model change annotations for each entity that is being analyzed.

      • enabled boolean

        If true, enables calculation and storage of the model bounds for each entity that is being analyzed.

      • terms string

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

    • model_snapshot_retention_days number

      Advanced configuration option, which affects the automatic removal of old model snapshots for this job. It specifies the maximum period of time (in days) that snapshots are retained. This period is relative to the timestamp of the most recent snapshot for this job. The default value is 10, which means snapshots ten days older than the newest snapshot are deleted.

    • renormalization_window_days number

      Advanced configuration option. The period over which adjustments to the score are applied, as new data is seen. The default value is the longer of 30 days or 100 bucket_spans.

    • results_index_name string
    • results_retention_days number

      Advanced configuration option. The period of time (in days) that results are retained. Age is calculated relative to the timestamp of the latest bucket result. If this property has a non-null value, once per day at 00:30 (server time), results that are the specified number of days older than the latest bucket result are deleted from Elasticsearch. The default value is null, which means all results are retained. Annotations generated by the system also count as results for retention purposes; they are deleted after the same number of days as results. Annotations added by users are retained forever.

Responses

  • 200 application/json

    Additional properties are allowed.
GET /_ml/datafeeds/{datafeed_id}/_preview 
curl \
 --request GET http://api.example.com/_ml/datafeeds/{datafeed_id}/_preview \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"datafeed_config":{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"datafeed_id":"string","delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"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"}},"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0},"job_config":{"allow_lazy_open":true,"analysis_config":{"bucket_span":"string","":"string","categorization_field_name":"string","categorization_filters":["string"],"detectors":[{"by_field_name":"string","custom_rules":[{"actions":["skip_result"],"conditions":[{}],"scope":{}}],"detector_description":"string","detector_index":42.0,"exclude_frequent":"all","field_name":"string","function":"string","over_field_name":"string","partition_field_name":"string","use_null":true}],"influencers":["string"],"latency":"string","model_prune_window":"string","multivariate_by_fields":true,"per_partition_categorization":{"enabled":true,"stop_on_warn":true},"summary_count_field_name":"string"},"analysis_limits":{"categorization_examples_limit":42.0,"":42.0},"background_persist_interval":"string","custom_settings":{},"daily_model_snapshot_retention_after_days":42.0,"data_description":{"format":"string","time_field":"string","time_format":"string","field_delimiter":"string"},"datafeed_config":{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"datafeed_id":"string","delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"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"}},"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0},"description":"string","groups":["string"],"job_id":"string","job_type":"string","model_plot_config":{"annotations_enabled":true,"enabled":true,"terms":"string"},"model_snapshot_retention_days":42.0,"renormalization_window_days":42.0,"results_index_name":"string","results_retention_days":42.0}}'

Preview a datafeed Added in 5.4.0

POST /_ml/datafeeds/{datafeed_id}/_preview
Api key auth

This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. You can also use secondary authorization headers to supply the credentials.

Path parameters

  • datafeed_id string Required

    A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters. NOTE: If you use this path parameter, you cannot provide datafeed or anomaly detection job configuration details in the request body.

Query parameters

  • start string | number

    The start time from where the datafeed preview should begin

  • end string | number

    The end time when the datafeed preview should stop

application/json

Body

  • datafeed_config object

    Additional properties are allowed.

    Hide datafeed_config attributes Show datafeed_config attributes object
    • aggregations object

      If set, the datafeed performs aggregation searches. Support for aggregations is limited and should be used only with low cardinality data.

    • chunking_config object

      Additional properties are allowed.

      Hide chunking_config attributes Show chunking_config attributes object
      • mode string Required

        Values are auto, manual, or off.

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

    • datafeed_id string
    • delayed_data_check_config object

      Additional properties are allowed.

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

      • enabled boolean Required

        Specifies whether the datafeed periodically checks for delayed data.

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

    • indices string | array[string]
    • indices_options object

      Additional properties are allowed.

      Hide indices_options attributes Show indices_options attributes object
      • allow_no_indices boolean

        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]
      • ignore_unavailable boolean

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

      • ignore_throttled boolean

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

    • job_id string
    • max_empty_searches number

      If a real-time datafeed has never seen any data (including during any initial training period) then it will automatically stop itself and close its associated job after this many real-time searches that return no documents. In other words, it will stop after frequency times max_empty_searches of real-time operation. If not set then a datafeed with no end time that sees no data will remain started until it is explicitly stopped.

    • query object

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

      Additional properties are allowed.

      External documentation
    • query_delay 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.

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

        • input_field string

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

        • target_field string

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

        • target_index string
        • 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:
            _types:ScriptLanguage string _types:ScriptLanguage string

            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.

    • script_fields object

      Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields.

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

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • script object Required

          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:
            _types:ScriptLanguage string _types:ScriptLanguage string

            Values are painless, expression, mustache, or java.

          • options object
            Hide options attribute Show options attribute object
            • * string Additional properties
        • ignore_failure boolean
    • scroll_size number

      The size parameter that is used in Elasticsearch searches when the datafeed does not use aggregations. The maximum value is the value of index.max_result_window, which is 10,000 by default.

  • job_config object

    Additional properties are allowed.

    Hide job_config attributes Show job_config attributes object
    • allow_lazy_open boolean

      Advanced configuration option. Specifies whether this job can open when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

    • analysis_config object Required

      Additional properties are allowed.

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

      • categorization_analyzer string | object

        One of:
        _types:CategorizationAnalyzer string _types:CategorizationAnalyzerDefinition object
      • categorization_field_name string

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

      • categorization_filters array[string]

        If categorization_field_name is specified, you can also define optional filters. This property expects an array of regular expressions. The expressions are used to filter out matching sequences from the categorization field values. You can use this functionality to fine tune the categorization by excluding sequences from consideration when categories are defined. For example, you can exclude SQL statements that appear in your log files. This property cannot be used at the same time as categorization_analyzer. If you only want to define simple regular expression filters that are applied prior to tokenization, setting this property is the easiest method. If you also want to customize the tokenizer or post-tokenization filtering, use the categorization_analyzer property instead and include the filters as pattern_replace character filters. The effect is exactly the same.

      • detectors array[object] Required

        Detector configuration objects specify which data fields a job analyzes. They also specify which analytical functions are used. You can specify multiple detectors for a job. If the detectors array does not contain at least one detector, no analysis can occur and an error is returned.

        Hide detectors attributes Show detectors attributes object
        • by_field_name string

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

        • custom_rules array[object]

          Custom rules enable you to customize the way detectors operate. For example, a rule may dictate conditions under which results should be skipped. Kibana refers to custom rules as job rules.

          Hide custom_rules attributes Show custom_rules attributes object
          • actions array[string]

            The set of actions to be triggered when the rule applies. If more than one action is specified the effects of all actions are combined.

            Values are skip_result or skip_model_update.

          • conditions array[object]

            An array of numeric conditions when the rule applies. A rule must either have a non-empty scope or at least one condition. Multiple conditions are combined together with a logical AND.

          • scope object

            A scope of series where the rule applies. A rule must either have a non-empty scope or at least one condition. By default, the scope includes all series. Scoping is allowed for any of the fields that are also specified in by_field_name, over_field_name, or partition_field_name.

        • detector_description string

          A description of the detector.

        • detector_index number

          A unique identifier for the detector. This identifier is based on the order of the detectors in the analysis_config, starting at zero. If you specify a value for this property, it is ignored.

        • exclude_frequent string

          Values are all, none, by, or over.

        • field_name string

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

        • function string

          The analysis function that is used. For example, count, rare, mean, min, max, or sum.

        • over_field_name string

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

        • partition_field_name string

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

        • use_null boolean

          Defines whether a new series is used as the null series when there is no value for the by or partition fields.

      • influencers array[string]

        A comma separated list of influencer field names. Typically these can be the by, over, or partition fields that are used in the detector configuration. You might also want to use a field name that is not specifically named in a detector, but is available as part of the input data. When you use multiple detectors, the use of influencers is recommended as it aggregates results for each influencer entity.

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

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

      • multivariate_by_fields boolean

        This functionality is reserved for internal use. It is not supported for use in customer environments and is not subject to the support SLA of official GA features. If set to true, the analysis will automatically find correlations between metrics for a given by field value and report anomalies when those correlations cease to hold. For example, suppose CPU and memory usage on host A is usually highly correlated with the same metrics on host B. Perhaps this correlation occurs because they are running a load-balanced application. If you enable this property, anomalies will be reported when, for example, CPU usage on host A is high and the value of CPU usage on host B is low. That is to say, you’ll see an anomaly when the CPU of host A is unusual given the CPU of host B. To use the multivariate_by_fields property, you must also specify by_field_name in your detector.

      • per_partition_categorization object

        Additional properties are allowed.

        Hide per_partition_categorization attributes Show per_partition_categorization attributes object
        • enabled boolean

          To enable this setting, you must also set the partition_field_name property to the same value in every detector that uses the keyword mlcategory. Otherwise, job creation fails.

        • stop_on_warn boolean

          This setting can be set to true only if per-partition categorization is enabled. If true, both categorization and subsequent anomaly detection stops for partitions where the categorization status changes to warn. This setting makes it viable to have a job where it is expected that categorization works well for some partitions but not others; you do not pay the cost of bad categorization forever in the partitions where it works badly.

      • summary_count_field_name string

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

    • analysis_limits object

      Additional properties are allowed.

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

    • custom_settings object

      Custom metadata about the job

      Additional properties are allowed.

    • daily_model_snapshot_retention_after_days number

      Advanced configuration option, which affects the automatic removal of old model snapshots for this job. It specifies a period of time (in days) after which only the first snapshot per day is retained. This period is relative to the timestamp of the most recent snapshot for this job.

    • data_description object Required

      Additional properties are allowed.

      Hide data_description attributes Show data_description attributes object
      • format string

        Only JSON format is supported at this time.

      • time_field string

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

      • time_format string

        The time format, which can be epoch, epoch_ms, or a custom pattern. The value epoch refers to UNIX or Epoch time (the number of seconds since 1 Jan 1970). The value epoch_ms indicates that time is measured in milliseconds since the epoch. The epoch and epoch_ms time formats accept either integer or real values. Custom patterns must conform to the Java DateTimeFormatter class. When you use date-time formatting patterns, it is recommended that you provide the full date, time and time zone. For example: yyyy-MM-dd'T'HH:mm:ssX. If the pattern that you specify is not sufficient to produce a complete timestamp, job creation fails.

      • field_delimiter string
    • datafeed_config object

      Additional properties are allowed.

      Hide datafeed_config attributes Show datafeed_config attributes object
      • aggregations object

        If set, the datafeed performs aggregation searches. Support for aggregations is limited and should be used only with low cardinality data.

      • chunking_config object

        Additional properties are allowed.

        Hide chunking_config attributes Show chunking_config attributes object
        • mode string Required

          Values are auto, manual, or off.

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

      • datafeed_id string
      • delayed_data_check_config object

        Additional properties are allowed.

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

        • enabled boolean Required

          Specifies whether the datafeed periodically checks for delayed data.

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

      • indices string | array[string]
      • indices_options object

        Additional properties are allowed.

        Hide indices_options attributes Show indices_options attributes object
        • allow_no_indices boolean

          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]
        • ignore_unavailable boolean

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

        • ignore_throttled boolean

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

      • job_id string
      • max_empty_searches number

        If a real-time datafeed has never seen any data (including during any initial training period) then it will automatically stop itself and close its associated job after this many real-time searches that return no documents. In other words, it will stop after frequency times max_empty_searches of real-time operation. If not set then a datafeed with no end time that sees no data will remain started until it is explicitly stopped.

      • query object

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

        Additional properties are allowed.

        External documentation
      • query_delay 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.

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

          • input_field string

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

          • target_field string

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

          • target_index string
          • 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:
              _types:ScriptLanguage string _types:ScriptLanguage string

              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.

      • script_fields object

        Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields.

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

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            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:
              _types:ScriptLanguage string _types:ScriptLanguage string

              Values are painless, expression, mustache, or java.

            • options object
              Hide options attribute Show options attribute object
              • * string Additional properties
          • ignore_failure boolean
      • scroll_size number

        The size parameter that is used in Elasticsearch searches when the datafeed does not use aggregations. The maximum value is the value of index.max_result_window, which is 10,000 by default.

    • description string

      A description of the job.

    • groups array[string]

      A list of job groups. A job can belong to no groups or many.

    • job_id string
    • job_type string

      Reserved for future use, currently set to anomaly_detector.

    • model_plot_config object

      Additional properties are allowed.

      Hide model_plot_config attributes Show model_plot_config attributes object
      • annotations_enabled boolean

        If true, enables calculation and storage of the model change annotations for each entity that is being analyzed.

      • enabled boolean

        If true, enables calculation and storage of the model bounds for each entity that is being analyzed.

      • terms string

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

    • model_snapshot_retention_days number

      Advanced configuration option, which affects the automatic removal of old model snapshots for this job. It specifies the maximum period of time (in days) that snapshots are retained. This period is relative to the timestamp of the most recent snapshot for this job. The default value is 10, which means snapshots ten days older than the newest snapshot are deleted.

    • renormalization_window_days number

      Advanced configuration option. The period over which adjustments to the score are applied, as new data is seen. The default value is the longer of 30 days or 100 bucket_spans.

    • results_index_name string
    • results_retention_days number

      Advanced configuration option. The period of time (in days) that results are retained. Age is calculated relative to the timestamp of the latest bucket result. If this property has a non-null value, once per day at 00:30 (server time), results that are the specified number of days older than the latest bucket result are deleted from Elasticsearch. The default value is null, which means all results are retained. Annotations generated by the system also count as results for retention purposes; they are deleted after the same number of days as results. Annotations added by users are retained forever.

Responses

  • 200 application/json

    Additional properties are allowed.
POST /_ml/datafeeds/{datafeed_id}/_preview 
curl \
 --request POST http://api.example.com/_ml/datafeeds/{datafeed_id}/_preview \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"datafeed_config":{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"datafeed_id":"string","delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"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"}},"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0},"job_config":{"allow_lazy_open":true,"analysis_config":{"bucket_span":"string","":"string","categorization_field_name":"string","categorization_filters":["string"],"detectors":[{"by_field_name":"string","custom_rules":[{"actions":["skip_result"],"conditions":[{}],"scope":{}}],"detector_description":"string","detector_index":42.0,"exclude_frequent":"all","field_name":"string","function":"string","over_field_name":"string","partition_field_name":"string","use_null":true}],"influencers":["string"],"latency":"string","model_prune_window":"string","multivariate_by_fields":true,"per_partition_categorization":{"enabled":true,"stop_on_warn":true},"summary_count_field_name":"string"},"analysis_limits":{"categorization_examples_limit":42.0,"":42.0},"background_persist_interval":"string","custom_settings":{},"daily_model_snapshot_retention_after_days":42.0,"data_description":{"format":"string","time_field":"string","time_format":"string","field_delimiter":"string"},"datafeed_config":{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"datafeed_id":"string","delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"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"}},"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0},"description":"string","groups":["string"],"job_id":"string","job_type":"string","model_plot_config":{"annotations_enabled":true,"enabled":true,"terms":"string"},"model_snapshot_retention_days":42.0,"renormalization_window_days":42.0,"results_index_name":"string","results_retention_days":42.0}}'

Update an anomaly detection job Added in 5.5.0

POST /_ml/anomaly_detectors/{job_id}/_update
Api key auth

Updates certain properties of an anomaly detection job.

Path parameters

  • job_id string Required

    Identifier for the job.

application/json

Body Required

  • allow_lazy_open boolean

    Advanced configuration option. Specifies whether this job can open when there is insufficient machine learning node capacity for it to be immediately assigned to a node. If false and a machine learning node with capacity to run the job cannot immediately be found, the open anomaly detection jobs API returns an error. However, this is also subject to the cluster-wide xpack.ml.max_lazy_ml_nodes setting. If this option is set to true, the open anomaly detection jobs API does not return an error and the job waits in the opening state until sufficient machine learning node capacity is available.

  • analysis_limits object

    Additional properties are allowed.

    Hide analysis_limits attribute Show analysis_limits attribute object
    • model_memory_limit string Required

      Limits can be applied for the resources required to hold the mathematical models in memory. These limits are approximate and can be set per job. They do not control the memory used by other processes, for example the Elasticsearch Java processes.

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

  • custom_settings object

    Advanced configuration option. Contains custom meta data about the job. For example, it can contain custom URL information as shown in Adding custom URLs to machine learning results.

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

      Additional properties are allowed.

  • categorization_filters array[string]
  • description string

    A description of the job.

  • model_plot_config object

    Additional properties are allowed.

    Hide model_plot_config attributes Show model_plot_config attributes object
    • annotations_enabled boolean

      If true, enables calculation and storage of the model change annotations for each entity that is being analyzed.

    • enabled boolean

      If true, enables calculation and storage of the model bounds for each entity that is being analyzed.

    • terms string

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

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

  • daily_model_snapshot_retention_after_days number

    Advanced configuration option, which affects the automatic removal of old model snapshots for this job. It specifies a period of time (in days) after which only the first snapshot per day is retained. This period is relative to the timestamp of the most recent snapshot for this job. Valid values range from 0 to model_snapshot_retention_days. For jobs created before version 7.8.0, the default value matches model_snapshot_retention_days.

  • model_snapshot_retention_days number

    Advanced configuration option, which affects the automatic removal of old model snapshots for this job. It specifies the maximum period of time (in days) that snapshots are retained. This period is relative to the timestamp of the most recent snapshot for this job.

  • renormalization_window_days number

    Advanced configuration option. The period over which adjustments to the score are applied, as new data is seen.

  • results_retention_days number

    Advanced configuration option. The period of time (in days) that results are retained. Age is calculated relative to the timestamp of the latest bucket result. If this property has a non-null value, once per day at 00:30 (server time), results that are the specified number of days older than the latest bucket result are deleted from Elasticsearch. The default value is null, which means all results are retained.

  • groups array[string]

    A list of job groups. A job can belong to no groups or many.

  • detectors array[object]

    An array of detector update objects.

    Hide detectors attributes Show detectors attributes object
    • detector_index number Required

      A unique identifier for the detector. This identifier is based on the order of the detectors in the analysis_config, starting at zero.

    • description string

      A description of the detector.

    • custom_rules array[object]

      An array of custom rule objects, which enable you to customize the way detectors operate. For example, a rule may dictate to the detector conditions under which results should be skipped. Kibana refers to custom rules as job rules.

      Hide custom_rules attributes Show custom_rules attributes object
      • actions array[string]

        The set of actions to be triggered when the rule applies. If more than one action is specified the effects of all actions are combined.

        Values are skip_result or skip_model_update.

      • conditions array[object]

        An array of numeric conditions when the rule applies. A rule must either have a non-empty scope or at least one condition. Multiple conditions are combined together with a logical AND.

        Hide conditions attributes Show conditions attributes object
        • applies_to string Required

          Values are actual, typical, diff_from_typical, or time.

        • operator string Required

          Values are gt, gte, lt, or lte.

        • value number Required

          The value that is compared against the applies_to field using the operator.

      • scope object

        A scope of series where the rule applies. A rule must either have a non-empty scope or at least one condition. By default, the scope includes all series. Scoping is allowed for any of the fields that are also specified in by_field_name, over_field_name, or partition_field_name.

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

          Additional properties are allowed.

          Hide * attributes Show * attributes object
  • per_partition_categorization object

    Additional properties are allowed.

    Hide per_partition_categorization attributes Show per_partition_categorization attributes object
    • enabled boolean

      To enable this setting, you must also set the partition_field_name property to the same value in every detector that uses the keyword mlcategory. Otherwise, job creation fails.

    • stop_on_warn boolean

      This setting can be set to true only if per-partition categorization is enabled. If true, both categorization and subsequent anomaly detection stops for partitions where the categorization status changes to warn. This setting makes it viable to have a job where it is expected that categorization works well for some partitions but not others; you do not pay the cost of bad categorization forever in the partitions where it works badly.

Responses

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

      Additional properties are allowed.

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

      • categorization_analyzer string | object

        One of:
        _types:CategorizationAnalyzer string _types:CategorizationAnalyzerDefinition object
      • categorization_field_name string

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

      • categorization_filters array[string]

        If categorization_field_name is specified, you can also define optional filters. This property expects an array of regular expressions. The expressions are used to filter out matching sequences from the categorization field values.

      • detectors array[object] Required

        An array of detector configuration objects. Detector configuration objects specify which data fields a job analyzes. They also specify which analytical functions are used. You can specify multiple detectors for a job.

        Hide detectors attributes Show detectors attributes object
        • by_field_name string

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

        • custom_rules array[object]

          An array of custom rule objects, which enable you to customize the way detectors operate. For example, a rule may dictate to the detector conditions under which results should be skipped. Kibana refers to custom rules as job rules.

          Hide custom_rules attributes Show custom_rules attributes object
          • actions array[string]

            The set of actions to be triggered when the rule applies. If more than one action is specified the effects of all actions are combined.

            Values are skip_result or skip_model_update.

          • conditions array[object]

            An array of numeric conditions when the rule applies. A rule must either have a non-empty scope or at least one condition. Multiple conditions are combined together with a logical AND.

          • scope object

            A scope of series where the rule applies. A rule must either have a non-empty scope or at least one condition. By default, the scope includes all series. Scoping is allowed for any of the fields that are also specified in by_field_name, over_field_name, or partition_field_name.

        • detector_description string

          A description of the detector.

        • detector_index number

          A unique identifier for the detector. This identifier is based on the order of the detectors in the analysis_config, starting at zero.

        • exclude_frequent string

          Values are all, none, by, or over.

        • field_name string

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

        • function string Required

          The analysis function that is used. For example, count, rare, mean, min, max, and sum.

        • over_field_name string

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

        • partition_field_name string

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

        • use_null boolean

          Defines whether a new series is used as the null series when there is no value for the by or partition fields.

      • influencers array[string] Required

        A comma separated list of influencer field names. Typically these can be the by, over, or partition fields that are used in the detector configuration. You might also want to use a field name that is not specifically named in a detector, but is available as part of the input data. When you use multiple detectors, the use of influencers is recommended as it aggregates results for each influencer entity.

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

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

      • multivariate_by_fields boolean

        This functionality is reserved for internal use. It is not supported for use in customer environments and is not subject to the support SLA of official GA features. If set to true, the analysis will automatically find correlations between metrics for a given by field value and report anomalies when those correlations cease to hold.

      • per_partition_categorization object

        Additional properties are allowed.

        Hide per_partition_categorization attributes Show per_partition_categorization attributes object
        • enabled boolean

          To enable this setting, you must also set the partition_field_name property to the same value in every detector that uses the keyword mlcategory. Otherwise, job creation fails.

        • stop_on_warn boolean

          This setting can be set to true only if per-partition categorization is enabled. If true, both categorization and subsequent anomaly detection stops for partitions where the categorization status changes to warn. This setting makes it viable to have a job where it is expected that categorization works well for some partitions but not others; you do not pay the cost of bad categorization forever in the partitions where it works badly.

      • summary_count_field_name string

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

    • analysis_limits object Required

      Additional properties are allowed.

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

    • create_time number

      Time unit for milliseconds

    • finished_time number

      Time unit for milliseconds

    • custom_settings object
      Hide custom_settings attribute Show custom_settings attribute object
      • * string Additional properties
    • daily_model_snapshot_retention_after_days number Required
    • data_description object Required

      Additional properties are allowed.

      Hide data_description attributes Show data_description attributes object
      • format string

        Only JSON format is supported at this time.

      • time_field string

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

      • time_format string

        The time format, which can be epoch, epoch_ms, or a custom pattern. The value epoch refers to UNIX or Epoch time (the number of seconds since 1 Jan 1970). The value epoch_ms indicates that time is measured in milliseconds since the epoch. The epoch and epoch_ms time formats accept either integer or real values. Custom patterns must conform to the Java DateTimeFormatter class. When you use date-time formatting patterns, it is recommended that you provide the full date, time and time zone. For example: yyyy-MM-dd'T'HH:mm:ssX. If the pattern that you specify is not sufficient to produce a complete timestamp, job creation fails.

      • field_delimiter string
    • datafeed_config object

      Additional properties are allowed.

      Hide datafeed_config attributes Show datafeed_config attributes object
      • aggregations object
      • authorization object

        Additional properties are allowed.

        Hide authorization attributes Show authorization attributes object
        • api_key object

          Additional properties are allowed.

          Hide api_key attributes Show api_key attributes object
          • id string Required

            The identifier for the API key.

          • name string Required

            The name of the API key.

        • roles array[string]

          If a user ID was used for the most recent update to the datafeed, its roles at the time of the update are listed in the response.

        • service_account string

          If a service account was used for the most recent update to the datafeed, the account name is listed in the response.

      • chunking_config object

        Additional properties are allowed.

        Hide chunking_config attributes Show chunking_config attributes object
        • mode string Required

          Values are auto, manual, or off.

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

      • datafeed_id string Required
      • frequency 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.

      • indices array[string] Required
      • indexes array[string]
      • job_id string Required
      • max_empty_searches number
      • query_delay 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.

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

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            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:
              _types:ScriptLanguage string _types:ScriptLanguage string

              Values are painless, expression, mustache, or java.

            • options object
              Hide options attribute Show options attribute object
              • * string Additional properties
          • ignore_failure boolean
      • scroll_size number
      • delayed_data_check_config object Required

        Additional properties are allowed.

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

        • enabled boolean Required

          Specifies whether the datafeed periodically checks for delayed data.

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

          • input_field string

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

          • target_field string

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

          • target_index string
          • 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:
              _types:ScriptLanguage string _types:ScriptLanguage string

              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.

      • indices_options object

        Additional properties are allowed.

        Hide indices_options attributes Show indices_options attributes object
        • allow_no_indices boolean

          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]
        • ignore_unavailable boolean

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

        • ignore_throttled boolean

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

      • query object Required

        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": {"boost": 1}}.

        Additional properties are allowed.

        Query DSL
    • description string
    • groups array[string]
    • job_id string Required
    • job_type string Required
    • job_version string Required
    • model_plot_config object

      Additional properties are allowed.

      Hide model_plot_config attributes Show model_plot_config attributes object
      • annotations_enabled boolean

        If true, enables calculation and storage of the model change annotations for each entity that is being analyzed.

      • enabled boolean

        If true, enables calculation and storage of the model bounds for each entity that is being analyzed.

      • terms string

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

    • model_snapshot_id string
    • model_snapshot_retention_days number Required
    • renormalization_window_days number
    • results_index_name string Required
    • results_retention_days number
POST /_ml/anomaly_detectors/{job_id}/_update 
curl \
 --request POST http://api.example.com/_ml/anomaly_detectors/{job_id}/_update \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"allow_lazy_open":true,"analysis_limits":{"model_memory_limit":"string"},"background_persist_interval":"string","custom_settings":{"additionalProperty1":{},"additionalProperty2":{}},"categorization_filters":["string"],"description":"string","model_plot_config":{"annotations_enabled":true,"enabled":true,"terms":"string"},"model_prune_window":"string","daily_model_snapshot_retention_after_days":42.0,"model_snapshot_retention_days":42.0,"renormalization_window_days":42.0,"results_retention_days":42.0,"groups":["string"],"detectors":[{"detector_index":42.0,"description":"string","custom_rules":[{"actions":["skip_result"],"conditions":[{"applies_to":"actual","operator":"gt","value":42.0}],"scope":{"additionalProperty1":{"filter_id":"string","filter_type":"include"},"additionalProperty2":{"filter_id":"string","filter_type":"include"}}}]}],"per_partition_categorization":{"enabled":true,"stop_on_warn":true}}'

Get data frame analytics job configuration info Added in 7.3.0

GET /_ml/data_frame/analytics/{id}
Api key auth

You can get information for multiple data frame analytics jobs in a single API request by using a comma-separated list of data frame analytics jobs or a wildcard expression.

Path parameters

  • id string Required

    Identifier for the data frame analytics job. If you do not specify this option, the API returns information for the first hundred data frame analytics jobs.

Query parameters

  • allow_no_match boolean

    Specifies what to do when the request:

    1. Contains wildcard expressions and there are no data frame analytics jobs that match.
    2. Contains the _all string or no identifiers and there are no matches.
    3. Contains wildcard expressions and there are only partial matches.

    The default value returns an empty data_frame_analytics array when there are no matches and the subset of results when there are partial matches. If this parameter is false, the request returns a 404 status code when there are no matches or only partial matches.

  • from number

    Skips the specified number of data frame analytics jobs.

  • size number

    Specifies the maximum number of data frame analytics jobs to obtain.

  • exclude_generated boolean

    Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • count number Required
    • data_frame_analytics array[object] Required

      An array of data frame analytics job resources, which are sorted by the id value in ascending order.

      Hide data_frame_analytics attributes Show data_frame_analytics attributes object
      • allow_lazy_start boolean
      • analysis object Required

        Additional properties are allowed.

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

          • downsample_factor number

            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.

          • early_stopping_enabled boolean

            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.

          • eta_growth_rate_per_tree number

            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.

          • feature_bag_fraction number

            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.

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

          • max_optimization_rounds_per_hyperparameter number

            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.

          • max_trees number

            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.

          • num_top_feature_importance_values number

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

          • prediction_field_name string

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

          • randomize_seed number

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

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

          • soft_tree_depth_tolerance number

            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.

          • class_assignment_objective string
          • num_top_classes number

            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.

        • outlier_detection object

          Additional properties are allowed.

          Hide outlier_detection attributes Show outlier_detection attributes object
          • compute_feature_influence boolean

            Specifies whether the feature influence calculation is enabled.

          • feature_influence_threshold number

            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.

          • n_neighbors number

            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.

          • outlier_fraction number

            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.

          • standardization_enabled boolean

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

        • regression object

          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.

          • downsample_factor number

            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.

          • early_stopping_enabled boolean

            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.

          • eta_growth_rate_per_tree number

            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.

          • feature_bag_fraction number

            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.

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

          • max_optimization_rounds_per_hyperparameter number

            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.

          • max_trees number

            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.

          • num_top_feature_importance_values number

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

          • prediction_field_name string

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

          • randomize_seed number

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

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

          • soft_tree_depth_tolerance number

            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.

          • loss_function string

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

          • loss_function_parameter number

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

      • analyzed_fields object

        Additional properties are allowed.

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

          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]

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

      • authorization object

        Additional properties are allowed.

        Hide authorization attributes Show authorization attributes object
        • api_key object

          Additional properties are allowed.

          Hide api_key attributes Show api_key attributes object
          • id string Required

            The identifier for the API key.

          • name string Required

            The name of the API key.

        • roles array[string]

          If a user ID was used for the most recent update to the job, its roles at the time of the update are listed in the response.

        • service_account string

          If a service account was used for the most recent update to the job, the account name is listed in the response.

      • create_time number

        Time unit for milliseconds

      • description string
      • dest object Required

        Additional properties are allowed.

        Hide dest attributes Show dest attributes object
        • index string Required
        • results_field string

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

      • id string Required
      • max_num_threads number
      • model_memory_limit string
      • source object Required

        Additional properties are allowed.

        Hide source attributes Show source attributes object
        • index string | array[string] Required
        • runtime_mappings object
          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

            • fetch_fields array[object]

              For type lookup

            • format string

              A custom format for date type runtime fields.

            • input_field string

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

            • target_field string

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

            • target_index string
            • script object

              Additional properties are allowed.

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

            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]

            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.

          Query DSL
      • version string
      • _meta object
        Hide _meta attribute Show _meta attribute object
        • * object Additional properties

          Additional properties are allowed.
GET /_ml/data_frame/analytics/{id} 
curl \
 --request GET http://api.example.com/_ml/data_frame/analytics/{id} \
 --header "Authorization: $API_KEY"

Create or update a query rule Added in 8.15.0

PUT /_query_rules/{ruleset_id}/_rule/{rule_id}
Api key auth

Create or update a query rule within a query ruleset.

IMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

Path parameters

  • ruleset_id string Required

    The unique identifier of the query ruleset containing the rule to be created or updated.

  • rule_id string Required

    The unique identifier of the query rule within the specified ruleset to be created or updated.

application/json

Body Required

  • type string Required

    Values are pinned or exclude.

  • criteria object | array[object] Required

    The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

    One of:
    _types:QueryRuleCriteria object array-2 array[object]
    Hide attributes Show attributes
    • type string Required

      Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

    • metadata string

      The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

    • values array[object]

      The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

      Additional properties are allowed.

  • actions object Required

    Additional properties are allowed.

    Hide actions attributes Show actions attributes object
    • ids array[string]

      The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

    • docs array[object]

      The documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document:

      • _index: The index of the document to pin.
      • _id: The unique document ID.
      Hide docs attributes Show docs attributes object
  • priority number

Responses

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

      Values are created, updated, deleted, not_found, or noop.
PUT /_query_rules/{ruleset_id}/_rule/{rule_id} 
curl \
 --request PUT http://api.example.com/_query_rules/{ruleset_id}/_rule/{rule_id} \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"type":"pinned","criteria":{"type":"global","metadata":"string","values":[{}]},"actions":{"ids":["string"],"docs":[{"_id":"string","_index":"string"}]},"priority":42.0}'

Create or update a query ruleset Added in 8.10.0

PUT /_query_rules/{ruleset_id}
Api key auth

There is a limit of 100 rules per ruleset. This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

External documentation

Path parameters

  • ruleset_id string Required

    The unique identifier of the query ruleset to be created or updated.

application/json

Body Required

  • rules object | array[object]

    One of:
    _types:QueryRule object array-2 array[object]
    Hide attributes Show attributes
    • rule_id string Required
    • type string Required

      Values are pinned or exclude.

    • criteria object | array[object] Required

      The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

      One of:
      _types:QueryRuleCriteria object array-2 array[object]
      Hide attributes Show attributes
      • type string Required

        Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

      • metadata string

        The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

      • values array[object]

        The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

        Additional properties are allowed.

    • actions object Required

      Additional properties are allowed.

      Hide actions attributes Show actions attributes object
      • ids array[string]

        The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

      • docs array[object]

        The documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document:

        • _index: The index of the document to pin.
        • _id: The unique document ID.
        Hide docs attributes Show docs attributes object
    • priority number

Responses

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

      Values are created, updated, deleted, not_found, or noop.
PUT /_query_rules/{ruleset_id} 
curl \
 --request PUT http://api.example.com/_query_rules/{ruleset_id} \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"rules":{"rule_id":"string","type":"pinned","criteria":{"type":"global","metadata":"string","values":[{}]},"actions":{"ids":["string"],"docs":[{"_id":"string","_index":"string"}]},"priority":42.0}}'

Create or update a script or search template

PUT /_scripts/{id}/{context}
Api key auth

Creates or updates a stored script or search template.

External documentation

Path parameters

  • id string Required

    The identifier for the stored script or search template. It must be unique within the cluster.

  • context string Required

    The context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context.

Query parameters

  • context string

    The context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context. If you specify both this and the <context> path parameter, the API uses the request path parameter.

  • master_timeout string

    The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. It can also be set to -1 to indicate that the request should never timeout.

  • timeout string

    The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. It can also be set to -1 to indicate that the request should never timeout.

application/json

Body Required

Responses

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

      For a successful response, this value is always true. On failure, an exception is returned instead.
PUT /_scripts/{id}/{context} 
curl \
 --request PUT http://api.example.com/_scripts/{id}/{context} \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"script\": {\n    \"lang\": \"mustache\",\n    \"source\": {\n      \"query\": {\n        \"match\": {\n          \"message\": \"{{query_string}}\"\n        }\n      },\n      \"from\": \"{{from}}\",\n      \"size\": \"{{size}}\"\n    }\n  }\n}"'
Request examples
Run `PUT _scripts/my-search-template` to create a search template. 
{
  "script": {
    "lang": "mustache",
    "source": {
      "query": {
        "match": {
          "message": "{{query_string}}"
        }
      },
      "from": "{{from}}",
      "size": "{{size}}"
    }
  }
}
Run `PUT _scripts/my-stored-script` to create a stored script. 
{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 2) + params['my_modifier']"
  }
}

Run a search

GET /_search
Api key auth

Get search hits that match the query defined in the request. You can provide search queries using the q query string parameter or the request body. If both are specified, only the query parameter is used.

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.

Search slicing

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties. By default the splitting is done first on the shards, then locally on each shard. The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.

For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.

IMPORTANT: The same point-in-time ID should be used for all slices. If different PIT IDs are used, slices can overlap and miss documents. This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.

External documentation

Query parameters

  • allow_no_indices boolean

    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.

  • allow_partial_search_results boolean

    If true and there are shard request timeouts or shard failures, the request returns partial results. If false, it returns an error with no partial results.

    To override the default behavior, you can set the search.default_allow_partial_results cluster setting to false.

  • analyzer string

    The analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.

  • analyze_wildcard boolean

    If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.

  • batched_reduce_size number

    The number of shard results that should be reduced at once on the coordinating node. If the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.

  • ccs_minimize_roundtrips boolean

    If true, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.

  • default_operator string

    The default operator for the query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

    Values are and, AND, or, or OR.

  • df string

    The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.

  • docvalue_fields string | array[string]

    A comma-separated list of fields to return as the docvalue representation of a field for each hit.

  • expand_wildcards string | array[string]

    The 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. It supports comma-separated values such as open,hidden.

  • explain boolean

    If true, the request returns detailed information about score computation as part of a hit.

  • ignore_throttled boolean Deprecated

    If true, concrete, expanded or aliased indices will be ignored when frozen.

  • ignore_unavailable boolean

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

  • include_named_queries_score boolean

    If true, the response includes the score contribution from any named queries.

    This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.

  • lenient boolean

    If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.

  • max_concurrent_shard_requests number

    The number of concurrent shard requests per node that the search runs concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.

  • preference string

    The nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:

    • _only_local to run the search only on shards on the local node.
    • _local to, if possible, run the search on shards on the local node, or if not, select shards using the default method.
    • _only_nodes:<node-id>,<node-id> to run the search on only the specified nodes IDs. If suitable shards exist on more than one selected node, use shards on those nodes using the default method. If none of the specified nodes are available, select shards from any available node using the default method.
    • _prefer_nodes:<node-id>,<node-id> to if possible, run the search on the specified nodes IDs. If not, select shards using the default method. _shards:<shard>,<shard> to run the search only on the specified shards. You can combine this value with other preference values. However, the _shards value must come first. For example: _shards:2,3|_local. <custom-string> (any string that does not start with _) to route searches with the same <custom-string> to the same shards in the same order.
  • pre_filter_shard_size number

    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 (if date filters are mandatory to match but the shard bounds and the query are disjoint). When unspecified, the pre-filter phase is executed if any of these conditions is met:

    • The request targets more than 128 shards.
    • The request targets one or more read-only index.
    • The primary sort of the query targets an indexed field.
  • request_cache boolean

    If true, the caching of search results is enabled for requests where size is 0. It defaults to index level settings.

  • routing string

    A custom value that is used to route operations to a specific shard.

  • scroll string

    The period to retain the search context for scrolling. By default, this value cannot exceed 1d (24 hours). You can change this limit by using the search.max_keep_alive cluster-level setting.

  • search_type string

    Indicates how distributed term frequencies are calculated for relevance scoring.

    Values are query_then_fetch or dfs_query_then_fetch.

  • stats array[string]

    Specific tag of the request for logging and statistical purposes.

  • stored_fields string | array[string]

    A comma-separated list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.

  • suggest_field string

    The field to use for suggestions.

  • suggest_mode string

    The suggest mode. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

    Values are missing, popular, or always.

  • suggest_size number

    The number of suggestions to return. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

  • suggest_text string

    The source text for which the suggestions should be returned. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

  • terminate_after number

    The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

    IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. If set to 0 (default), the query does not terminate early.

  • timeout string

    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. It defaults to no timeout.

  • track_total_hits boolean | number

    The number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query.

  • track_scores boolean

    If true, the request calculates and returns document scores, even if the scores are not used for sorting.

  • typed_keys boolean

    If true, aggregation and suggester names are be prefixed by their respective types in the response.

  • rest_total_hits_as_int boolean

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response.

  • version boolean

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

  • _source boolean | string | array[string]

    The source fields that are returned for matching documents. These fields are returned in the hits._source property of the search response. Valid values are:

    • true to return the entire document source.
    • false to not return the document source.
    • <string> to return the source fields that are specified as a comma-separated list that supports wildcard (*) patterns.
  • _source_excludes string | array[string]

    A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.

  • _source_includes string | array[string]

    A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.

  • seq_no_primary_term boolean

    If true, the request returns the sequence number and primary term of the last modification of each hit.

  • q string

    A query in the Lucene query string syntax. Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.

    IMPORTANT: This parameter overrides the query parameter in the request body. If both parameters are specified, documents matching the query request body parameter are not returned.

  • size number

    The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • from number

    The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • sort string | array[string]

    A comma-separated list of <field>:<direction> pairs.

application/json

Body

  • aggregations object

    Defines the aggregations that are run as part of the search request.

  • collapse object

    Additional properties are allowed.

    External documentation
  • explain boolean

    If true, the request returns detailed information about score computation as part of a hit.

  • ext object

    Configuration of search extensions defined by Elasticsearch plugins.

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

      Additional properties are allowed.

  • from number

    The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

  • highlight object

    Additional properties are allowed.

    Hide highlight attributes Show highlight attributes object

    • Values are plain, fvh, or unified.

    • boundary_chars string

      A string that contains each boundary character.

    • boundary_max_scan number

      How far to scan for boundary characters.

    • boundary_scanner string

      Values are chars, sentence, or word.

    • boundary_scanner_locale string

      Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

    • force_source boolean Deprecated
    • fragmenter string

      Values are simple or span.

    • fragment_size number

      The size of the highlighted fragment in characters.

    • highlight_filter boolean
    • highlight_query object

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

      Additional properties are allowed.

      External documentation
    • max_fragment_length number
    • max_analyzed_offset number

      If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

    • no_match_size number

      The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

    • number_of_fragments number

      The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

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

        Additional properties are allowed.

    • order string

      Value is score.

    • phrase_limit number

      Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

    • post_tags array[string]

      Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

    • pre_tags array[string]

      Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

    • require_field_match boolean

      By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

    • tags_schema string

      Value is styled.

    • encoder string

      Values are default or html.

    • fields object Required
  • track_total_hits boolean | number

    Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.

  • indices_boost array[object]

    Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

    External documentation
    Hide indices_boost attribute Show indices_boost attribute object
    • * number Additional properties
  • docvalue_fields array[object]

    An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

    External documentation
    Hide docvalue_fields attributes Show docvalue_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

      The format in which the values are returned.

    • include_unmapped boolean

  • knn object | array[object]

    The approximate kNN search to run.

    One of:
    _types:KnnSearch object array-2 array[object]
    Hide attributes Show attributes
    • field string Required

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

    • query_vector array[number]
    • query_vector_builder object

      Additional properties are allowed.

      Hide query_vector_builder attribute Show query_vector_builder attribute object
    • k number

      The final number of nearest neighbors to return as top hits

    • num_candidates number

      The number of nearest neighbor candidates to consider per shard

    • boost number

      Boost value to apply to kNN scores

    • filter object | array[object]

      Filters for the kNN search query

      One of:
      query_dsl:QueryContainer object array-2 array[object]

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

      Additional properties are allowed.

      External documentation
    • similarity number

      The minimum similarity for a vector to be considered a match

    • inner_hits object

      Additional properties are allowed.

      Hide inner_hits attributes Show inner_hits attributes object
      • name string
      • size number

        The maximum number of hits to return per inner_hits.

      • from number

        Inner hit starting document offset.

      • collapse object

        Additional properties are allowed.

        External documentation
      • docvalue_fields array[object]
        Hide docvalue_fields attributes Show docvalue_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

          The format in which the values are returned.

        • include_unmapped boolean
      • explain boolean
      • highlight object

        Additional properties are allowed.

        Hide highlight attributes Show highlight attributes object

        • Values are plain, fvh, or unified.

        • boundary_chars string

          A string that contains each boundary character.

        • boundary_max_scan number

          How far to scan for boundary characters.

        • boundary_scanner string

          Values are chars, sentence, or word.

        • boundary_scanner_locale string

          Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

        • force_source boolean Deprecated
        • fragmenter string

          Values are simple or span.

        • fragment_size number

          The size of the highlighted fragment in characters.

        • highlight_filter boolean
        • highlight_query object

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

          Additional properties are allowed.

          External documentation
        • max_fragment_length number
        • max_analyzed_offset number

          If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

        • no_match_size number

          The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

        • number_of_fragments number

          The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

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

            Additional properties are allowed.

        • order string

          Value is score.

        • phrase_limit number

          Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

        • post_tags array[string]

          Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

        • pre_tags array[string]

          Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in <em> and </em> tags.

        • require_field_match boolean

          By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

        • tags_schema string

          Value is styled.

        • encoder string

          Values are default or html.

        • fields object Required
      • ignore_unmapped boolean
      • script_fields object
        Hide script_fields attribute Show script_fields attribute object
        • * object Additional properties

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            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.

            • lang
            • options object
          • ignore_failure boolean
      • seq_no_primary_term boolean
      • fields string | array[string]

      • sort string | object | array[string | object]

        One of:
        _types:Field string _types:SortOptions object _types:Sort array[string | object]

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

      • _source boolean | object

        Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

        One of:
        _types:SourceConfig boolean _types:SourceFilter object
      • stored_fields string | array[string]
      • track_scores boolean
      • version boolean
    • rescore_vector object

      Additional properties are allowed.

      Hide rescore_vector attribute Show rescore_vector attribute object
      • oversample number Required

        Applies the specified oversample factor to k on the approximate kNN search

  • min_score number

    The minimum _score for matching documents. Documents with a lower _score are not included in the search results.

  • post_filter object

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

    Additional properties are allowed.

    External documentation
  • profile boolean

    Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.

  • query object

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

    Additional properties are allowed.

    External documentation

  • rescore object | array[object]

    Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.

    One of:
    _types:Rescore object array-2 array[object]
    Hide attributes Show attributes
    • window_size number
    • query object

      Additional properties are allowed.

      Hide query attributes Show query attributes object
    • learning_to_rank object

      Additional properties are allowed.

      Hide learning_to_rank attributes Show learning_to_rank attributes object
      • model_id string Required

        The unique identifier of the trained model uploaded to Elasticsearch

      • params object

        Named parameters to be passed to the query templates used for feature

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

          Additional properties are allowed.

  • retriever object

    Additional properties are allowed.

    Hide retriever attributes Show retriever attributes object
    • standard object

      Additional properties are allowed.

      Hide standard attributes Show standard attributes object
      • filter object Required

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

        Additional properties are allowed.

        External documentation
      • min_score number

        Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • query object

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

        Additional properties are allowed.

        External documentation
      • search_after array[number | string | boolean | null]

        A field value.

      • terminate_after number

        Maximum number of documents to collect for each shard.

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

      • collapse object

        Additional properties are allowed.

        External documentation
    • knn object

      Additional properties are allowed.

      Hide knn attributes Show knn attributes object
      • filter object

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

        Additional properties are allowed.

        External documentation
      • min_score number

        Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • field string Required

        The name of the vector field to search against.

      • query_vector array[number]
      • query_vector_builder object

        Additional properties are allowed.

        Hide query_vector_builder attribute Show query_vector_builder attribute object
      • k number Required

        Number of nearest neighbors to return as top hits.

      • num_candidates number Required

        Number of nearest neighbor candidates to consider per shard.

      • similarity number

        The minimum similarity required for a document to be considered a match.

      • rescore_vector object

        Additional properties are allowed.

        Hide rescore_vector attribute Show rescore_vector attribute object
        • oversample number Required

          Applies the specified oversample factor to k on the approximate kNN search

    • rrf object

      Additional properties are allowed.

      Hide rrf attributes Show rrf attributes object
      • filter object

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

        Additional properties are allowed.

        External documentation
      • min_score number

        Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • retrievers array[object] Required

        A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.

        Additional properties are allowed.

      • rank_constant number

        This value determines how much influence documents in individual result sets per query have over the final ranked result set.

      • rank_window_size number

        This value determines the size of the individual result sets per query.

    • text_similarity_reranker object

      Additional properties are allowed.

      Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
      • filter object

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

        Additional properties are allowed.

        External documentation
      • min_score number

        Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • retriever object Required

        Additional properties are allowed.

      • rank_window_size number

        This value determines how many documents we will consider from the nested retriever.

      • inference_id string

        Unique identifier of the inference endpoint created using the inference API.

      • inference_text string

        The text snippet used as the basis for similarity comparison

      • field string

        The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text

    • rule object

      Additional properties are allowed.

      Hide rule attributes Show rule attributes object
      • filter object

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

        Additional properties are allowed.

        External documentation
      • min_score number

        Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.

      • ruleset_ids array[string] Required

        The ruleset IDs containing the rules this retriever is evaluating against.

      • match_criteria object Required

        The match criteria that will determine if a rule in the provided rulesets should be applied.

        Additional properties are allowed.

      • retriever object Required

        Additional properties are allowed.

      • rank_window_size number

        This value determines the size of the individual result set.

  • script_fields object

    Retrieve a script evaluation (based on different fields) for each hit.

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

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • script object Required

        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:
          _types:ScriptLanguage string _types:ScriptLanguage string

          Values are painless, expression, mustache, or java.

        • options object
          Hide options attribute Show options attribute object
          • * string Additional properties
      • ignore_failure boolean
  • search_after array[number | string | boolean | null]

    A field value.

  • size number

    The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.

  • slice object

    Additional properties are allowed.

    Hide slice attributes Show slice attributes object
    • field string

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

    • id string Required
    • max number Required

  • sort string | object | array[string | object]

    One of:
    _types:Field string _types:SortOptions object _types:Sort array[string | object]

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

  • _source boolean | object

    Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

    One of:
    _types:SourceConfig boolean _types:SourceFilter object
  • fields array[object]

    An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

    Hide fields attributes Show 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

      The format in which the values are returned.

    • include_unmapped boolean
  • suggest object

    Additional properties are allowed.

    Hide suggest attribute Show suggest attribute object
    • text string

      Global suggest text, to avoid repetition when the same text is used in several suggesters

  • terminate_after number

    The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

    IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.

    If set to 0 (default), the query does not terminate early.

  • timeout string

    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.

  • track_scores boolean

    If true, calculate and return document scores, even if the scores are not used for sorting.

  • version boolean

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

  • seq_no_primary_term boolean

    If true, the request returns sequence number and primary term of the last modification of each hit.

    External documentation
  • stored_fields string | array[string]
  • pit object

    Additional properties are allowed.

    Hide pit attributes Show pit attributes object
    • id string Required
    • keep_alive 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.

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

      • input_field string

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

      • target_field string

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

      • target_index string
      • 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:
          _types:ScriptLanguage string _types:ScriptLanguage string

          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.

  • stats array[string]

    The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

GET /_search 
curl \
 --request GET http://api.example.com/_search \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"term\": {\n      \"user.id\": \"kimchy\"\n    }\n  }\n}"'
Request examples
Run `GET /my-index-000001/_search?from=40&size=20` to run a search. 
{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}
Run `POST /_search` to run a point in time search. The `id` parameter tells Elasticsearch to run the request using contexts from this open point in time. The `keep_alive` parameter tells Elasticsearch how long it should extend the time to live of the point in time. 
{
    "size": 100,  
    "query": {
        "match" : {
            "title" : "elasticsearch"
        }
    },
    "pit": {
      "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
      "keep_alive": "1m"  
    }
}
When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently. The result from running the first `GET /_search` request returns documents belonging to the first slice (`id: 0`). If you run a second request with `id` set to `1', it returns documents in the second slice. Since the maximum number of slices is set to `2`, the union of the results is equivalent to the results of a point-in-time search without slicing. 
{
  "slice": {
    "id": 0,                      
    "max": 2                      
  },
  "query": {
    "match": {
      "message": "foo"
    }
  },
  "pit": {
    "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=="
  }
}
Response examples (200)
An abbreviated response from `GET /my-index-000001/_search?from=40&size=20` with a simple term query. 
{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 20,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "0",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "status_code": 200,
              "bytes": 1070000
            },
            "version": "1.1"
          },
          "source": {
            "ip": "127.0.0.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}