过滤器

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

过滤器可以用于 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%");

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", ["腾讯云开发", "云开发"]);

match

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

参数

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

代码示例

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

not

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

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

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

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

参数

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

代码示例

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

or

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

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

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

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

.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	必需	要使用的过滤器，遵循 MySQL 语法
options	object	必需	命名参数
options.referencedTable	string	可选	设置为过滤引用表而不是父表

代码示例

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

filter

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

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

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

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

参数

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

代码示例

// 查询 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", "技术");