创建数据库结构化载入任务¶

从数据库连接器中的表、集合或其他支持对象读取结构化数据，并写入目标数据表。该请求使用 config_type: 3 和 structured_load_config；不能与文件导入的 source_config 或 volume_id 混用，也不提供目标目录字段。

POST https://moi.matrixorigin.cn/newmoi/task

调用前准备¶

准备支持结构化载入的数据库连接器、来源对象、目标数据库或目标表，以及来源字段到目标列的映射。创建页会先读取来源对象的字段和能力，再生成请求中的映射与一致性契约；请使用同一次来源探测得到的 proof_hash 和 capability_profile_hash。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：要创建任务的工作区 ID，通过 X-Workspace-ID Header 传递。
$IDEMPOTENCY_KEY：本次创建请求的唯一键。重试同一请求时复用该值，避免重复创建。
$CONNECTOR_ID：数据库来源连接器 ID。
$DATABASE_ID：目标数据库 ID。
$TARGET_TABLE_ID：已有目标表 ID。
$PROOF_HASH：来源探测返回的一致性证明哈希。
$CAPABILITY_PROFILE_HASH：来源探测返回的能力配置哈希。

请求体¶

字段	类型	是否必填	说明
`config_type`	integer	是	固定为 `3`。
`name`	string	否	任务名称。
`structured_load_config`	object	是	结构化载入配置。
`structured_load_config.version`	integer	是	固定为 `1`。
`source`	object	是	来源对象。包含 `connector_id`、`source_type`、`database`，并按来源类型填写 `schema`、`table` 或 `collection`。支持的 `source_type` 包括 `SOURCE_TYPE_HIVE`、`SOURCE_TYPE_MYSQL`、`SOURCE_TYPE_SQLSERVER`、`SOURCE_TYPE_ORACLE`、`SOURCE_TYPE_POSTGRESQL` 和 `SOURCE_TYPE_MONGODB`。
`target`	object	是	目标表。包含 `mode` 与 `database_id`。`mode: "existing"` 时填写 `table_id`；`mode: "new"` 时填写 `table_name` 和 `create_table`。
`target.create_table`	object	条件必填	新建目标表定义，包含与 `target.table_name` 相同的 `name`、可选 `description` 和 `columns`。每列包含 `name`、`data_type`、`primary_key`、`nullable`，并可包含 `description`、`default_value`、`has_default_value`。
`mapping`	object（对象数组）	是	至少一项字段映射。每项包含来源 `source`、`target_column`、`target_type`、`nullable`、`primary_key`、`allow_duplicate_source`，并可包含 `description`、`default_value`、`has_default_value`。普通数据库列的 `source` 可填写 `kind:"column"` 和 `column`；MongoDB 字段路径使用 `kind:"mongodb_field_path"` 和 `mongo_path.segments`。
`load_policy`	object	是	载入策略。包含 `run_mode`、`initial_load_rule`、`conflict_policy` 和正整数 `max_rows_per_batch`。周期任务还必须填写 `sync_strategy`；全量刷新时 `full_refresh_write_mode` 为 `staging_replace`。
`schedule`	object	条件必填	`run_mode:"periodic"` 时必填。包含 `kind`、`timezone`，分钟或小时计划填写 `interval`，每天计划填写 `time_of_day`。
`hive_partition`	object	否	Hive 来源的分区筛选；包含 `enabled`、`fields` 和 `selection`。
`mongo`	object	否	MongoDB 来源的推断和展平设置。`inference_sample_limit` 指定样本数量；`flatten` 可包含 `mode`、`paths`、`projection_hash`、`flatten_hash`。
`compute`	object	是	计算资源设置，包含 `task_compute_resource_id`、`query_compute_resource_id` 和 `priority`（`high`、`normal` 或 `low`）。
`consistency_contract`	object	是	来源一致性契约。包含 `contract_kind`、`proof_kind`、`proof_hash`、`capability_profile_hash`；按来源能力可附加水位线和并列字段等约束。

`load_policy` 约束¶

字段	可用值	条件
`load_policy.run_mode`	`once`、`periodic`	`periodic` 时还必须提供 `schedule` 和 `sync_strategy`。
`load_policy.initial_load_rule`	`append`、`truncate`	`truncate` 仅适用于已有目标表。
`load_policy.conflict_policy`	`fail`、`skip`、`replace`	`replace` 时至少提供一个主键映射。

请求示例¶

下面示例从 MySQL 的 sales.orders 一次性载入数据到已有目标表。proof_hash 和 capability_profile_hash 必须使用来源探测实际返回的值。

curl -X POST "https://moi.matrixorigin.cn/newmoi/task" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "config_type":3,
    "name":"orders-once",
    "structured_load_config":{
      "version":1,
      "source":{"connector_id":"'"$CONNECTOR_ID"'","source_type":"SOURCE_TYPE_MYSQL","database":"sales","table":"orders"},
      "target":{"mode":"existing","database_id":"'"$DATABASE_ID"'","table_id":"'"$TARGET_TABLE_ID"'"},
      "mapping":[
        {"source":{"kind":"column","column":"order_id"},"target_column":"order_id","target_type":"BIGINT","nullable":false,"primary_key":true,"allow_duplicate_source":false}
      ],
      "load_policy":{"run_mode":"once","initial_load_rule":"append","conflict_policy":"fail","max_rows_per_batch":10000},
      "compute":{"task_compute_resource_id":"default","query_compute_resource_id":"default","priority":"normal"},
      "consistency_contract":{"contract_kind":"worker_proved_persistent_watermark","proof_kind":"db_metadata","proof_hash":"'"$PROOF_HASH"'","capability_profile_hash":"'"$CAPABILITY_PROFILE_HASH"'"}
    }
  }'

成功响应¶

当响应中的 code 为 OK 时，任务已受理。若带相同幂等键重试同一请求，响应可包含 Idempotency-Replayed: true Header。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "task_id": "task_01"
  }
}

响应字段如下。

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data.task_id`	string	新建任务 ID。

错误响应¶

{
  "code": "STRUCTURED_LOAD_CONFIG_INVALID",
  "msg": "invalid structured load configuration",
  "data": {
    "path": "structured_load_config.target"
  }
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`403`	`ErrForbidden`	调用者无权读取来源连接器或写入目标表。	检查工作区、连接器和目标资源授权。
`200`	`STRUCTURED_LOAD_CONFIG_INVALID`	配置字段缺失、目标类型不匹配或策略组合无效。	根据 `data.path` 修正对应字段后重试。
`200`	`STRUCTURED_LOAD_IDEMPOTENCY_KEY_INVALID`	幂等键重复传递，或使用同一键提交了不同请求。	每个新请求使用唯一键；仅重试同一请求时复用原键。
`200`	`ErrServer`	服务未能创建或调度任务。	同时检查 HTTP 状态和 `code`，再查询任务详情。

后续操作¶

记录 data.task_id。通过查询任务详情确认来源、目标表、运行状态和结构化载入摘要；需要查看单次运行时使用查询运行记录。

最后更新于 2026 年 8 月 22 日