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.

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.

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.

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

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

Common HTTP errors¶

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; use Query run record to view a single run.

Last updated on Sep 3, 2026