Link Search Menu Expand Document Documentation Menu
文档

转换 API

除了使用 OpenSearch Dashboards，您还可以使用 REST API 来创建、启动、停止和完成与转换作业相关的其他操作。

目录

创建转换作业

1.0 版引入

创建一个转换作业。

请求格式

PUT _plugins/_transform/<transform_id>

路径参数

参数 数据类型 描述
transform_id 字符串 转换 ID

请求正文字段

您可以在 HTTP 请求正文中指定以下选项

选项 数据类型 描述 必需
enabled 布尔型 如果为 true，转换作业将在创建时启用。 否
continuous 布尔型 指定转换作业是否应为连续作业。连续作业每次都根据 schedule 字段中指定的时间表执行，并基于新转换的桶以及添加到源索引的任何新数据运行。非连续作业仅执行一次。默认为 false。 否
schedule 对象 转换作业的时间表。 是
start_time 整数 转换作业的 Unix 纪元开始时间。 是
description 字符串 描述转换作业。 否
metadata_id 字符串 与转换作业关联的任何元数据。 否
source_index 字符串 包含要转换数据的源索引。 是
target_index 字符串 新转换数据添加到的目标索引。您可以创建新索引或更新现有索引。 是
data_selection_query 对象 用于过滤转换作业源索引子集的查询 DSL。有关更多信息，请参阅查询领域特定语言 (DSL)。 是
page_size 整数 IM 并发处理和索引的桶数量。数字越高，性能越好，但需要更多内存。如果您的机器内存不足，索引管理 (IM) 会自动调整此字段并重试，直到操作成功。 是
groups 数组 指定在转换作业中使用的分组。支持的分组有 terms、histogram 和 date_histogram。有关更多信息，请参阅桶聚合。 如果不使用聚合，则为是。
source_field 字符串 要转换的字段。 是
aggregations 对象 在转换作业中使用的聚合。支持的聚合有 sum、max、min、value_count、avg、scripted_metric 和 percentiles。有关更多信息，请参阅度量聚合。 如果不使用分组，则为是。

示例请求

以下请求创建一个 ID 为 sample 的转换作业

PUT _plugins/_transform/sample
{
  "transform": {
    "enabled": true,
    "continuous": true,
    "schedule": {
      "interval": {
        "period": 1,
        "unit": "Minutes",
        "start_time": 1602100553
      }
    },
    "description": "Sample transform job",
    "source_index": "sample_index",
    "target_index": "sample_target",
    "data_selection_query": {
      "match_all": {}
    },
    "page_size": 1,
    "groups": [
      {
        "terms": {
          "source_field": "customer_gender",
          "target_field": "gender"
        }
      },
      {
        "terms": {
          "source_field": "day_of_week",
          "target_field": "day"
        }
      }
    ],
    "aggregations": {
      "quantity": {
        "sum": {
          "field": "total_quantity"
        }
      }
    }
  }
}

示例响应

{
  "_id": "sample",
  "_version": 7,
  "_seq_no": 13,
  "_primary_term": 1,
  "transform": {
    "transform_id": "sample",
    "schema_version": 7,
    "continuous": true,
    "schedule": {
      "interval": {
        "start_time": 1621467964243,
        "period": 1,
        "unit": "Minutes"
      }
    },
    "metadata_id": null,
    "updated_at": 1621467964243,
    "enabled": true,
    "enabled_at": 1621467964243,
    "description": "Sample transform job",
    "source_index": "sample_index",
    "data_selection_query": {
      "match_all": {
        "boost": 1.0
      }
    },
    "target_index": "sample_target",
    "roles": [],
    "page_size": 1,
    "groups": [
      {
        "terms": {
          "source_field": "customer_gender",
          "target_field": "gender"
        }
      },
      {
        "terms": {
          "source_field": "day_of_week",
          "target_field": "day"
        }
      }
    ],
    "aggregations": {
      "quantity": {
        "sum": {
          "field": "total_quantity"
        }
      }
    }
  }
}

