# 数据库与表

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

## 前提条件

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

```bash
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`，但不需要请求体：

```bash
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`：

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

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

```bash
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`。

## 创建数据库

```bash
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：

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

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

## 创建表

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

```bash
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，或改用新的唯一名称。 |
| 删除被拒绝 | 子对象和下游引用 | 先解除引用或删除子对象，再重新提交。 |

## 下一步

- [创建卷并上传文件](volumes-folders-files.md)
- [使用 SQL 查询表](../sql/execute-results.md)
- [把表加入语义模型](../semantic-models/sources-processing.md)