读写行

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

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

参数与请求头

名称	位置	说明
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}

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

响应

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

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

[
  {
    "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}

const { data, error, count } = await supabase.from("tasks").select("*", { head: true, count: "exact" });
if (error) throw error;
console.log(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}

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

响应

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

[
  {
    "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}

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

响应

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 204

Success without a body

未声明响应体。

响应示例 — HTTP 200

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

[
  {
    "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}

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

响应

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	resolution=merge-duplicates, return=representation
range-unit	items

[
  {
    "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}

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

响应

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 204

Success without a body

未声明响应体。

响应示例 — HTTP 200

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

[
  {
    "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
  }
]

读写行

本页内容