New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 获取转换统计 API 重置转换 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›转换 API

预览转换 API

编辑

预览转换 API

编辑

预览转换。

请求

编辑

GET _transform/<transform_id>/_preview

POST _transform/<transform_id>/_preview

GET _transform/_preview

POST _transform/_preview

先决条件

编辑

需要以下权限

  • 集群：manage_transform (内置的 transform_admin 角色授予此权限)
  • 源索引：read, view_index_metadata。

描述

编辑

此 API 生成当您使用相同的配置运行创建转换 API 时将获得的结果的预览。它最多返回 100 个结果。计算基于源索引中的所有当前数据。

它还为目标索引生成映射和设置的列表。如果在启动转换时目标索引不存在，则将使用这些映射和设置。这些值是根据源索引的字段类型和转换聚合确定的。

存在一些限制，可能会导致较差的映射。作为一种解决方法，在启动转换之前，使用您首选的映射创建目标索引或索引模板。

您必须为转换选择 latest 或 pivot 方法；您不能在单个转换中同时使用两者。

当您预览转换时，它会使用调用 API 的用户的凭据。当您启动转换时，它会使用创建或更新它的最后一个用户的角色。如果两组角色不同，则预览可能无法准确反映转换的行为。为避免此类问题，创建或更新转换的同一用户应预览它，以确保它返回预期的数据。或者，使用辅助授权标头来提供凭据

路径参数

编辑
<transform_id>

(可选，字符串) 要预览的转换的 ID。

如果将 <transform_id> 作为路径参数提供，则不能在请求正文中提供转换配置详细信息。

查询参数

