Create table¶

Creates a table in the specified database.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/table/create

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the database list to obtain the target database ID.

Set the operation-specific values used in the request:

$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¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/catalog/table/create" \
  -H "X-API-Key: $CLOUDSIGMA_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"
      }
    ]
  }'

Parameter reference

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.

Response example

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

Field reference

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¶

Response example

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

Field reference

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 15, 2026