Create table¶

Creates a table in the specified database.

POST https://moi.matrixorigin.cn/newmoi/catalog/table/create

Preparation before calling¶

First query the database list to obtain the target database ID. Prepare the personal access token, target workspace ID, and database ID that have access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$DATABASE_ID: The target database ID under which the table is to be created.

Table creation is not possible for system, retention, or subscription databases.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/table/create" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "database_id": '"$DATABASE_ID"',
    "name": "<TABLE_NAME>",
    "columns": [
      {
        "name": "id",
        "type": "INT",
        "is_pk": true
      },
      {
        "name": "amount",
        "type": "DECIMAL"
      }
    ]
  }'

Request body¶

Parameter	Type	Required	Description
`database_id`	integer	Yes	Target database ID.
`name`	string	Yes	Table name, must be a valid identifier.
`columns`	array	Yes	A column definition. Each item must contain at least a column name and type.
`comment`	string	No	Table comment.
`data_file_url`	string	No	URL of the data file to import; when empty only creates the table.
`column_load_options`	array	No	Loading options for each column when importing data.

Successful response¶

Returns 200 and the new table ID on success. Table creation is not possible for system, retention, or subscription databases.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 1001
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	integer	ID of the new table.

Error response¶

{
  "code": "ErrReadonlySystemDatabase",
  "msg": "数据库不可写",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`database_id`, `name` or column definition is missing, or the identifier is invalid.	Try again after providing the complete table definition.
`403`	`ErrForbidden`	The current identity does not have permission to create tables in the target database.	Use credentials with write access, or contact your administrator for authorization.
`409`	`ErrReadonlySystemDatabase`、`ErrReadonlyReservedDatabase`、`ErrReadonlySubscriptionDatabase`	The target database is not writable.	Select a writable database.
`500`	`ErrServer`	The service cannot create tables or import data.	Record the request time and error message and try again; if it continues to fail, contact support.

Follow-up operations¶

Use data.id Query table information.

Last updated on Sep 3, 2026