转换会记住创建它的用户在创建时所拥有的角色，并使用这些相同的角色。如果这些角色在源索引和目标索引上没有所需的权限，转换在尝试未经授权的操作时会失败。如果您提供了二次授权头，则使用这些凭据。
您必须使用Kibana或此API来创建转换。不要直接使用Elasticsearch索引API将转换添加到任何.transform-internal*索引中。如果启用了Elasticsearch安全功能，请不要为用户提供任何.transform-internal*索引的权限。如果您在7.5之前使用了转换，也不要为用户提供任何.data-frame-internal*索引的权限。

您必须为您的转换选择最新或透视方法；不能在单个转换中同时使用两者。

路径参数

edit

<transform_id>: (必需，字符串) 转换的标识符。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它的长度限制为 64 个字符，并且必须以字母数字字符开头和结尾。

查询参数

edit

defer_validation: (可选，布尔值) 当 true 时，可推迟的验证不会运行。如果源索引在转换创建之后才存在，这种行为可能是所需的。
timeout: (可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30秒。

请求体

edit

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

dest

(必需，对象) 转换的目标。

Properties of dest

index: (必需，字符串) 转换的目标索引。

在 pivot 转换的情况下，目标索引的映射会尽可能基于源字段推导出来。如果需要其他映射，请在使用转换之前使用 Create index API。

在 latest 转换的情况下，映射永远不会被推断。如果目标索引的动态映射不合适，请在使用转换之前使用 Create index API。

aliases: (可选，对象数组) 转换的目标索引应具有的别名。别名是使用转换的存储凭据进行操作的，这意味着在创建时提供的辅助凭据（如果同时指定了主要和辅助凭据）。

无论目标索引是由转换创建的还是由用户预先创建的，目标索引都会被添加到别名中。

+ .属性 aliases

Details

alias: (必需，字符串) 别名的名称。
move_on_creation: (可选，布尔值) 目标索引是否应是此别名的唯一索引。如果为true，则在将目标索引添加到此别名之前，将从该别名中删除所有其他索引。默认为false。

pipeline: (可选，字符串) ingest pipeline的唯一标识符。

frequency

(可选，时间单位) 当转换以连续模式运行时，检查源索引中更改的时间间隔。最小值为1s，最大值为1h。默认值为1m。

latest

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

Properties of latest

sort: (必填, 字符串) 指定用于标识最新文档的日期字段。
unique_key: (必填, 字符串数组) 指定用于对数据进行分组的一个或多个字段的数组。

_meta: (可选, 对象) 定义可选的转换元数据。

pivot

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

Properties of pivot

aggregations or aggs

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

group_by

(必需，对象) 定义如何对数据进行分组。每个透视表可以定义多个分组。目前支持以下分组：

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

retention_policy

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

Properties of retention_policy

time

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

Properties of time

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

settings

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

Properties of 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。
num_failure_retries: (可选, 整数) 定义在转换任务被标记为 failed 之前，可恢复失败的尝试次数。最小值为 0，最大值为 100。 -1 可以表示无限。在这种情况下，转换永远不会放弃重试可恢复的失败。默认值为集群级别的设置 num_transform_failure_retries。
unattended: (可选, 布尔值) 如果为 true，转换将以无人值守模式运行。在无人值守模式下，转换在发生错误时会无限重试，这意味着转换永远不会失败。设置除无限以外的重试次数将在验证时失败。默认值为 false。

source

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

Properties of source

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

如果任何索引位于远程集群中，则主节点和至少一个转换节点必须具有remote_cluster_client节点角色。
query: (可选, 对象) 一个查询子句，用于从源索引中检索数据子集。参见 Query DSL。
runtime_mappings: (可选, 对象) 定义可由转换使用的搜索时运行时字段。对于搜索运行时字段，所有数据节点（包括远程节点）必须为7.12或更高版本。

sync

(可选, 对象) 定义了持续运行所需的属性转换。

Properties of sync

time

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

Properties of time

delay: (可选, 时间单位) 当前时间与最新输入数据时间之间的时间延迟。默认值是 60s。
field: (必需, 字符串) 用于在源中标识新文档的日期字段。

强烈建议使用包含摄取时间戳的字段。如果使用不同的字段，您可能需要设置delay，以便考虑数据传输延迟。

示例

edit

以下转换使用了 pivot 方法：

PUT _transform/ecommerce_transform1
{
  "source": {
    "index": "kibana_sample_data_ecommerce",
    "query": {
      "term": {
        "geoip.continent_name": {
          "value": "Asia"
        }
      }
    }
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  },
  "description": "Maximum priced ecommerce data by customer_id in Asia",
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform1",
    "pipeline": "add_timestamp_pipeline"
  },
  "frequency": "5m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "60s"
    }
  },
  "retention_policy": {
    "time": {
      "field": "order_date",
      "max_age": "30d"
    }
  }
}

