# 读写行 (/docs/api/native/database/rest)



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

`/database/v1/databases/{database_id}/rest/{table}`

与同一库的其它入口读写相同的行；错误使用 PostgREST code。

[支持矩阵与初始化](/docs/api/compatible/supabase)

[完整参数、响应头与返回状态](/docs/api/compatible/supabase/tables)

一次批量 POST 最多插入 **500 行**，单次请求是原子的：任何一行失败，整批回滚。跨请求没有事务；需要一起成功的行应放在一次批量 POST 中。有关联依赖时先查后插，并处理并发变化导致的关联错误。

同一批次按所有行的键的并集补齐缺失值为 `null`（PostgREST 行为）。发送 `Prefer: missing=default` 可改用字段默认值；显式 `null` 仍为 null，没有默认值的必填字段仍必须提供。默认 `return=minimal` 返回 201、body 为空；发送 `Prefer: return=representation` 才返回行。

## 查询行 [#查询行]

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

```bash
curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?select=*&order=title.asc&limit=10" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

### 响应 [#响应]

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

**application/vnd.pgrst.object+json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

#### HTTP 206 [#http-206]

Partial range with requested count

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

**application/vnd.pgrst.object+json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

响应示例 — HTTP 200

| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| etag | W/"5.1" |
| range-unit | items |

```json
[
  {
    "id": "rec_3e85a292099340e3",
    "version": 1,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:47.896Z",
    "title": "Write a summary",
    "done": false
  }
]
```

## 统计行 [#统计行]

`HEAD /database/v1/databases/{database_id}/rest/{table}`

```bash
curl --head "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?select=*" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: count=exact'
```

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

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

Success; write bodies require Prefer: return=representation

未声明响应体。

#### HTTP 206 [#http-206-1]

Partial range with requested count

未声明响应体。

响应示例 — HTTP 200

| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/1 |
| preference-applied | count=exact |
| etag | W/"5.1" |
| range-unit | items |

无响应正文。

## 插入行 [#插入行]

`POST /database/v1/databases/{database_id}/rest/{table}`

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: return=representation' \
  -H "Content-Type: application/json" \
  -d '{"title":"Write a summary","done":false}'
```

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

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

Success (201). With the default return=minimal the body is empty; Prefer: return=representation returns rows.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

**application/vnd.pgrst.object+json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

响应示例 — HTTP 201

| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | return=representation |
| range-unit | items |

```json
[
  {
    "id": "rec_3e85a292099340e3",
    "version": 1,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:47.896Z",
    "title": "Write a summary",
    "done": false
  }
]
```

## 更新行 [#更新行]

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

```bash
curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?title=eq.Write%20a%20summary" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: return=representation' \
  -H "Content-Type: application/json" \
  -d '{"done":true}'
```

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

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

**application/vnd.pgrst.object+json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

#### HTTP 204 [#http-204]

Success without a body

未声明响应体。

响应示例 — HTTP 200

| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | return=representation |
| range-unit | items |

```json
[
  {
    "id": "rec_3e85a292099340e3",
    "version": 2,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:48.802Z",
    "title": "Write a summary",
    "done": true
  }
]
```

## 合并行 [#合并行]

`POST /database/v1/databases/{database_id}/rest/{table}`

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?on_conflict=title" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: resolution=merge-duplicates,return=representation' \
  -H "Content-Type: application/json" \
  -d '{"title":"Write a summary","done":true}'
```

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

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

Success (201). With the default return=minimal the body is empty; Prefer: return=representation returns rows.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

**application/vnd.pgrst.object+json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

响应示例 — HTTP 201

| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | resolution=merge-duplicates, return=representation |
| range-unit | items |

```json
[
  {
    "id": "rec_3e85a292099340e3",
    "version": 3,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:49.076Z",
    "title": "Write a summary",
    "done": true
  }
]
```

## 删除行 [#删除行]

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

```bash
curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/rest/tasks?title=eq.Write%20a%20summary" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'prefer: return=representation'
```

### 响应 [#响应-5]

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

**application/vnd.pgrst.object+json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Row identifier of 1–64 characters from A-Z a-z 0-9 _ -. Generated by the service unless the insert supplied one; it cannot be changed by updates. |

#### HTTP 204 [#http-204-1]

Success without a body

未声明响应体。

响应示例 — HTTP 200

| 响应头 | 值 |
| --- | --- |
| content-range | 0-0/* |
| preference-applied | return=representation |
| range-unit | items |

```json
[
  {
    "id": "rec_3e85a292099340e3",
    "version": 3,
    "created_at": "2026-10-11T17:41:47.896Z",
    "updated_at": "2026-10-11T17:41:49.076Z",
    "title": "Write a summary",
    "done": true
  }
]
```

## Row [#row]

默认投影、select=*、return=representation 与 RPC 行对象只返回 id 和用户字段。系统元数据须显式点名，例如 select=*,\_version,\_created\_at,\_updated\_at；\* 不展开它们。可用 \_version=eq.3 过滤、order=\_created\_at.desc 排序，但不可写。未指定 order 时仍按内部创建时间、id 排序。没有同名用户字段时，旧名 created\_at/updated\_at/version 用于过滤或排序返回 400，details 为 use \_created\_at（或对应名字），hint 为 system metadata moved to underscore columns。已有下划线用户字段优先，同名系统元数据在该表上不可访问。上方历史响应样例采集于此规则调整前，仍可能包含旧元数据列；当前行形状以本节为准。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 资源 ID; ^[A-Za-z0-9_-]{1,64}$ |