# 读写行 (/docs/api/compatible/supabase/tables)



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

`/supabase/{database_id}/rest/v1/{table}`

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

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

## 参数与请求头 [#参数与请求头]

| 名称 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |
| table | path | 表 ID 或名称。 |
| select | query | 列名列表；支持 *、别名、JSON 路径及 link 关联展开。不支持类型转换、聚合、展开运算和连接修饰。 |
| {column} | query | 把 {column} 换为字段名或 JSON 路径，例如 title=eq.summary；不同列的条件同时生效。 |
| and | query | 括号内的条件全部成立，例如 (done.eq.false,title.neq.draft)。 |
| or | query | 括号内任一条件成立。 |
| not.and | query | 否定全部条件成立。 |
| not.or | query | 否定任一条件成立。 |
| order | query | 逗号分隔的字段，可带 asc/desc、nullsfirst/nullslast；支持 JSON 路径。 |
| limit | query | 最多返回的条数。 |
| offset | query | 跳过的行数。 |
| on_conflict | query | upsert 的冲突键：id 或单个 unique 字段；配合 Prefer 的 resolution。 |
| columns | query | 写入列的逗号分隔列表；列表之外的输入键被忽略。 |
| Range | header | GET/HEAD 的闭区间，例如 0-9；与 limit/offset 取交集。 |
| Range-Unit | header | items；其它单位使 Range 被忽略。 |
| Prefer | header | 逗号分隔的偏好。未知值默认被忽略；handling=strict 时返回 400 PGRST122。 |
| Accept | header | application/json、*/* 或 application/vnd.pgrst.object+json；单对象模式必须恰好匹配一行，否则返回 406 PGRST116。其他媒体类型返回 406 PGRST107；text/csv、application/geo+json 与 application/vnd.pgrst.plan 返回 400 PGRST127。 |
| If-None-Match | header | 上次 GET/HEAD 返回的 ETag（弱比较）；与当前 ETag 匹配时返回 304，无正文。 |

POST 接受单个对象或对象数组；PATCH 接受对象。系统列由服务管理。写入默认不返回正文，使用 Prefer: return=representation（SDK 的 .select()）返回行。PATCH 和 DELETE 只影响匹配过滤器的行；省略过滤器会影响全部匹配行。

| 响应头 | 说明 |
| --- | --- |
| Content-Range | 本次行范围/总数；未请求计数时总数为 *。 |
| Preference-Applied | 已应用的偏好。 |
| ETag | GET/HEAD 返回的版本标记；请求带 If-None-Match 且与之匹配时返回 304、无正文。 |
| Location | POST 使用 return=headers-only 时的新行地址。 |

读取通常为 200；请求计数且只返回部分行时为 206。POST 为 201。PATCH/DELETE 使用 representation 时为 200，否则为 204。HEAD 没有正文。If-None-Match 与当前 ETag 匹配时返回 304。datetime 值统一按 UTC、3 位毫秒保存和读出（如 2026-10-11T00:30:00.000Z），精度为毫秒，超过 3 位的小数秒四舍五入。

## 查询行 [#查询行]

`GET /supabase/{database_id}/rest/v1/{table}`

```typescript
const { data, error } = await supabase.from("tasks").select("*").order("title").limit(10);
if (error) throw error;
console.log(data);
```

### 响应 [#响应]

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string |  |
| [].version | integer |  |
| [].created_at | string |  |
| [].updated_at | string |  |

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

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string |  |
| version | integer |  |
| created_at | string |  |
| updated_at | string |  |

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

Partial range with requested count

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string |  |
| [].version | integer |  |
| [].created_at | string |  |
| [].updated_at | string |  |

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

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string |  |
| version | integer |  |
| created_at | string |  |
| updated_at | string |  |

响应示例 — HTTP 200

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

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

## 统计行 [#统计行]

`HEAD /supabase/{database_id}/rest/v1/{table}`

```typescript
const { data, error, count } = await supabase.from("tasks").select("*", { head: true, count: "exact" });
if (error) throw error;
console.log(count);
```

### 响应 [#响应-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 /supabase/{database_id}/rest/v1/{table}`

```typescript
const { data, error } = await supabase.from("tasks").insert({"title":"Write a summary","done":false}).select();
if (error) throw error;
console.log(data);
```

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

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string |  |
| [].version | integer |  |
| [].created_at | string |  |
| [].updated_at | string |  |

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

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string |  |
| version | integer |  |
| created_at | string |  |
| updated_at | string |  |

响应示例 — HTTP 201

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

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

## 更新行 [#更新行]

`PATCH /supabase/{database_id}/rest/v1/{table}`

```typescript
const { data, error } = await supabase.from("tasks").update({ done: true }).eq("title", "Write a summary").select();
if (error) throw error;
console.log(data);
```

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

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string |  |
| [].version | integer |  |
| [].created_at | string |  |
| [].updated_at | string |  |

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

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string |  |
| version | integer |  |
| created_at | string |  |
| updated_at | string |  |

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

Success without a body

未声明响应体。

响应示例 — HTTP 200

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

```json
[
  {
    "id": "rec_e88fcbd357aa49c9",
    "version": 2,
    "created_at": "2026-10-11T17:42:00.094Z",
    "updated_at": "2026-10-11T17:42:01.047Z",
    "title": "Write a summary",
    "done": true
  }
]
```

## 合并行 [#合并行]

`POST /supabase/{database_id}/rest/v1/{table}`

```typescript
const { data, error } = await supabase.from("tasks").upsert({"title":"Write a summary","done":true}, { onConflict: "title" }).select();
if (error) throw error;
console.log(data);
```

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

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string |  |
| [].version | integer |  |
| [].created_at | string |  |
| [].updated_at | string |  |

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

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string |  |
| version | integer |  |
| created_at | string |  |
| updated_at | string |  |

响应示例 — HTTP 201

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

```json
[
  {
    "id": "rec_e88fcbd357aa49c9",
    "version": 3,
    "created_at": "2026-10-11T17:42:00.094Z",
    "updated_at": "2026-10-11T17:42:01.735Z",
    "title": "Write a summary",
    "done": true
  }
]
```

## 删除行 [#删除行]

`DELETE /supabase/{database_id}/rest/v1/{table}`

```typescript
const { data, error } = await supabase.from("tasks").delete().eq("title", "Write a summary").select();
if (error) throw error;
console.log(data);
```

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

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

Success; write bodies require Prefer: return=representation

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| [].id | string |  |
| [].version | integer |  |
| [].created_at | string |  |
| [].updated_at | string |  |

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

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string |  |
| version | integer |  |
| created_at | string |  |
| updated_at | string |  |

#### 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_e88fcbd357aa49c9",
    "version": 3,
    "created_at": "2026-10-11T17:42:00.094Z",
    "updated_at": "2026-10-11T17:42:01.735Z",
    "title": "Write a summary",
    "done": true
  }
]
```