编辑
timeout
(可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，则请求将失败并返回错误。默认为 30s。

请求正文

编辑
description
(可选，字符串) 转换的自由文本描述。
dest

(可选，对象) 转换的目标。

dest 的属性
index
(可选，字符串) 转换的目标索引。

在 pivot 转换的情况下，目标索引的映射会在可能的情况下根据源字段推断出来。如果需要其他映射，请在启动转换之前使用创建索引 API。

在 latest 转换的情况下，永远不会推断映射。如果不需要目标索引的动态映射，请在启动转换之前使用创建索引 API。

pipeline
(可选，字符串) 摄取管道的唯一标识符。
frequency
(可选，时间单位) 当转换连续运行时，检查源索引中更改的间隔。最小值为 1s，最大值为 1h。默认值为 1m。
latest

(必需*，对象) latest 方法通过查找每个唯一键的最新文档来转换数据。

latest 的属性
sort
(必需，字符串) 指定用于标识最新文档的日期字段。
unique_key
(必需，字符串数组) 指定用于对数据进行分组的一个或多个字段的数组。
pivot

(必需，对象) pivot 方法通过聚合和分组数据来转换数据。这些对象定义 group by 字段和用于减少数据的聚合。

pivot 的属性
aggregations 或 aggs

(必需，对象) 定义如何聚合分组的数据。当前支持以下聚合

group_by

(必需，对象) 定义如何分组数据。每个 pivot 可以定义多个分组。当前支持以下分组

分组属性可以选择性地具有 missing_bucket 属性。如果它是 true，则包含在各个 group_by 字段中没有值的文档。默认为 false。

retention_policy

(可选，对象) 定义转换的保留策略。符合定义条件的数据将从目标索引中删除。

retention_policy 的属性
time

(必需，对象) 指定转换使用时间字段来设置保留策略。如果存在保留策略的 time.field 并且其中包含早于 max.age 的数据，则会删除数据。

time 的属性
field
(必需，字符串) 用于计算文档年龄的日期字段。将 time.field 设置为现有的日期字段。
max_age
(必需，时间单位) 指定目标索引中文档的最大年龄。比配置的值旧的文档将从目标索引中删除。
source

(必需，对象) 转换的数据源。

source 的属性
index

(必需，字符串或数组) 转换的源索引。它可以是单个索引、索引模式（例如，"my-index-*"）、索引数组（例如，["my-index-000001", "my-index-000002"]）或索引模式数组（例如，["my-index-*", "my-other-index-*"]。对于远程索引，使用语法 "remote_name:index_name"。

如果任何索引位于远程集群中，则主节点和至少一个转换节点必须具有 remote_cluster_client 节点角色。

query
(可选，对象) 从源索引检索数据子集的查询子句。请参阅查询 DSL。
runtime_mappings
(可选，对象) 可以被转换使用的搜索时运行时字段的定义。对于搜索运行时字段，所有数据节点（包括远程节点）必须是 7.12 或更高版本。
sync

(可选，对象) 定义转换连续运行所需的属性。

sync 的属性
time

(可选，对象) 指定转换使用时间字段来同步源索引和目标索引。

time 的属性
delay
(可选，时间单位) 当前时间和最新输入数据时间之间的时间延迟。默认值为 60s。
field
(可选，字符串) 用于标识源中新文档的日期字段。
settings

(可选，对象) 定义可选的转换设置。

settings 的属性
align_checkpoints
(可选，布尔值) 指定是否应优化转换检查点范围以获得性能。当日期直方图指定为转换配置中的组源时，此类优化可以将检查点范围与日期直方图间隔对齐。作为效果，目标索引中执行的文档更新将减少，从而提高整体性能。默认值为 true，这意味着如果可能，将优化检查点范围。
dates_as_epoch_millis
(可选，布尔值) 定义输出中的日期应写入为 ISO 格式的字符串（默认值）还是自纪元以来的毫秒数。epoch_millis 是 7.11 版本之前创建的转换的默认值。要获得兼容的输出，请将其设置为 true。默认值为 false。
deduce_mappings
(可选，布尔值) 指定转换是否应从转换配置中推断出目标索引映射。默认值为 true，这意味着如果可能，将推断出目标索引映射。
docs_per_second
(可选，浮点数) 指定每秒输入文档数的限制。此设置通过在搜索请求之间添加等待时间来限制转换。默认值为 null，禁用限制。
max_page_search_size
（可选，整数）定义每个检查点复合聚合使用的初始页面大小。如果发生断路器异常，则页面大小会动态调整为较低的值。最小值是 10，最大值是 65,536。默认值是 500。
无人值守
（可选，布尔值）如果为 true，则转换在无人值守模式下运行。在无人值守模式下，如果发生错误，转换将无限期重试，这意味着转换永远不会失败。将重试次数设置为无穷大以外的值将在验证时失败。默认为 false。

响应正文

编辑
generated_dest_index

（对象）包含有关目标索引的详细信息。

generated_dest_index 的属性
aliases
（对象）目标索引的别名。
mappings
（对象）目标索引中每个文档的 映射。
settings
（对象）目标索引的 索引设置。
preview
（数组）一个文档数组。 特别是，它们是在转换中将在目标索引中创建的文档的 JSON 表示形式。

示例

编辑
resp = client.transform.preview_transform(
    source={
        "index": "kibana_sample_data_ecommerce"
    },
    pivot={
        "group_by": {
            "customer_id": {
                "terms": {
                    "field": "customer_id",
                    "missing_bucket": True
                }
            }
        },
        "aggregations": {
            "max_price": {
                "max": {
                    "field": "taxful_total_price"
                }
            }
        }
    },
)
print(resp)
const response = await client.transform.previewTransform({
  source: {
    index: "kibana_sample_data_ecommerce",
  },
  pivot: {
    group_by: {
      customer_id: {
        terms: {
          field: "customer_id",
          missing_bucket: true,
        },
      },
    },
    aggregations: {
      max_price: {
        max: {
          field: "taxful_total_price",
        },
      },
    },
  },
});
console.log(response);
POST _transform/_preview
{
  "source": {
    "index": "kibana_sample_data_ecommerce"
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  }
}
Copy as curlTry in Elastic 

此示例返回的数据如下：

{
  "preview" : [
    {
      "max_price" : 171.0,
      "customer_id" : "10"
    },
    {
      "max_price" : 233.0,
      "customer_id" : "11"
    },
    {
      "max_price" : 200.0,
      "customer_id" : "12"
    }
    ...
  ],
  "generated_dest_index" : {
    "mappings" : {
      "_meta" : {
        "_transform" : {
          "transform" : "transform-preview",
          "version" : {
            "created" : "7.7.0"
          },
          "creation_date_in_millis" : 1584738236757
        },
        "created_by" : "transform"
      },
      "properties" : {
        "max_price" : {
          "type" : "half_float"
        },
        "customer_id" : {
          "type" : "keyword"
        }
      }
    },
    "settings" : {
      "index" : {
        "number_of_shards" : "1",
        "auto_expand_replicas" : "0-1"
      }
    },
    "aliases" : { }
  }
}
« 获取转换统计 API 重置转换 API »

On this page

Was this helpful?
Feedback