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

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

```text
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` 必须使用来源探测实际返回的值。

```bash
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。

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

响应字段如下。

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

## 错误响应

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 25 30 33

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

## 后续操作

记录 `data.task_id`。通过[查询任务详情](get-import-task.md)确认来源、目标表、运行状态和结构化载入摘要；需要查看单次运行时使用[查询运行记录](list-import-task-runs.md)。