更新转换作业

1.0 版引入

如果 transform_id 已存在，则更新转换作业。对于此请求，您必须指定要更新的转换的序列号和主术语。要获取这些信息，请使用获取转换作业详情 API 调用。

请求格式

PUT _plugins/_transform/<transform_id>?if_seq_no=<seq_no>&if_primary_term=<primary_term>

查询参数

更新操作支持以下查询参数

参数 描述 必需
if_seq_no 仅当更改转换作业的最后操作具有指定序列号时才执行转换操作。 是
if_primary_term 仅当更改转换作业的最后操作具有指定主术语时才执行转换操作。 是

请求正文字段

您可以更新以下字段。

选项 数据类型 描述
schedule 对象 转换作业的时间表。包含字段 interval.start_time、interval.period 和 interval.unit。
start_time 整数 转换作业的 Unix 纪元开始时间。
period 整数 转换作业的执行频率。
unit 字符串 与执行周期关联的时间单位。可用选项包括 Minutes（分钟）、Hours（小时）和 Days（天）。
description 整数 描述转换作业。
page_size 整数 IM 并发处理和索引的桶数量。数字越高，性能越好，但需要更多内存。如果您的机器内存不足，IM 会自动调整此字段并重试，直到操作成功。

示例请求

以下请求更新 ID 为 sample、序列号为 13、主术语为 1 的转换作业

PUT _plugins/_transform/sample?if_seq_no=13&if_primary_term=1
{
  "transform": {
  "enabled": true,
  "schedule": {
    "interval": {
    "period": 1,
    "unit": "Minutes",
    "start_time": 1602100553
    }
  },
  "description": "Sample transform job",
  "source_index": "sample_index",
  "target_index": "sample_target",
  "data_selection_query": {
    "match_all": {}
  },
  "page_size": 1,
  "groups": [
    {
    "terms": {
      "source_field": "customer_gender",
      "target_field": "gender"
    }
    },
    {
    "terms": {
      "source_field": "day_of_week",
      "target_field": "day"
    }
    }
  ],
  "aggregations": {
    "quantity": {
    "sum": {
      "field": "total_quantity"
    }
    }
  }
  }
}

示例响应

PUT _plugins/_transform/sample?if_seq_no=13&if_primary_term=1
{
  "transform": {
    "enabled": true,
    "schedule": {
      "interval": {
        "period": 1,
        "unit": "Minutes",
        "start_time": 1602100553
      }
    },
    "description": "Sample transform job",
    "source_index": "sample_index",
    "target_index": "sample_target",
    "data_selection_query": {
      "match_all": {}
    },
    "page_size": 1,
    "groups": [
      {
        "terms": {
          "source_field": "customer_gender",
          "target_field": "gender"
        }
      },
      {
        "terms": {
          "source_field": "day_of_week",
          "target_field": "day"
        }
      }
    ],
    "aggregations": {
      "quantity": {
        "sum": {
          "field": "total_quantity"
        }
      }
    }
  }
}

获取转换作业详情

1.0 版引入

返回转换作业详情。

请求格式

GET _plugins/_transform/<transform_id>

示例请求

以下请求返回 ID 为 sample 的转换作业详情

GET _plugins/_transform/sample

示例响应

{
  "_id": "sample",
  "_version": 7,
  "_seq_no": 13,
  "_primary_term": 1,
  "transform": {
    "transform_id": "sample",
    "schema_version": 7,
    "continuous": true,
    "schedule": {
      "interval": {
        "start_time": 1621467964243,
        "period": 1,
        "unit": "Minutes"
      }
    },
    "metadata_id": null,
    "updated_at": 1621467964243,
    "enabled": true,
    "enabled_at": 1621467964243,
    "description": "Sample transform job",
    "source_index": "sample_index",
    "data_selection_query": {
      "match_all": {
        "boost": 1.0
      }
    },
    "target_index": "sample_target",
    "roles": [],
    "page_size": 1,
    "groups": [
      {
        "terms": {
          "source_field": "customer_gender",
          "target_field": "gender"
        }
      },
      {
        "terms": {
          "source_field": "day_of_week",
          "target_field": "day"
        }
      }
    ],
    "aggregations": {
      "quantity": {
        "sum": {
          "field": "total_quantity"
        }
      }
    }
  }
}

