# Create a database structured loading task

Read structured data from a table, collection, or other supporting object in a database connector and write it to the target data table. This request uses `config_type: 3` and `structured_load_config`; cannot be mixed with `source_config` or `volume_id` from file imports, nor is a target directory field provided.

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

## Before you call

Prepare a database connector, source object, target database or target table that supports structured loading, and mapping of source fields to target columns. The creation page will first read the fields and capabilities of the source object, and then generate the mapping and consistency contract in the request; please use `proof_hash` and `capability_profile_hash` obtained from the same source detection.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: The workspace ID of the task to be created, passed through the `X-Workspace-ID` Header.
- `$IDEMPOTENCY_KEY`: The unique key for this creation request. Reuse this value when retrying the same request to avoid duplicate creation.
- `$CONNECTOR_ID`: Database source connector ID.
- `$DATABASE_ID`: Target database ID.
- `$TARGET_TABLE_ID`: Target table ID already exists.
- `$PROOF_HASH`: The proof-of-consistency hash returned by the origin probe.
- `$CAPABILITY_PROFILE_HASH`: The capability configuration hash returned by the source probe.

## Request example

The following example loads data from MySQL's `sales.orders` into an existing target table in one go. `proof_hash` and `capability_profile_hash` must use the source probe to actually return the value.

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

## Request body

| Field | Type | Is it required | Description |
| --- | --- | --- | --- |
| `config_type` | integer | Yes | Fixed to `3`. |
| `name` | string | No | Task name. |
| `structured_load_config` | object | Yes | Structured load configuration. |
| `structured_load_config.version` | integer | Yes | Fixed to `1`. |
| `source` | object | Yes | Source object. Includes `connector_id`, `source_type`, and `database`; provide `schema`, `table`, or `collection` as required by the source type. |
| `target` | object | Yes | Target table. Includes `mode` and `database_id`; provide `table_id` when `mode: "existing"`, or `table_name` and `create_table` when `mode: "new"`. |
| `target.create_table` | object | Condition required | Create a new target table definition containing the same `name`, optional `description` and `columns` as `target.table_name`. Each column contains `name`, `data_type`, `primary_key`, `nullable`, and can contain `description`, `default_value`, `has_default_value`. |
| `mapping` | object[] | Yes | At least one field mapping. Each item contains the sources `source`, `target_column`, `target_type`, `nullable`, `primary_key`, `allow_duplicate_source`, and can contain `description`, `default_value`, `has_default_value`. The `source` of ordinary database columns can be filled in `kind:"column"` and `column`; the MongoDB field path uses `kind:"mongodb_field_path"` and `mongo_path.segments`. |
| `load_policy` | object | Yes | Load policy. Contains `run_mode`, `initial_load_rule`, `conflict_policy` and the positive integer `max_rows_per_batch`. Periodic tasks must also fill in `sync_strategy`; during full refresh, `full_refresh_write_mode` is `staging_replace`. |
| `schedule` | object | Condition required | Required when `run_mode:"periodic"` is specified. Contains `kind`, `timezone`, fill in `interval` for minute or hour plan, fill in `time_of_day` for daily plan. |
| `hive_partition` | object | No | Partition filtering for Hive sources; contains `enabled`, `fields` and `selection`. |
| `mongo` | object | No | Inference and flattening settings for MongoDB sources. `inference_sample_limit` specifies the number of samples; `flatten` can include `mode`, `paths`, `projection_hash`, `flatten_hash`. |
| `compute` | object | Yes | Compute resource settings, consisting of `task_compute_resource_id`, `query_compute_resource_id` and `priority` (`high`, `normal` or `low`). |
| `consistency_contract` | object | Yes | Source consistency contract, including `contract_kind`, `proof_kind`, `proof_hash`, and `capability_profile_hash`. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

### `load_policy` constraints

| Field | Allowed values | Condition |
| --- | --- | --- |
| `load_policy.run_mode` | `once`, `periodic` | With `periodic`, also provide `schedule` and `sync_strategy`. |
| `load_policy.initial_load_rule` | `append`, `truncate` | `truncate` applies only to an existing target table. |
| `load_policy.conflict_policy` | `fail`, `skip`, `replace` | With `replace`, provide at least one primary-key mapping. |

## Successful response

The task has been accepted when the `code` in the response is `OK`. If the same request is retried with the same idempotent key, the response can contain the `Idempotency-Replayed: true` header.

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

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.task_id` | string | New task ID. |

## Error response

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

### Common HTTP errors

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

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `403`
  - `ErrForbidden`
  - The caller does not have permission to read from the source connector or write to the target table.
  - Check workspace, connector and target resource authorizations.
* - `200`
  - `STRUCTURED_LOAD_CONFIG_INVALID`
  - Configuration fields are missing, target types do not match, or policy combinations are invalid.
  - Correct the corresponding fields according to `data.path` and try again.
* - `200`
  - `STRUCTURED_LOAD_IDEMPOTENCY_KEY_INVALID`
  - An idempotent key is passed repeatedly, or different requests are submitted using the same key.
  - Use a unique key for each new request; only reuse the original key when retrying the same request.
* - `200`
  - `ErrServer`
  - The service failed to create or schedule the task.
  - Check the HTTP status and `code` at the same time, and then query the task details.
```

## Follow-up operations

Log `data.task_id`. Confirm the source, target table, running status and structured load summary through [Query task details](get-import-task.md); use [Query run record](list-import-task-runs.md) to view a single run.