OpenSearch/docs/reference/data-frames/apis/put-transform.asciidoc

165 lines
4.8 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[role="xpack"]
[testenv="basic"]
[[put-data-frame-transform]]
=== Create {dataframe-transforms} API
[subs="attributes"]
++++
<titleabbrev>Create {dataframe-transforms}</titleabbrev>
++++
Instantiates a {dataframe-transform}.
beta[]
[[put-data-frame-transform-request]]
==== {api-request-title}
`PUT _data_frame/transforms/<data_frame_transform_id>`
[[put-data-frame-transform-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have
`manage_data_frame_transforms` cluster privileges to use this API. The built-in
`data_frame_transforms_admin` role has these privileges. You must also
have `read` and `view_index_metadata` privileges on the source index and `read`,
`create_index`, and `index` privileges on the destination index. For more
information, see {stack-ov}/security-privileges.html[Security privileges] and
{stack-ov}/built-in-roles.html[Built-in roles].
[[put-data-frame-transform-desc]]
==== {api-description-title}
IMPORTANT: You must use {kib} or this API to create a {dataframe-transform}.
Do not put a {dataframe-transform} directly into any
`.data-frame-internal*` indices using the Elasticsearch index API.
If {es} {security-features} are enabled, do not give users any
privileges on `.data-frame-internal*` indices.
[[put-data-frame-transform-path-parms]]
==== {api-path-parms-title}
`<data_frame_transform_id>`::
(Required, string) Identifier for the {dataframe-transform}. This identifier
can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and
underscores. It must start and end with alphanumeric characters.
[[put-data-frame-transform-request-body]]
==== {api-request-body-title}
`description`::
(Optional, string) Free text description of the {dataframe-transform}.
`dest`::
(Required, object) Required. The destination configuration, which has the
following properties:
`index`:::
(Required, string) The _destination index_ for the {dataframe-transform}.
`pipeline`:::
(Optional, string) The unique identifier for a <<pipeline,pipeline>>.
`frequency`::
(Optional, time units) The interval between checks for changes in the source indices
when the {dataframe-transform} is running continuously. Defaults to `1m`.
The lowest permitted value is `1s`; the highest `1h`.
`pivot`::
(Required, object) Defines the pivot function `group by` fields and the aggregation to
reduce the data. See <<data-frame-transform-pivot>>.
`source`::
(Required, object) The source configuration, which has the following
properties:
`index`:::
(Required, string or array) The _source indices_ for the
{dataframe-transform}. It can be a single index, an index pattern (for
example, `"myindex*"`), or an array of indices (for example,
`["index1", "index2"]`).
`query`:::
(Optional, object) A query clause that retrieves a subset of data from the
source index. See <<query-dsl>>.
`sync`::
(Optional, object) Defines the properties required to run continuously.
`time`:::
(Required, object) Specifies that the {dataframe-transform} uses a time
field to synchronize the source and destination indices.
`field`::::
(Required, string) The date field that is used to identify new documents
in the source.
+
--
TIP: In general, its a good idea to use a field that contains the
<<accessing-ingest-metadata,ingest timestamp>>. If you use a different field,
you might need to set the `delay` such that it accounts for data transmission
delays.
--
`delay`::::
(Optional, time units) The time delay between the current time and the
latest input data time. The default value is `60s`.
[[put-data-frame-transform-example]]
==== {api-examples-title}
[source,js]
--------------------------------------------------
PUT _data_frame/transforms/ecommerce_transform
{
"source": {
"index": "kibana_sample_data_ecommerce",
"query": {
"term": {
"geoip.continent_name": {
"value": "Asia"
}
}
}
},
"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",
"dest": {
"index": "kibana_sample_data_ecommerce_transform",
"pipeline": "add_timestamp_pipeline"
},
"frequency": "5m",
"sync": {
"time": {
"field": "order_date",
"delay": "60s"
}
}
}
--------------------------------------------------
// CONSOLE
// TEST[setup:kibana_sample_data_ecommerce]
When the transform is created, you receive the following results:
[source,js]
----
{
"acknowledged" : true
}
----
// TESTRESPONSE