您也可以通过省略 transform_id 来获取所有转换作业的详情。

示例请求

以下请求返回所有转换作业的详情

GET _plugins/_transform/

示例响应

{
  "total_transforms": 1,
  "transforms": [
    {
      "_id": "sample",
      "_seq_no": 13,
      "_primary_term": 1,
      "transform": {
        "transform_id": "sample",
        "schema_version": 7,
        "continuous": true,
        "schedule": {
          "interval": {
            "start_time": 1621467964243,
            "period": 1,
            "unit": "Minutes"
          }
        },
        "metadata_id": null,
        "updated_at": 1621467964243,
        "enabled": true,
        "enabled_at": 1621467964243,
        "description": "Sample transform job",
        "source_index": "sample_index",
        "data_selection_query": {
          "match_all": {
            "boost": 1.0
          }
        },
        "target_index": "sample_target",
        "roles": [],
        "page_size": 1,
        "groups": [
          {
            "terms": {
              "source_field": "customer_gender",
              "target_field": "gender"
            }
          },
          {
            "terms": {
              "source_field": "day_of_week",
              "target_field": "day"
            }
          }
        ],
        "aggregations": {
          "quantity": {
            "sum": {
              "field": "total_quantity"
            }
          }
        }
      }
    }
  ]
}

查询参数

您可以指定以下 GET API 操作的查询参数来过滤结果。

参数 描述 必需
from 要返回的起始转换。默认为 0。 否
size 指定要返回的转换数量。默认为 10。 否
search 用于过滤结果的搜索词。 否
sortField 用于对结果进行排序的字段。 否
sortDirection 指定结果的排序方向。可以是 ASC（升序）或 DESC（降序）。默认为 ASC。 否

示例请求

以下请求返回从转换 8 开始的两个结果

GET _plugins/_transform?size=2&from=8

示例响应

{
  "total_transforms": 18,
  "transforms": [
    {
      "_id": "sample8",
      "_seq_no": 93,
      "_primary_term": 1,
      "transform": {
        "transform_id": "sample8",
        "schema_version": 7,
        "schedule": {
          "interval": {
            "start_time": 1622063596812,
            "period": 1,
            "unit": "Minutes"
          }
        },
        "metadata_id": "y4hFAB2ZURQ2dzY7BAMxWA",
        "updated_at": 1622063657233,
        "enabled": false,
        "enabled_at": null,
        "description": "Sample transform job",
        "source_index": "sample_index3",
        "data_selection_query": {
          "match_all": {
            "boost": 1.0
          }
        },
        "target_index": "sample_target3",
        "roles": [],
        "page_size": 1,
        "groups": [
          {
            "terms": {
              "source_field": "customer_gender",
              "target_field": "gender"
            }
          },
          {
            "terms": {
              "source_field": "day_of_week",
              "target_field": "day"
            }
          }
        ],
        "aggregations": {
          "quantity": {
            "sum": {
              "field": "total_quantity"
            }
          }
        }
      }
    },
    {
      "_id": "sample9",
      "_seq_no": 98,
      "_primary_term": 1,
      "transform": {
        "transform_id": "sample9",
        "schema_version": 7,
        "schedule": {
          "interval": {
            "start_time": 1622063598065,
            "period": 1,
            "unit": "Minutes"
          }
        },
        "metadata_id": "x8tCIiYMTE3veSbIJkit5A",
        "updated_at": 1622063658388,
        "enabled": false,
        "enabled_at": null,
        "description": "Sample transform job",
        "source_index": "sample_index4",
        "data_selection_query": {
          "match_all": {
            "boost": 1.0
          }
        },
        "target_index": "sample_target4",
        "roles": [],
        "page_size": 1,
        "groups": [
          {
            "terms": {
              "source_field": "customer_gender",
              "target_field": "gender"
            }
          },
          {
            "terms": {
              "source_field": "day_of_week",
              "target_field": "day"
            }
          }
        ],
        "aggregations": {
          "quantity": {
            "sum": {
              "field": "total_quantity"
            }
          }
        }
      }
    }
  ]
}

