Get transforms Generally available; Added in 7.5.0

GET /_transform/{transform_id}
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_transform

GET /_transform/{transform_id}

Get configuration information for transforms.

Required authorization

  • Cluster privileges: monitor_transform

Path parameters

  • transform_id string | array[string] Required

    Identifier for the transform. It can be a transform identifier or a wildcard expression. You can get information for all transforms by using _all, by specifying * as the <transform_id>, or by omitting the <transform_id>.

Query parameters

  • allow_no_match boolean

    Specifies what to do when the request:

    1. Contains wildcard expressions and there are no transforms 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 this parameter is false, the request returns a 404 status code when there are no matches or only partial matches.

    Default value is true.

  • from number

    Skips the specified number of transforms.

    Default value is 0.

  • size number

    Specifies the maximum number of transforms to obtain.

    Default value is 100.

  • exclude_generated boolean

    Excludes fields that were automatically added when creating the transform. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.

    Default value is false.

Responses

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

        The security privileges that the transform uses to run its queries. If Elastic Stack security features were disabled at the time of the most recent update to the transform, this property is omitted.

        Hide authorization attributes Show authorization attributes object
        • api_key object

          If an API key was used for the most recent update to the transform, its name and identifier are listed in the response.

        • roles array[string]

          If a user ID was used for the most recent update to the transform, 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 transform, the account name is listed in the response.

      • create_time number

        The time the transform was created.

      • create_time_string string | number

        One of:
        string-1 string UnitMillis number

        Time unit for milliseconds

      • description string

        Free text description of the transform.

      • dest object Required

        The destination for the transform.

        Hide dest attributes Show dest attributes object
        • index string

          The destination index for the transform. The mappings of the destination index are deduced based on the source fields when possible. If alternate mappings are required, use the create index API prior to starting the transform.

        • aliases array[object] Generally available; Added in 8.8.0

          The aliases that the destination index for the transform should have. Aliases are manipulated using the stored credentials of the transform, which means the secondary credentials supplied at creation time (if both primary and secondary credentials are specified).

          The destination index is added to the aliases regardless of whether the destination index was created by the transform or pre-created by the user.

        • pipeline string

          The unique identifier for an ingest pipeline.

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

        External documentation
      • id string Required
      • latest object
        Hide latest attributes Show latest attributes object
        • sort string Required

          Specifies the date field that is used to identify the latest documents.

        • unique_key array[string] Required

          Specifies an array of one or more fields that are used to group the data.

      • pivot object

        The pivot method transforms the data by aggregating and grouping it.

        Hide pivot attributes Show pivot attributes object
        • aggregations object

          Defines how to aggregate the grouped data. The following aggregations are currently supported: average, bucket script, bucket selector, cardinality, filter, geo bounds, geo centroid, geo line, max, median absolute deviation, min, missing, percentiles, rare terms, scripted metric, stats, sum, terms, top metrics, value count, weighted average.

        • group_by object

          Defines how to group the data. More than one grouping can be defined per pivot. The following groupings are currently supported: date histogram, geotile grid, histogram, terms.

          Hide group_by attribute Show group_by attribute object
          • * object Additional properties
      • retention_policy object
        Hide retention_policy attribute Show retention_policy attribute object
        • time object

          Specifies that the transform uses a time field to set the retention policy.

      • settings object

        Defines optional transform settings.

        Hide settings attributes Show settings attributes object
        • align_checkpoints boolean

          Specifies whether the transform checkpoint ranges should be optimized for performance. Such optimization can align checkpoint ranges with the date histogram interval when date histogram is specified as a group source in the transform config. As a result, less document updates in the destination index will be performed thus improving overall performance.

          Default value is true.

        • dates_as_epoch_millis boolean

          Defines if dates in the ouput should be written as ISO formatted string or as millis since epoch. epoch_millis was the default for transforms created before version 7.11. For compatible output set this value to true.

          Default value is false.

        • deduce_mappings boolean

          Specifies whether the transform should deduce the destination index mappings from the transform configuration.

          Default value is true.

        • docs_per_second number

          Specifies a limit on the number of input documents per second. This setting throttles the transform by adding a wait time between search requests. The default value is null, which disables throttling.

        • max_page_search_size number

          Defines the initial page size to use for the composite aggregation for each checkpoint. If circuit breaker exceptions occur, the page size is dynamically adjusted to a lower value. The minimum value is 10 and the maximum is 65,536. The default value is 500 for pivot transforms and 5000 for latest transforms.

        • use_point_in_time boolean

          Specifies whether the transform checkpoint will use the Point In Time API while searching over the source index. In general, Point In Time is an optimization that will reduce pressure on the source index by reducing the amount of refreshes and merges, but it can be expensive if a large number of Point In Times are opened and closed for a given index. The benefits and impact depend on the data being searched, the ingest rate into the source index, and the amount of other consumers searching the same source index.

          Default value is true.

          External documentation
        • num_failure_retries number Generally available; Added in 8.4.0

          Defines the number of retries on a recoverable failure before the transform task is marked as failed. The minimum value is 0 and the maximum is 100, where -1 indicates that the transform retries indefinitely. If unset, the cluster-level setting num_transform_failure_retries is used.

          This setting cannot be specified when unattended is true, because unattended transforms always retry indefinitely.

        • unattended boolean Generally available; Added in 8.5.0

          If true, the transform runs in unattended mode. In unattended mode, the transform retries indefinitely in case of an error which means the transform never fails. Setting the number of retries other than infinite fails in validation.

          Default value is false.

      • source object Required

        The source of the data for the transform.

        Hide source attributes Show source attributes object
        • index string | array[string] Required

          The source indices for the transform. It can be a single index, an index pattern (for example, "my-index-*""), an array of indices (for example, ["my-index-000001", "my-index-000002"]), or an array of index patterns (for example, ["my-index-*", "my-other-index-*"]. For remote indices use the syntax "remote_name:index_name". If any indices are in remote clusters then the master node and at least one transform node must have the remote_cluster_client node role.

        • runtime_mappings object Generally available; Added in 7.12.0

          Definitions of search-time runtime fields that can be used by the transform. For search runtime fields all data nodes, including remote nodes, must be 7.12 or later.

        • query object

          A query clause that retrieves a subset of data from the source index.

          Query DSL
      • sync object

        Defines the properties transforms require to run continuously.

        Hide sync attribute Show sync attribute object
        • time object

          Specifies that the transform uses a time field to synchronize the source and destination indices.

      • version string

        The version of Elasticsearch that existed on the node when the transform was created.

      • _meta object
        Hide _meta attribute Show _meta attribute object
        • * object Additional properties
GET /_transform/{transform_id} 
GET _transform?size=10

resp = client.transform.get_transform(
    size="10",
)
const response = await client.transform.getTransform({
  size: 10,
});
response = client.transform.get_transform(
  size: "10"
)
$resp = $client->transform()->getTransform([
    "size" => "10",
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_transform?size=10"
var response = await client.TransformManagement
    .GetTransformAsync(d1 => d1
        .Size(10)
    );
client.transform().getTransform(g -> g
    .size(10)
);
Response examples (200)
A successful response that contains configuration information for a transform. 
{
  "count": 1,
  "transforms": [
    {
      "id": "ecommerce_transform1",
      "authorization": {
        "roles": [
          "superuser"
        ]
      },
      "version": "8.4.0",
      "create_time": 1656023416565,
      "source": {
        "index": [
          "kibana_sample_data_ecommerce"
        ],
        "query": {
          "term": {
            "geoip.continent_name": {
              "value": "Asia"
            }
          }
        }
      },
      "dest": {
        "index": "kibana_sample_data_ecommerce_transform1",
        "pipeline": "add_timestamp_pipeline"
      },
      "frequency": "5m",
      "sync": {
        "time": {
          "field": "order_date",
          "delay": "60s"
        }
      },
      "pivot": {
        "group_by": {
          "customer_id": {
            "terms": {
              "field": "customer_id"
            }
          }
        },
        "aggregations": {
          "max_price": {
            "max": {
              "field": "taxful_total_price"
            }
          }
        }
      },
      "description": "Maximum priced ecommerce data by customer_id in Asia",
      "settings": {},
      "retention_policy": {
        "time": {
          "field": "order_date",
          "max_age": "30d"
        }
      }
    }
  ]
}