过滤器

过滤器允许只返回符合特定条件的行。

过滤器可以用于 select()、update()、upsert() 和 delete() 查询。

eq

仅匹配列值等于指定值的行。

要检查列值是否为 NULL，应该使用 .is() 而不是 eq。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	any	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 title 等于 "腾讯云开发" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .eq("title", "腾讯云开发");

neq

仅匹配列值不等于指定值的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	any	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 title 不等于 "腾讯云开发" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .neq("title", "腾讯云开发");

gt

仅匹配列值大于指定值的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	any	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 id 大于 2 的记录
const { data, error } = await db.from("articles").select().gt("id", 2);

gte

仅匹配列值大于或等于指定值的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	any	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 id 大于或等于 2 的记录
const { data, error } = await db.from("articles").select().gte("id", 2);

lt

仅匹配列值小于指定值的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	any	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 id 小于 2 的记录
const { data, error } = await db.from("articles").select().lt("id", 2);

lte

仅匹配列值小于或等于指定值的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	any	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 id 小于或等于 2 的记录
const { data, error } = await db.from("articles").select().lte("id", 2);

like

仅匹配列值符合特定模式的行（是否区分大小写受校验规则约束）。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
pattern	string	必需	要匹配的模式

代码示例

// 从 articles 表中查询所有 title 包含 "cloudbase" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .like("title", "%cloudbase%");

ilike

仅匹配列值符合特定模式的行（不区分大小写，不受校验规则约束）。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
pattern	string	必需	要匹配的模式

代码示例

// 从 articles 表中查询所有 title 包含 "cloudbase" 的记录（不区分大小写）
const { data, error } = await db
  .from("articles")
  .select()
  .ilike("title", "%cloudbase%");

is

仅匹配列值等于指定值的行。

对于非布尔列，主要用于检查列值是否为 NULL；

对于布尔列，也可以设置为 true 或 false，行为与 .eq() 相同。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	Object	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 title 为 null 的记录
const { data, error } = await db.from("articles").select().is("title", null);

in

仅匹配列值包含在指定数组中的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
values	Array	必需	用于过滤的值数组

代码示例

// 从 articles 表中查询所有 title 在指定数组 ["腾讯云开发", "云开发"] 中的记录
const { data, error } = await db
  .from("articles")
  .select()
  .in("title", ["腾讯云开发", "云开发"]);

contains

仅匹配列值包含指定值的行。

适用于数组列、范围列和 JSONB 列。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	Array|Object	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 tags 包含 ["技术", "云计算"] 的记录（数组列）
const { data, error } = await db
  .from("articles")
  .select()
  .contains("tags", ["技术", "云计算"]);

// 从 articles 表中查询所有 metadata 包含指定 JSON 对象的记录（JSONB 列）
const { data, error } = await db
  .from("articles")
  .select()
  .contains("metadata", { category: "技术" });

containedBy

仅匹配列值被指定值包含的行。

适用于数组列、范围列和 JSONB 列。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	Array|Object	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 tags 被 ["技术", "云计算", "前端", "后端"] 包含的记录
const { data, error } = await db
  .from("articles")
  .select()
  .containedBy("tags", ["技术", "云计算", "前端", "后端"]);

overlaps

仅匹配列值与指定值有重叠元素的行。

适用于数组列和范围列。

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
value	Array|string	必需	用于过滤的值

代码示例

// 从 articles 表中查询所有 tags 与 ["技术", "前端"] 有重叠元素的记录
const { data, error } = await db
  .from("articles")
  .select()
  .overlaps("tags", ["技术", "前端"]);

textSearch

仅匹配 tsvector 列值满足指定 tsquery 全文搜索条件的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的文本搜索列
query	string	必需	用于匹配的全文搜索查询
options	object	可选	命名参数
options.config	string	可选	文本搜索配置（如 'english'、'simple'）
options.type	string	可选	搜索类型：'plain'（默认）、'phrase' 或 'websearch'

代码示例

// 从 articles 表中全文搜索 content 列包含 "云开发" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .textSearch("content", "云开发");

// 使用 websearch 语法进行全文搜索
const { data, error } = await db
  .from("articles")
  .select()
  .textSearch("content", "'云开发' OR '云计算'", {
    type: "websearch",
    config: "simple",
  });

rangeGt

仅适用于范围列。仅匹配列中每个元素都大于范围中任何元素的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的范围列
range	string	必需	用于过滤的范围

代码示例

// 从 articles 表中查询所有 created_at 大于范围 "[2023-01-01 00:00, 2023-01-02 00:00)" 中的记录
const { data, error } = await db
  .from("articles")
  .select()
  .rangeGt("created_at", "[2023-01-01 00:00, 2023-01-02 00:00)");

rangeGte

仅适用于范围列。仅匹配列中每个元素都包含在范围内或大于范围中任何元素的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的范围列
range	string	必需	用于过滤的范围

代码示例

// 从 articles 表中查询所有 created_at 大于或等于范围 "[2023-01-01 08:30, 2023-01-01 09:30)" 中的记录
const { data, error } = await db
  .from("articles")
  .select()
  .rangeGte("created_at", "[2023-01-01 08:30, 2023-01-01 09:30)");