启动转换作业

1.0 版引入

使用 API 创建的转换作业会自动启用，但如果您需要启用某个作业，可以使用启动 API 操作。

请求格式

POST _plugins/_transform/<transform_id>/_start

示例请求

以下请求启动 ID 为 sample 的转换作业

POST _plugins/_transform/sample/_start

示例响应

{
  "acknowledged": true
}

停止转换作业

1.0 版引入

停止一个转换作业。

请求格式

POST _plugins/_transform/<transform_id>/_stop

示例请求

以下请求停止 ID 为 sample 的转换作业

POST _plugins/_transform/sample/_stop

示例响应

{
  "acknowledged": true
}

获取转换作业状态

1.0 版引入

返回转换作业的状态和元数据。

请求格式

GET _plugins/_transform/<transform_id>/_explain

示例请求

以下请求返回 ID 为 sample 的转换作业详情

GET _plugins/_transform/sample/_explain

示例响应

{
  "sample": {
    "metadata_id": "PzmjweME5xbgkenl9UpsYw",
    "transform_metadata": {
      "continuous_stats": {
        "last_timestamp": 1621883525672,
        "documents_behind": {
          "sample_index": 72
          }
      },
      "transform_id": "sample",
      "last_updated_at": 1621883525873,
      "status": "finished",
      "failure_reason": "null",
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "documents_indexed": 0,
        "index_time_in_millis": 0,
        "search_time_in_millis": 0
      }
    }
  }
}

预览转换作业结果

1.0 版引入

返回转换后的索引的预览效果。

示例请求

POST _plugins/_transform/_preview

{
  "transform": {
  "enabled": false,
  "schedule": {
    "interval": {
    "period": 1,
    "unit": "Minutes",
    "start_time": 1602100553
    }
  },
  "description": "test transform",
  "source_index": "sample_index",
  "target_index": "sample_target",
  "data_selection_query": {
    "match_all": {}
  },
  "page_size": 10,
  "groups": [
    {
    "terms": {
      "source_field": "customer_gender",
      "target_field": "gender"
    }
    },
    {
    "terms": {
      "source_field": "day_of_week",
      "target_field": "day"
    }
    }
  ],
  "aggregations": {
    "quantity": {
    "sum": {
      "field": "total_quantity"
    }
    }
  }
  }
}

示例响应

{
  "documents" : [
  {
    "quantity" : 862.0,
    "gender" : "FEMALE",
    "day" : "Friday"
  },
  {
    "quantity" : 682.0,
    "gender" : "FEMALE",
    "day" : "Monday"
  },
  {
    "quantity" : 772.0,
    "gender" : "FEMALE",
    "day" : "Saturday"
  },
  {
    "quantity" : 669.0,
    "gender" : "FEMALE",
    "day" : "Sunday"
  },
  {
    "quantity" : 887.0,
    "gender" : "FEMALE",
    "day" : "Thursday"
  }
  ]
}

删除转换作业

1.0 版引入

删除一个转换作业。此操作不会删除源索引或目标索引。

请求格式

DELETE _plugins/_transform/<transform_id>

示例请求

以下请求删除 ID 为 sample 的转换作业

DELETE _plugins/_transform/sample

示例响应

{
  "took": 205,
  "errors": false,
  "items": [
    {
      "delete": {
        "_index": ".opensearch-ism-config",
        "_id": "sample",
        "_version": 4,
        "result": "deleted",
        "forced_refresh": true,
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": 6,
        "_primary_term": 1,
        "status": 200
      }
    }
  ]
}
剩余 350 字符

有问题？。

想贡献？ 或 。