# 数据表 (/docs/api/native/database/tables)



[指南 →](/docs/cloud/services/database/quickstart)

[基础地址与鉴权](/docs/api/native/database)

## 创建表 [#创建表]

`POST /database/v1/databases/{database_id}/tables`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

### 请求体 [#请求体]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 名称; ^[a-z_][a-z0-9_]{0,62}$ |
| description | string | 否 | 描述 |
| fields | NewField[] | 是 | 字段列表 |

返回: `Table`.

### 响应 [#响应]

#### HTTP 201 [#http-201]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| description | string | null | Free-text note about the table, or null when none was set. |
| fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| fields[].id | string | Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name. |
| fields[].name | string | Current field name; rows are keyed by it in requests and responses. May change when the field is renamed. |
| fields[].description | string | null | Free-text note about the field, or null when none was set. |
| fields[].required | boolean | Whether every row must hold a non-null value for this field. |
| fields[].unique | boolean | Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION. |
| fields[].indexed | boolean | Whether an index is maintained for faster filters and ordering. Always false for json and link fields. |
| fields[].type | string | Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created. |
| fields[].options | object | Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required. |
| fields[].default | any | Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults. |
| schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"tasks","fields":[{"name":"title","type":"string","required":true,"unique":true},{"name":"done","type":"boolean"}]}'
```

响应示例 — HTTP 201

```json
{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": null,
  "schema_revision": 1,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:44.246Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}
```

## 列出表 [#列出表]

`GET /database/v1/databases/{database_id}/tables`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

返回: `Page + object`.

### 响应 [#响应-1]

#### HTTP 200 [#http-200]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | Every table of the database with its fields, in creation order; at most 50 items. |
| data[].id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| data[].name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| data[].description | string | null | Free-text note about the table, or null when none was set. |
| data[].fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| data[].schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| data[].created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| data[].updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| data[].row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |
| next_cursor | string | null | Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc). |

```bash
curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "data": [
    {
      "id": "tbl_2b3431c772754599",
      "name": "tasks",
      "description": null,
      "schema_revision": 1,
      "created_at": "2026-10-11T17:41:44.246Z",
      "updated_at": "2026-10-11T17:41:44.246Z",
      "fields": [
        {
          "id": "fld_bc71f7c6a1a848d2",
          "name": "title",
          "type": "string",
          "description": null,
          "required": true,
          "unique": true,
          "indexed": true
        },
        {
          "id": "fld_c7879883dfe04ca0",
          "name": "done",
          "type": "boolean",
          "description": null,
          "required": false,
          "unique": false,
          "indexed": true
        }
      ]
    }
  ],
  "next_cursor": null
}
```

## 读取表 [#读取表]

`GET /database/v1/databases/{database_id}/tables/{table}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |

返回: `Table`.

### 响应 [#响应-2]

#### HTTP 200 [#http-200-1]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| description | string | null | Free-text note about the table, or null when none was set. |
| fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| fields[].id | string | Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name. |
| fields[].name | string | Current field name; rows are keyed by it in requests and responses. May change when the field is renamed. |
| fields[].description | string | null | Free-text note about the field, or null when none was set. |
| fields[].required | boolean | Whether every row must hold a non-null value for this field. |
| fields[].unique | boolean | Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION. |
| fields[].indexed | boolean | Whether an index is maintained for faster filters and ordering. Always false for json and link fields. |
| fields[].type | string | Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created. |
| fields[].options | object | Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required. |
| fields[].default | any | Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults. |
| schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |

```bash
curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": null,
  "schema_revision": 1,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:44.246Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ],
  "row_count": 0
}
```

## 更新表 [#更新表]

`PATCH /database/v1/databases/{database_id}/tables/{table}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |

### 请求体 [#请求体-1]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 否 | 名称 |
| description | string / null | 否 | 描述 |

返回: `Table`.

### 响应 [#响应-3]

#### HTTP 200 [#http-200-2]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Table identifier, prefixed tbl_. Stable across renames and accepted wherever a table path parameter takes an id or name. |
| name | string | Current table name, usable in the rows path; may change when the table is renamed. |
| description | string | null | Free-text note about the table, or null when none was set. |
| fields | array<object> | Field definitions of the table, in display order. Row values are keyed by each field's name. |
| fields[].id | string | Field identifier, prefixed fld_. Stable across renames; accepted wherever a field path parameter takes an id or name. |
| fields[].name | string | Current field name; rows are keyed by it in requests and responses. May change when the field is renamed. |
| fields[].description | string | null | Free-text note about the field, or null when none was set. |
| fields[].required | boolean | Whether every row must hold a non-null value for this field. |
| fields[].unique | boolean | Whether values must be distinct across rows; fixed at creation. A unique field is indexed, and a violation returns 409 UNIQUE_VIOLATION. |
| fields[].indexed | boolean | Whether an index is maintained for faster filters and ordering. Always false for json and link fields. |
| fields[].type | string | Scalar data type of the field; it cannot be changed after the field is created. / Type json: the value is any JSON document validated against options.schema. It cannot be changed after the field is created. / Type link: the value is the id of a row in another table (an array of ids when options.multiple is true). It cannot be changed after the field is created. |
| fields[].options | object | Scalar fields take no options; always an empty object. / Settings of a json field. schema is required. / Settings of a link field. Both linked_table_id and multiple are required. |
| fields[].default | any | Default JSON value for omitted insert fields; must match the field type and JSON schema. A datetime default of "now()" evaluates to server time on insertion and reads back as "now()" in the field definition. For string and json fields it is a literal string. Explicit null remains null. Link fields do not support defaults. |
| schema_revision | integer | Counter that starts at 1 and increases by one each time the table's name, description or fields change; use it to detect schema changes. |
| created_at | string | Time the table was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last schema change to the table, as an RFC 3339 UTC timestamp. |
| row_count | integer | Number of rows currently stored. Returned only by databaseGetTable; absent from list, create and field responses. |

```bash
curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Tasks for an agent"}'
```

响应示例 — HTTP 200

```json
{
  "id": "tbl_2b3431c772754599",
  "name": "tasks",
  "description": "Tasks for an agent",
  "schema_revision": 2,
  "created_at": "2026-10-11T17:41:44.246Z",
  "updated_at": "2026-10-11T17:41:45.127Z",
  "fields": [
    {
      "id": "fld_bc71f7c6a1a848d2",
      "name": "title",
      "type": "string",
      "description": null,
      "required": true,
      "unique": true,
      "indexed": true
    },
    {
      "id": "fld_c7879883dfe04ca0",
      "name": "done",
      "type": "boolean",
      "description": null,
      "required": false,
      "unique": false,
      "indexed": true
    }
  ]
}
```

## 删除表 [#删除表]

`DELETE /database/v1/databases/{database_id}/tables/{table}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |

返回: `object`.

### 响应 [#响应-4]

#### HTTP 200 [#http-200-3]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| deleted | boolean | Always true: the table and all of its rows were dropped immediately and cannot be recovered. |

```bash
curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/tables/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "deleted": true
}
```

## Table [#table]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 资源 ID; ^tbl_ |
| name | string | 是 | 名称 |
| description | string / null | 是 | 描述 |
| fields | Field[] | 是 | 字段列表 |
| schema_revision | integer | 是 | 表结构版本 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| row_count | integer | 否 | 行数；仅单表查询返回 |

[Field](/docs/api/native/database/fields#field) · [Page](/docs/api/native/database/databases#page)