跳到主要内容

修饰符

修饰符用于改变响应的格式，与过滤器不同，它们作用于行级别以上的操作。

过滤器仅返回匹配特定条件的行而不改变行的形状，而修饰符允许改变响应的格式。

select​

默认情况下，.insert() 不会返回插入的行。通过调用此方法，插入的行将在数据中返回。

⚠️ 注意：仅当表中只有一个主键，且该主键为自增类型时，.select() 方法才会返回插入的行。

参数​

参数名类型必填描述
columnsstring否要检索的列，用逗号分隔

代码示例​

// 在 articles 表中执行 upsert 操作，并返回修改后的完整记录
const { data, error } = await db
  .from("articles")
  .insert({ id: 1, title: "腾讯云开发新功能" })
  .select();

order​

对查询结果进行排序。

可以多次调用此方法来按多个列排序。

可以对引用的表进行排序，但仅当在查询中使用 !inner 时，它才会影响父表的排序。

参数​

参数名类型必填描述
columnstring是要排序的列
optionsobject否命名参数

options 参数详情​

参数名类型必填描述
ascendingboolean否如果为 true，结果将按升序排列
nullsFirstboolean否如果为 true，null 值将首先出现。如果为 false，null 值将最后出现
referencedTablestring否设置为按引用表的列排序

代码示例​

// 按发布时间降序排列文章
const { data, error } = await db
  .from("articles")
  .select("id, title, published_at")
  .order("published_at", { ascending: false });

对引用表排序​

// 对引用表 categories 按 name 降序排列
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    categories (
      name
    )
  `)
  .order("name", { referencedTable: "categories", ascending: false });
// 按引用表 category 的 name 列升序排列
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    category:categories (
      name
    )
  `)
  .order("category(name)", { ascending: true });

limit​

限制返回的行数。

参数​

参数名类型必填描述
countnumber是要返回的最大行数
optionsobject否命名参数

options 参数详情​

参数名类型必填描述
referencedTablestring否设置为限制引用表的行数，而不是父表的行数

代码示例​

// 限制返回 5 篇文章
const { data, error } = await db.from("articles").select("title").limit(5);

限制引用表的行数​

// 每篇文章只返回 3 个分类
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    categories (
      name
    )
  `)
  .limit(3, { referencedTable: "categories" });

range​

限制查询结果的范围。

通过从偏移量 from 开始到 to 结束来限制查询结果，只有在此范围内的记录会被返回。

这遵循查询顺序，如果没有排序子句，范围行为可能会不可预期。

from 和 to 值是基于 0 的且包含边界：range(1, 3) 将包括查询的第二、第三和第四行。

参数​

参数名类型必填描述
fromnumber是限制结果的起始索引
tonumber是限制结果的结束索引
optionsobject是命名参数

options 参数详情​

参数名类型必填描述
referencedTablestring否设置为限制引用表的行数，而不是父表的行数

代码示例​

// 获取文章列表的第 1-2 条记录（包含边界）
const { data, error } = await db.from("articles").select("title").range(0, 1);

对引用表使用范围限制​

// 每篇文章只返回前 2 个分类（索引 0-1）
const { data, error } = await db
  .from("articles")
  .select(`
    title,
    categories (
      name
    )
  `)
  .range(0, 1, { referencedTable: "categories" });

abortSignal​

💡 注意：此方法仅在 Web 环境下可用。

为 fetch 请求设置 AbortSignal。

可以使用此功能为请求设置超时。

参数​

参数名类型必填描述
signalAbortSignal是用于 fetch 请求的 AbortSignal

代码示例​

// 使用 AbortController 手动中止请求
const ac = new AbortController();
ac.abort();
const { data, error } = await db
  .from("articles")
  .select()
  .abortSignal(ac.signal);
// 使用 AbortSignal.timeout 设置 1 秒超时
const { data, error } = await db
  .from("articles")
  .select()
  .abortSignal(AbortSignal.timeout(1000));

single​

检索单行数据。

将数据作为单个对象返回，而不是对象数组。

查询结果必须只有一行（例如使用 .limit(1) ），否则此方法会返回错误。

代码示例​

// 获取第一篇文章的标题
const { data, error } = await db
  .from("articles")
  .select("title")
  .limit(1)
  .single();

maybeSingle​

检索零行或一行数据。

将数据作为单个对象返回，而不是对象数组。

查询结果必须为零行或一行（例如使用 .limit(1) ），否则此方法会返回错误。

代码示例​

// 根据标题查找文章，可能不存在
const { data, error } = await db
  .from("articles")
  .select()
  .eq("title", "腾讯云开发新功能")
  .maybeSingle();

overrideTypes​

部分覆盖或替换成功响应的类型。

覆盖响应中 data 字段的返回类型，对于类型安全的查询结果转换非常有用。

参数​

参数名类型必填描述
typeT是要覆盖的类型
optionsobject否选项对象

options 参数详情​

参数名类型必填描述
mergeboolean否如果为 false，则完全替换类型而不是合并

代码示例​

完全覆盖数组类型​

// 将响应数据完全覆盖为自定义数组类型，merge: false 表示完全替换而非合并
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<MyType>, { merge: false }>();

完全覆盖对象类型​

// 与 maybeSingle 一起使用，将单个对象响应完全覆盖为自定义类型
const { data } = await db
  .from("articles")
  .select()
  .maybeSingle()
  .overrideTypes<MyType, { merge: false }>();

部分覆盖数组类型​

// 部分覆盖数组元素类型，只指定需要改变的字段类型（如 status 字段）
const { data } = await db
  .from("articles")
  .select()
  .overrideTypes<Array<{ status: "A" | "B" }>>();

部分覆盖对象类型​

// 部分覆盖单个对象类型，只指定需要改变的字段类型（如 status 字段）
const { data } = await db
  .from("articles")
  .select()
  .maybeSingle()
  .overrideTypes<{ status: "A" | "B" }>();