rangeLt

仅适用于范围列。仅匹配列中每个元素都小于范围中任何元素的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的范围列
range	string	必需	用于过滤的范围

代码示例

// 从 articles 表中查询所有 created_at 小于范围 "[2023-01-01 12:00, 2023-01-01 13:00)" 中的记录
const { data, error } = await db
  .from("articles")
  .select()
  .rangeLt("created_at", "[2023-01-01 12:00, 2023-01-01 13:00)");

rangeLte

仅适用于范围列。仅匹配列中每个元素都包含在范围内或小于范围中任何元素的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的范围列
range	string	必需	用于过滤的范围

代码示例

// 从 articles 表中查询所有 created_at 小于或等于范围 "[2023-01-01 14:00, 2023-01-01 16:00)" 中的记录
const { data, error } = await db
  .from("articles")
  .select()
  .rangeLte("created_at", "[2023-01-01 14:00, 2023-01-01 16:00)");

rangeAdjacent

仅适用于范围列。仅匹配列范围与指定范围互斥且没有重叠元素的行。

参数

参数	类型	必需	说明
column	string	必需	要过滤的范围列
range	string	必需	用于过滤的范围

代码示例

// 从 articles 表中查询所有 created_at 与范围 "[2023-01-01 12:00, 2023-01-01 13:00)" 互斥且没有重叠元素的记录
const { data, error } = await db
  .from("articles")
  .select()
  .rangeAdjacent("created_at", "[2023-01-01 12:00, 2023-01-01 13:00)");

match

仅匹配查询键中每个列都等于其关联值的行，相当于多个 .eq() 的简写形式。

参数

参数	类型	必需	说明
query	Record<ColumnName, Row['ColumnName']>	必需	过滤对象，列名作为键映射到它们的过滤值

代码示例

// 从 articles 表中查询所有 id 等于 2 且 title 等于 "腾讯云开发" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .match({ id: 2, title: "腾讯云开发" });

not

仅匹配不满足过滤条件的行。

与大多数过滤器不同，操作符和值按原样使用，需要遵循 PostgreSQL 语法，还需要确保它们已正确转义。

not() 期望使用原始的 PostgreSQL 语法作为过滤器值。

.not('id', 'in', '(5,6,7)')  // 对 `in` 过滤器使用 `()`
.not('name', 'like', '%test%')  // 使用 `not like` 进行模糊匹配

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
operator	string	必需	要取反的过滤操作符，遵循 PostgreSQL 语法
value	any	必需	过滤值，遵循 PostgreSQL 语法

代码示例

// 从 articles 表中查询所有 title 不为 null 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .not("title", "is", null);

or

仅匹配满足至少一个过滤条件的行。

与大多数过滤器不同，过滤器按原样使用，需要遵循 PostgreSQL 语法，还需要确保它们已正确转义。

目前无法跨多个表进行 .or() 过滤。

or() 期望使用原始的 PostgreSQL 语法作为过滤器名称和值。

.or('id.in.(5,6,7), name.like.%test%')  // 对 `in` 过滤器使用 `()`，对模糊匹配使用 `like` 和 `%`
.or('id.in.(5,6,7), name.not.like.%test%')  // 使用 `not.like` 进行反向模糊匹配

参数

参数	类型	必需	说明
filters	string	必需	要使用的过滤器，遵循 PostgreSQL 语法
options	object	必需	命名参数
options.referencedTable	string	可选	设置为过滤引用表而不是父表

代码示例

// 从 articles 表中查询所有 id 等于 2 或者 title 等于 "腾讯云开发" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .or(`id.eq.2,title.eq.腾讯云开发`);

filter

仅匹配满足过滤条件的行，这是一个逃生舱口，应该尽可能使用特定的过滤器方法。

与大多数过滤器不同，操作符和值按原样使用，需要遵循 PostgreSQL 语法，还需要确保它们已正确转义。

filter() 期望使用原始的 PostgreSQL 语法作为过滤器值。

.filter('id', 'in', '(5,6,7)')  // 对 `in` 过滤器使用 `()`
.filter('name', 'like', '%test%')  // 使用 `like` 进行模糊匹配
.filter('name', 'not.like', '%test%')  // 使用 `not.like` 进行反向模糊匹配

参数

参数	类型	必需	说明
column	string	必需	要过滤的列
operator	string	必需	过滤操作符，遵循 PostgreSQL 语法
value	any	必需	过滤值，遵循 PostgreSQL 语法

代码示例

// 查询 title 在指定值列表中的记录
// 从 articles 表中查询所有 title 在指定值列表 ["腾讯云开发", "云开发"] 中的记录
const { data, error } = await db
  .from("articles")
  .select()
  .filter("title", "in", "(腾讯云开发,云开发)");

// 在引用表上过滤
// 从 articles 表中查询所有关联的 categories.name 等于 "技术" 的记录
const { data, error } = await db
  .from("articles")
  .select()
  .filter("categories.name", "eq", "技术");