# 查询数据库中的表

查看一个数据库中的表和视图。使用返回的对象名称查看字段、表信息或建表语句。

```text
POST https://moi.matrixorigin.cn/newmoi/meta/db/table
```

## 调用前准备

准备个人访问令牌、工作区 ID 和数据库名称。可先[查询数据库](list-databases.md)确认名称。

下方示例使用 `$AI_STUDIO_API_KEY`、`$WORKSPACE_ID` 和 `$DATABASE`。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 要查询的数据库名称。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/meta/db/table" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"name\":\"$DATABASE\"}"
```

## 成功响应

```json
{
  "code": 200,
  "data": {
    "db_name": "sales",
    "tables": {"tables": [{"name": "orders", "owner": "", "created": "", "rows": 0, "size": 0}], "total": 1},
    "views": {"tables": [], "total": 0}
  }
}
```

响应字段如下。

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`items[].name` 表示 `items` 数组中每一项的 `name` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 `200`。 |
| `data.db_name` | string | 被查询的数据库名称。 |
| `data.tables.tables` | array | 表列表。 |
| `data.views.tables` | array | 视图列表。 |
| `data.tables.total` | integer | 表列表中的对象数量。 |
| `data.views.total` | integer | 视图列表中的对象数量。 |
| `data.tables.tables[].name` | string | 表名称；用于查询表信息、字段或建表语句。 |
| `data.views.tables[].name` | string | 视图名称；用于查看建表语句或删除视图。 |
| `data.tables.tables[].owner` | string | 表对象所有者。 |
| `data.views.tables[].owner` | string | 视图对象所有者。 |
| `data.tables.tables[].created` | string | 表对象创建时间。 |
| `data.views.tables[].created` | string | 视图对象创建时间。 |
| `data.tables.tables[].rows` | integer | 表对象行数。 |
| `data.views.tables[].rows` | integer | 视图对象行数。 |
| `data.tables.tables[].size` | integer | 表对象大小。 |
| `data.views.tables[].size` | integer | 视图对象大小。 |

## 错误响应

```json
{
  "code": 400,
  "message": "name 不能为空"
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 15 45 40

* - HTTP 状态码
  - 常见原因
  - 建议操作
* - `400`
  - 请求体无法解析，或缺少 `name`。
  - 提供非空的数据库名称。
* - `401`
  - 凭据缺失或无效。
  - 检查 API Key 和工作区请求头。
* - `403`
  - 当前访问凭据无权读取该数据库。
  - 使用具有数据库访问权限的凭据重试。
* - `500`
  - 查询表或视图时发生服务端错误。
  - 检查对象名称和服务端错误信息后重试。
* - `503`
  - 数据库连接暂时不可用。
  - 稍后重试。
```

## 后续操作

保存目标项的标识，再[查询表信息](get-table-info.md)。