数据库与表¶

使用数据目录（Catalog）API 创建数据库和表，并从响应中取得后续文件、SQL 和语义模型任务需要的资源 ID。本页先完成一条最短路径：列出数据目录、创建数据库，再在数据库中创建一张表。

前提条件¶

已按开始使用 Product API准备 Product API Base URL、个人访问令牌和工作区 ID。
当前身份具有读取数据目录以及创建数据库和表的权限。
已确认目标工作区，避免在错误的工作区创建同名资源。

export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'
export WORKSPACE_ID='<workspace-id>'

列出数据目录¶

数据目录列表接口使用 POST，但不需要请求体：

curl -X POST "$PRODUCT_API_BASE_URL/catalog/list" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json"

成功响应中的 data.list[] 是当前身份可见的数据目录。保存目标项的 id：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "list": [
      {
        "id": 101,
        "name": "<CATALOG_NAME>",
        "description": "",
        "database_count": 0,
        "allowed_actions": []
      }
    ]
  }
}

如果还没有可用数据目录，可以调用 POST /catalog/create 创建：

curl -X POST "$PRODUCT_API_BASE_URL/catalog/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<CATALOG_NAME>",
    "description": "<DESCRIPTION>"
  }'

创建成功后保存 data.id，并在后续命令中设置 CATALOG_ID。

创建数据库¶

export CATALOG_ID='<catalog-id>'

curl -X POST "$PRODUCT_API_BASE_URL/catalog/database/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"catalog_id\": $CATALOG_ID,
    \"name\": \"<DATABASE_NAME>\",
    \"description\": \"<DESCRIPTION>\"
  }"

字段	类型	必需	说明
`catalog_id`	integer	是	父数据目录的数值 ID。
`name`	string	是	数据库名称。创建后不能通过当前 Product API 重命名。
`description`	string	否	数据库说明；后续可以通过更新接口修改。

成功响应返回数据库 ID：

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

保存 data.id。读取数据库信息使用 POST /catalog/database/info，请求体为 {"id": 201}；列出直接子对象使用 POST /catalog/database/children。

创建表¶

下面的示例创建一张包含主键和文本列的表：

export DATABASE_ID='<database-id>'

curl -X POST "$PRODUCT_API_BASE_URL/catalog/table/create" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"database_id\": $DATABASE_ID,
    \"name\": \"orders\",
    \"columns\": [
      {
        \"name\": \"id\",
        \"type\": \"INT\",
        \"is_pk\": true
      },
      {
        \"name\": \"description\",
        \"type\": \"VARCHAR\",
        \"precision\": [255]
      }
    ]
  }"

字段	类型	必需	说明
`database_id`	integer	是	目标数据库 ID。
`name`	string	是	表名称。创建前可使用 `/catalog/table/exist` 检查同名表。
`columns`	array	是	列定义；至少包含一列。
`columns[].name`	string	是	列名称。
`columns[].type`	string	是	MatrixOne 数据类型。
`columns[].is_pk`	boolean	否	当前列是否为主键。
`columns[].precision`	integer[]	按类型	字符串长度或数值精度等类型参数。
`columns[].default`	string	否	默认值表达式；只使用 MatrixOne 接受的值。
`columns[].comment`	string	否	列说明。

成功响应的 data.id 是表 ID。后续可以通过 /catalog/table/info 读取列与统计信息，通过 /catalog/table/data 或 /catalog/table/preview 读取受限结果。

删除前检查¶

删除表、数据库或数据目录会影响其下游引用。提交删除前，先列出数据库子对象，并检查工作流、语义模型、数据分享和导入导出任务中的使用关系。删除接口成功不提供恢复能力。

常见问题¶

现象	先检查	下一步
数据目录或数据库为空	`X-Workspace-ID` 和当前身份可见范围	在同一工作区重新列出资源，不要复制其他工作区的 ID。
创建表失败	`database_id`、列类型、列名和 `precision`	缩减为最小列定义后重试，再逐项增加可选字段。
同名对象冲突	当前数据目录或数据库中的列表结果	使用已有对象 ID，或改用新的唯一名称。
删除被拒绝	子对象和下游引用	先解除引用或删除子对象，再重新提交。

下一步¶

最后更新于 2026 年 8 月 14 日