当创建转换时，您会收到以下结果：

{
  "acknowledged" : true
}

以下转换使用了 latest 方法：

PUT _transform/ecommerce_transform2
{
  "source": {
    "index": "kibana_sample_data_ecommerce"
  },
  "latest": {
    "unique_key": ["customer_id"],
    "sort": "order_date"
  },
  "description": "Latest order for each customer",
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform2"
  },
  "frequency": "5m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "60s"
    }
  }
}

删除转换 API

edit

删除一个现有的转换。

请求

edit

DELETE _transform/

前提条件

edit

需要manage_transform集群权限。此权限包含在transform_admin内置角色中。
在删除转换之前，您必须停止它。

路径参数

edit

<transform_id>: (必需, 字符串) 转换的标识符。

查询参数

edit

force: (可选，布尔值) 当 true 时，无论当前状态如何，转换都会被删除。默认值为 false，意味着在删除转换之前，它必须处于 stopped 状态。
delete_dest_index: (可选，布尔值) 当 true 时，目标索引将与转换一起删除。默认值为 false，表示目标索引不会被删除。
timeout: (可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30秒。

示例

edit

DELETE _transform/ecommerce_transform

当删除转换时，您会收到以下结果：

{
  "acknowledged" : true
}

获取转换 API

edit

检索转换的配置信息。

请求

edit

GET _transform/

GET _transform/,

GET _transform/

GET _transform/_all

GET _transform/*

先决条件

edit

需要 monitor_transform 集群权限。此权限包含在 transform_user 内置角色中。

描述

edit

您可以通过使用逗号分隔的标识符列表或通配符表达式，在单个API请求中获取多个转换的信息。您可以通过使用_all，将*指定为，或者省略来获取所有转换的信息。

路径参数

edit

<transform_id>: (可选，字符串) 转换的标识符。它可以是一个转换标识符或通配符表达式。如果你不指定这些选项中的一个，API将返回所有转换的信息。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的转换。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

默认值为 true，在没有匹配项时返回一个空的 transforms 数组，在有部分匹配时返回部分结果。

如果此参数为false，当没有匹配项或只有部分匹配时，请求将返回404状态码。

exclude_generated

(可选, 布尔值) 排除在创建转换时自动添加的字段。这允许配置以可接受的格式被检索，然后添加到另一个集群中。默认值为 false。

from

(可选，整数) 跳过指定数量的转换。默认值是 0。

size

(可选, 整数) 指定要获取的最大转换数量。默认值是 100。

响应体

edit

API返回一个转换资源数组，这些资源按id值的升序排序。有关完整的属性列表，请参阅创建转换API。

create_time: (字符串) 转换创建的时间。例如，1576094542936。此属性是信息性的；您无法更改其值。
version: (字符串) 训练模型创建时的转换配置版本号。

从 Elasticsearch 8.10.0 开始，使用一个新的版本号来跟踪转换插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。version 值表示新的版本号。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

以下示例检索最多十个转换的信息：

GET _transform?size=10

以下示例获取配置信息，用于 ecommerce_transform1 转换：

GET _transform/ecommerce_transform1

API返回以下结果：

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

获取转换统计信息 API

edit

检索转换的使用信息。

请求

edit

GET _transform//_stats

GET _transform/,/_stats

GET _transform/_stats

GET _transform/_all/_stats

GET _transform/*/_stats

先决条件

edit

需要以下权限：

集群: monitor_transform (内置角色 transform_user 授予此权限)
目标索引: read, view_index_metadata.

描述

edit

您可以通过使用逗号分隔的标识符列表或通配符表达式，在单个API请求中获取多个转换的统计信息。您可以通过使用_all，将*指定为，或者省略来获取所有转换的统计信息。

路径参数

edit

<transform_id>: (可选，字符串) 转换的标识符。它可以是一个转换标识符或通配符表达式。如果你不指定这些选项中的一个，API将返回所有转换的信息。

查询参数

edit

allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

包含通配符表达式且没有匹配的转换。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

默认值为 true，在没有匹配项时返回一个空的 transforms 数组，在有部分匹配时返回部分结果。

如果此参数为false，当没有匹配项或只有部分匹配时，请求将返回404状态码。

from

(可选，整数) 跳过指定数量的转换。默认值是 0。

size

(可选, 整数) 指定要获取的最大转换数量。默认值是 100。

响应体

edit

API返回一个转换的统计对象数组，这些对象按id值的升序排序。所有这些属性都是信息性的；您不能更新它们的值。

checkpointing

(对象) 包含关于 checkpoints 的统计信息。

Properties of checkpointing

changes_last_detected_at: (日期) 源索引中最后一次检测到更改的时间戳。

last

(对象) 包含关于最近完成的检查点的统计信息。

Properties of last

checkpoint: (整数) 检查点的序列号。
time_upper_bound_millis: (日期) 使用基于时间的同步时，此时间戳指示包含在检查点中的数据的上限。
timestamp_millis: (日期) 检查点的时间戳，指示检查点创建的时间。

last_search_time

(日期) 源索引中最后一次搜索的时间戳。仅当转换正在运行时，才会显示此字段。

next

(对象) 包含关于当前正在进行中的下一个检查点的统计信息。仅当转换的 state 为 indexing 时，才会出现此对象。

Properties of next

checkpoint: (整数) 检查点的序列号。
checkpoint_progress: (对象) 包含关于检查点进度的统计信息。例如，它列出了 total_docs、docs_remaining、percent_complete、docs_processed 和 docs_indexed。此信息仅适用于批量转换和连续转换的第一个检查点。
time_upper_bound_millis: (日期) 使用基于时间的同步时，此时间戳指示包含在检查点中的数据的上限。
timestamp_millis: (日期) 检查点的时间戳，指示检查点创建的时间。

operations_behind

(整数) 源索引上已发生但尚未应用于目标索引的操作数量。一个较高的数字可能表明转换未能跟上进度。

health

(对象) 此转换的健康指标。

Properties of health

status

(字符串) 此转换的健康状态。状态包括：

green: 转换是健康的。
unknown: 无法确定转换的健康状况。
yellow: 转换的功能处于降级状态，可能需要修复以避免健康状况变为red。
red: 转换正在经历中断或不可用。

issues

(可选, 数组) 如果返回非健康状态, 包含转换的问题列表。

Properties of issues

issue: (字符串) 问题的描述。
details: (可选, 字符串) 关于问题的详细信息。
count: (整数) 自问题开始以来发生的次数。
first_occurrence: (可选, 日期) 此问题首次发生的时间戳。

id

(字符串) 转换的标识符。

node

(对象) 仅对于开始的转换，转换开始的节点。

Properties of node

attributes: (对象) 节点的属性列表。
ephemeral_id: (字符串) 节点的临时ID。
id: (字符串) 节点的唯一标识符。例如，"0-o0tOoRTwKFZifatTWKNw"。
name: (字符串) 节点的名称。例如，0-o0tOo。
transport_address: (字符串) 接受传输HTTP连接的主机和端口。例如，127.0.0.1:9300。

reason

(字符串) 如果一个转换处于失败状态，此属性提供了关于失败原因的详细信息。

state

(字符串) 转换的状态，可以是以下值之一：

aborting: 转换正在中止。
failed: 转换失败。有关失败的更多信息，请检查原因字段。
indexing: 转换正在积极处理数据并创建新文档。
started: 转换正在运行但未积极索引数据。
stopped: 转换已停止。
stopping: 转换正在停止。

stats

(对象) 提供有关转换的统计信息的对象。

Properties of stats

delete_time_in_ms: (long) 删除所花费的时间，以毫秒为单位。
documents_deleted: (long) 由于此转换的保留策略，已从目标索引中删除的文档数量。
documents_indexed: (long) 已为转换索引到目标索引中的文档数量。
documents_processed: (long) 已从转换的源索引中处理的文档数量。
exponential_avg_checkpoint_duration_ms: (double) 检查点持续时间的指数移动平均值，以毫秒为单位。
exponential_avg_documents_indexed: (double) 已索引的新文档数量的指数移动平均值。
exponential_avg_documents_processed: (double) 已处理的文档数量的指数移动平均值。
index_failures: (long) 索引失败的次数。
index_time_in_ms: (long) 索引所花费的时间，以毫秒为单位。
index_total: (long) 索引操作的数量。
pages_processed: (long) 已处理的搜索或批量索引操作的数量。文档以批处理方式处理，而不是单独处理。
processing_time_in_ms: (long) 处理结果所花费的时间，以毫秒为单位。
processing_total: (long) 处理操作的数量。
search_failures: (long) 搜索失败的次数。
search_time_in_ms: (long) 搜索所花费的时间，以毫秒为单位。
search_total: (long) 转换的源索引上的搜索操作数量。
trigger_count: (long) 转换被调度程序触发的次数。例如，调度程序以在 frequency property中指定的间隔触发转换索引器以检查更新或摄取新数据。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

以下示例跳过前五个转换，并获取最多十个结果的使用信息：

GET _transform/_stats?from=5&size=10

以下示例获取转换的用法信息：

GET _transform/ecommerce-customer-transform/_stats

API返回以下结果：

{
  "count" : 1,
  "transforms" : [
    {
      "id" : "ecommerce-customer-transform",
      "state" : "started",
      "node" : {
        "id" : "cpTIGMsVQ8Gqwqlxxxxxxx",
        "name" : "my.home",
        "ephemeral_id" : "5-L21nFsQxxxxxxxxxx-xx",
        "transport_address" : "127.0.0.1:9300",
        "attributes" : { }
      },
      "stats" : {
        "pages_processed" : 78,
        "documents_processed" : 6027,
        "documents_indexed" : 68,
        "documents_deleted": 22,
        "delete_time_in_ms": 214,
        "trigger_count" : 168,
        "index_time_in_ms" : 412,
        "index_total" : 20,
        "index_failures" : 0,
        "search_time_in_ms" : 353,
        "search_total" : 78,
        "search_failures" : 0,
        "processing_time_in_ms" : 8,
        "processing_total" : 78,
        "exponential_avg_checkpoint_duration_ms" : 97.30637923893185,
        "exponential_avg_documents_indexed" : 2.2064915040974062,
        "exponential_avg_documents_processed" : 179.89419945785045
      },
      "checkpointing" : {
        "last" : {
          "checkpoint" : 20,
          "timestamp_millis" : 1585344558220,
          "time_upper_bound_millis" : 1585344498220
        },
        "changes_last_detected_at" : 1585344558219
      },
      "health": {
        "status": "green"
      }
    }
  ]
}

预览转换 API

edit

预览一个转换。

请求

edit

GET _transform//_preview

POST _transform//_preview

GET _transform/_preview

POST _transform/_preview

先决条件

edit

需要以下权限：

集群: manage_transform (内置角色 transform_admin 授予此权限)
源索引: read, view_index_metadata.

描述

edit

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

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

存在一些限制，这可能导致映射不佳。作为一种解决方法，请在开始转换之前创建目标索引或使用您首选映射的索引模板。

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

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

路径参数

edit

<transform_id>: (可选, 字符串) 要预览的转换的ID。

如果你提供作为路径参数，你不能在请求体中提供转换配置的详细信息。

查询参数

edit

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

请求体

edit

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

dest

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

Properties of dest

index: (可选, 字符串) 转换的目标索引。

在 pivot 转换的情况下，目标索引的映射会尽可能基于源字段推导出来。如果需要其他映射，请在使用转换之前使用 Create index API。

在 latest 转换的情况下，映射永远不会被推断。如果目标索引的动态映射不合适，请在使用转换之前使用 Create index API。

pipeline: (可选, 字符串) ingest pipeline的唯一标识符。

frequency

(可选，时间单位) 当转换以连续模式运行时，检查源索引中更改的时间间隔。最小值为1s，最大值为1h。默认值为1m。

latest

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

Properties of latest

sort: (必填, 字符串) 指定用于标识最新文档的日期字段。
unique_key: (必填, 字符串数组) 指定用于对数据进行分组的一个或多个字段的数组。

pivot

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

Properties of pivot

aggregations or aggs

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

group_by

(必需，对象) 定义如何对数据进行分组。每个透视表可以定义多个分组。目前支持以下分组：

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

retention_policy

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

Properties of retention_policy

time

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

Properties of time

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

source

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

Properties of source

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

如果任何索引位于远程集群中，则主节点和至少一个转换节点必须具有remote_cluster_client节点角色。
query: (可选, 对象) 一个查询子句，用于从源索引中检索数据子集。参见 Query DSL。
runtime_mappings: (可选, 对象) 定义可由转换使用的搜索时运行时字段。对于搜索运行时字段，所有数据节点（包括远程节点）必须为7.12或更高版本。

sync

(可选, 对象) 定义了持续运行所需的属性转换。

Properties of sync

time

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

Properties of time

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

settings

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

Properties of 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: (可选, 整数) 定义每个检查点的复合聚合的初始页面大小。如果发生电路 breaker 异常，页面大小将动态调整为较低的值。最小值为 10，最大值为 65,536。默认值为 500。
unattended: (可选, 布尔值) 如果为 true，转换将以无人值守模式运行。在无人值守模式下，转换在发生错误时会无限期重试，这意味着转换永远不会失败。设置除无限次以外的重试次数将在验证时失败。默认值为 false。

响应体

edit

generated_dest_index

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

Properties of generated_dest_index

aliases: (对象) 目标索引的别名。
mappings: (对象) 目标索引中每个文档的映射。
settings: (对象) 目标索引的索引设置。

preview

(数组) 文档数组。特别是，它们是转换在目标索引中创建的文档的 JSON 表示形式。

示例

edit

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

此示例返回的数据如下：

{
  "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

edit

重置一个变换。

请求

edit

POST _transform//_reset

先决条件

edit

需要manage_transform集群权限。此权限包含在transform_admin内置角色中。

描述

edit

在重置变换之前，您必须停止它；或者，使用force查询参数。

如果你重置一个转换，所有检查点、状态以及目标索引（如果它是由转换创建的）都将被删除。转换会被更新到最新格式，就像使用了Update transform API一样。转换已准备好重新启动，就像它刚刚被创建一样。

路径参数

edit

<transform_id>: (必需, 字符串) 转换的标识符。

查询参数

edit

force: (可选, 布尔值) 如果此值为 true，则无论当前状态如何，转换都会重置。如果为 false，则转换必须在重置之前处于 stopped 状态。默认值为 false
timeout: (可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30秒。

示例

edit

POST _transform/ecommerce_transform/_reset

当重置变换时，您会收到以下结果：

{
  "acknowledged" : true
}

立即安排转换 API

edit

立即运行一个转换来处理数据。

请求

edit

POST _transform//_schedule_now

先决条件

edit

需要manage_transform集群权限。此权限包含在transform_admin内置角色中。

描述

edit

当您运行此API时，处理下一个检查点的操作会立即开始，而不会等待配置的frequency间隔。API会立即返回，数据处理在后台进行。随后，除非在此期间再次调用API，否则转换将在now + frequency时再次处理。

路径参数

edit

<transform_id>: (必需, 字符串) 转换的标识符。

查询参数

edit

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

示例

edit

POST _transform/ecommerce_transform/_schedule_now

当转换立即安排时，您会收到以下结果：

{
  "acknowledged" : true
}

开始转换 API

edit

开始一个转换。

请求

edit

POST _transform//_start

先决条件

edit

需要以下权限：

集群：manage_transform（内置角色transform_admin授予此权限）

描述

edit

当你开始一个转换时，如果目标索引尚不存在，它会创建目标索引。number_of_shards 被设置为 1，而 auto_expand_replicas 被设置为 0-1。

如果是数据透视转换，它会根据源索引和转换聚合推导出目标索引的映射定义。如果目标索引中的字段是从脚本派生的（例如在 scripted_metric 或 bucket_script 聚合的情况下），转换将使用动态映射，除非存在索引模板。

如果是最新的转换，它不会推导映射定义；它使用动态映射。

要使用显式映射，请在开始转换之前创建目标索引。或者，您可以创建一个索引模板，尽管它不会影响透视转换中的推导映射。

当转换开始时，会进行一系列验证以确保其成功。如果在创建转换时推迟了验证，则在启动转换时会进行这些验证——除了权限检查之外。当启用了Elasticsearch安全功能时，转换会记住创建它的用户在创建时所拥有的角色，并使用这些相同的角色。如果这些角色在源索引和目标索引上没有所需的权限，则在尝试进行未经授权的操作时，转换将失败。

路径参数

edit

<transform_id>: (必需, 字符串) 转换的标识符。

查询参数

edit

from: (可选，字符串) 限制转换后的实体为在此时间之后更改的实体。支持相对时间，如 now-30d。仅适用于连续转换。
timeout: (可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30秒。

示例

edit

POST _transform/ecommerce_transform/_start

当转换开始时，您会收到以下结果：

{
  "acknowledged" : true
}

停止转换 API

edit

停止一个或多个转换。

请求

edit

POST _transform//_stop

POST _transform/,/_stop

POST _transform/_all/_stop

先决条件

edit

需要 manage_transform 集群权限。此权限包含在 transform_admin 内置角色中。

路径参数

edit

<transform_id>: (必需，字符串) 转换的标识符。要停止多个转换，请使用逗号分隔的列表或通配符表达式。要停止所有转换，请使用 _all 或 * 作为标识符。

查询参数

edit

allow_no_match

(可选，布尔值) 指定当请求时执行的操作：

包含通配符表达式且没有匹配的转换。
包含 _all 字符串或没有标识符且没有匹配项。
包含通配符表达式且只有部分匹配。

默认值为 true，在没有匹配项时返回成功的确认消息。当只有部分匹配时，API 会停止相应的转换。例如，如果请求包含 test-id1*,test-id2* 作为标识符，并且没有与 test-id2* 匹配的转换，API 仍然会停止与 test-id1* 匹配的转换。

如果此参数为false，当没有匹配项或只有部分匹配时，请求将返回404状态码。

force

(可选，布尔值) 设置为 true 以停止失败的转换，或强制停止未响应初始停止请求的转换。

timeout

(可选，时间值) 如果 wait_for_completion=true，API 会阻塞（最多）指定的时间，等待转换停止。如果超过 timeout 时间，API 会抛出一个超时异常。即使抛出超时异常，停止请求仍然在处理，并最终将转换移动到 STOPPED 状态。超时仅仅意味着 API 调用本身在等待状态变化时超时了。默认值为 30s。

wait_for_checkpoint

(可选，布尔值) 如果设置为 true，转换将在当前检查点完成之前不会完全停止。如果设置为 false，转换将尽快停止。默认为 false。

wait_for_completion

(可选, 布尔值) 如果设置为 true，将导致 API 阻塞，直到索引器状态完全停止。如果设置为 false，API 将立即返回，索引器将在后台异步停止。默认为 false。

响应代码

edit

404 (Missing resources): 如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

POST _transform/ecommerce_transform/_stop

当转换停止时，您会收到以下结果：

{
  "acknowledged" : true
}

更新转换 API

edit

更新变换的某些属性。

请求

edit

POST _transform//_update

先决条件

edit

需要以下权限：

集群：manage_transform（内置角色 transform_admin 授予此权限）
源索引：read、view_index_metadata
目标索引：read、index。如果配置了 retention_policy，则还需要 delete 索引权限。

描述

edit

此API更新现有转换。您可以更新的属性列表是您在创建转换时可以定义的属性列表的子集。

当更新转换时，会进行一系列验证以确保其成功。您可以使用defer_validation参数跳过这些检查。

除描述外的所有更新属性在下次检查点开始转换之前不会生效。这是为了确保每个检查点的数据一致性。

您的转换会记住更新时更新它的用户所拥有的角色，并以这些权限运行。如果您提供二次授权头，则使用这些凭证。
您必须使用Kibana或此API来更新转换。不支持直接更新任何转换内部、系统或隐藏索引，这可能会导致永久性失败。

路径参数

edit

<transform_id>: (必需, 字符串) 转换的标识符。

查询参数

edit

defer_validation: (可选，布尔值) 当 true 时，可推迟的验证不会运行。如果源索引在转换更新后才存在，这种行为可能是所需的。
timeout: (可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30秒。

请求体

edit

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

dest

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

Properties of dest

index: (必需, 字符串) 转换的目标索引。

在 pivot 转换的情况下，目标索引的映射会尽可能基于源字段推导出来。如果需要其他映射，请在使用转换之前使用 Create index API。

在 latest 转换的情况下，映射永远不会被推断。如果目标索引的动态映射不合适，请在使用转换之前使用 Create index API。

aliases: (可选, 对象数组) 转换的目标索引应具有的别名。别名是使用转换存储的凭据进行操作的，这意味着在创建时提供的辅助凭据（如果同时指定了主要和辅助凭据）。

无论目标索引是由转换创建的还是由用户预先创建的，目标索引都会被添加到别名中。

+ .属性 aliases

Details

alias: (必需, 字符串) 别名的名称。
move_on_creation: (可选, 布尔值) 目标索引是否应是此别名中的唯一索引。如果为 true，在将目标索引添加到此别名之前，将从此别名中移除所有其他索引。默认为 false。

pipeline: (可选, 字符串) ingest pipeline 的唯一标识符。

frequency

(可选，时间单位) 当转换以连续模式运行时，检查源索引中更改的时间间隔。最小值为1s，最大值为1h。默认值为1m。

_meta: (可选, 对象) 定义可选的转换元数据。

retention_policy

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

Properties of retention_policy

time

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

Properties of time

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

settings

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

Properties of 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。
num_failure_retries: (可选, 整数) 定义在转换任务被标记为 failed 之前，可恢复失败的尝试次数。最小值为 0，最大值为 100。 -1 可以表示无限。在这种情况下，转换永远不会放弃重试可恢复的失败。默认值为集群级别的设置 num_transform_failure_retries。
unattended: (可选, 布尔值) 如果为 true，转换将以无人值守模式运行。在无人值守模式下，转换在发生错误时会无限重试，这意味着转换永远不会失败。设置除无限以外的重试次数将在验证时失败。默认值为 false。

source

(可选, 对象) 转换数据的来源。

Properties of source

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

如果任何索引位于远程集群中，则主节点和至少一个转换节点必须具有remote_cluster_client节点角色。
query: (可选, 对象) 一个查询子句，用于从源索引中检索数据子集。参见 Query DSL。

sync

(可选, 对象) 定义了持续运行所需的属性转换。

只有在是连续转换的情况下，您才能更新这些属性。您不能将批量转换更改为连续转换，反之亦然。相反，在Kibana中克隆转换并添加或删除sync属性。

Properties of sync

time

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

Properties of time

delay: (可选, 时间单位) 当前时间与最新输入数据时间之间的时间延迟。默认值是60s。
field: (必需, 字符串) 用于在源中标识新文档的日期字段。

通常，使用包含摄取时间戳的字段是一个好主意。如果你使用不同的字段，你可能需要设置delay，以便它考虑到数据传输延迟。

示例

edit

POST _transform/simple-kibana-ecomm-pivot/_update
{
  "source": {
    "index": "kibana_sample_data_ecommerce",
    "query": {
      "term": {
        "geoip.continent_name": {
          "value": "Asia"
        }
      }
    }
  },
  "description": "Maximum priced ecommerce data by customer_id in Asia",
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform_v2",
    "pipeline": "add_timestamp_pipeline"
  },
  "frequency": "15m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "120s"
    }
  }
}

当转换更新时，您会收到更新后的配置：

{
  "id" : "simple-kibana-ecomm-pivot",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "version" : "8.4.0",
  "create_time" : 1656113450613,
  "source" : {
    "index" : [
      "kibana_sample_data_ecommerce"
    ],
    "query" : {
      "term" : {
        "geoip.continent_name" : {
          "value" : "Asia"
        }
      }
    }
  },
  "dest" : {
    "index" : "kibana_sample_data_ecommerce_transform_v2",
    "pipeline" : "add_timestamp_pipeline"
  },
  "frequency" : "15m",
  "sync" : {
    "time" : {
      "field" : "order_date",
      "delay" : "120s"
    }
  },
  "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" : { }
}

升级转换 API

edit

升级所有变换。

请求

edit

POST _transform/_upgrade

先决条件

edit

需要以下权限：

集群：manage_transform（内置角色transform_admin授予此权限）

描述

edit

转换在次要版本之间和支持的主要版本之间是兼容的。然而，随着时间的推移，转换配置信息的格式可能会发生变化。此API识别具有旧配置格式的转换，并将它们升级到最新版本；包括清理存储转换状态和检查点的内部数据结构。转换升级不会影响源索引和目标索引。

从 Elasticsearch 8.10.0 开始，使用了一个新的版本号来跟踪转换插件中的配置和状态变化。这个新的版本号与产品版本解耦，并将独立递增。

如果转换升级步骤失败，升级将停止，并返回有关底层问题的错误。解决该问题后，重新运行该过程。升级完成后会返回一个总结。

为了确保在集群主要版本升级期间（例如从7.16升级到8.0）持续转换保持运行，建议在升级集群之前升级转换。您可能希望在升级之前执行最近的集群备份。

当启用了Elasticsearch安全功能时，您的转换会记住最后创建或更新它的用户的角色。与更新转换不同，转换升级不会更改存储的角色，因此用于读取源数据和写入目标索引的角色保持不变。

查询参数

edit

dry_run: (可选，布尔值) 当 true 时，仅检查更新但不执行它们。默认为 false。
timeout: (可选，时间) 等待响应的时间段。如果在超时到期之前未收到响应，请求将失败并返回错误。默认为 30秒。

响应体

edit

needs_update: (整数) 需要升级的转换数量。
no_action: (整数) 不需要升级的转换数量。
updated: (整数) 已升级的转换数量。

示例

edit

要升级旧版转换为最新的配置格式，请执行以下 API 调用：

POST _transform/_upgrade

当所有转换都升级后，您会收到一个总结：

{
  "needs_update": 0,
  "updated": 2,
  "no_action": 1
}

« Text structure APIs Usage API »