Skip to content

查询表达式 (Query)

查询表达式用于表达数据库操作中的约束条件。你可以在 DatabaseSelection 的实例方法中使用。查询表达式的基本形式是一个字典,其中的键是字段名,值是约束条件。例如:

ts
ctx.database.get('foo', {
  bar: 1,
  baz: { $gt: 2 },
})

上述查询表达式的意思是:bar 字段的值等于 1,且 baz 字段的值大于 2

类型定义

FieldExpr

本节中定义的具体操作符构成的对象,例如 { $gt: 2 }

Shorthand

为了简化查询操作符的书写,我们为特定类型的字段引入了一些简写形式:

  • 如果该字段的类型是可比较类型,那么接受一个同类型的值,相当于 $eq 操作符
  • 如果该字段的类型是可索引类型,那么接受一个数组,相当于 $in 操作符
  • 如果该字段的类型是字符串,那么接受一个正则表达式,相当于 $regex 操作符
ts
type Extract<S, T, U> = S extends T ? U : never

type Shorthand<T> =
  | Extract<T, Comparable, T>
  | Extract<T, Indexable, T[]>
  | Extract<T, string, RegExp>

FieldQuery

某个字段的约束条件。可以是一个 FieldExprShorthand

ts
type FieldQuery<T> = FieldExpr<T> | Shorthand<T>

QueryExpr

一个字典,其中的键是字段名,值是该字段约束条件。除此以外,还可以使用逻辑运算符 $or, $and, $not 来组合多个约束条件。

ts
type QueryExpr<T> = LogicalExpr<T> & {
  [K in keyof T]?: null | FieldQuery<T[K]>
}

interface LogicalExpr<T> {
  $or?: QueryExpr<T>[]
  $and?: QueryExpr<T>[]
  $not?: QueryExpr<T>
}

Query

某个表的约束条件。它可以是:

  • 一个 QueryExpr,用于约束表中的字段
  • 一个 Shorthand,用于约束表中的主键 (如果主键唯一)
  • 一个 Callback,可以在其中使用求值表达式
ts
type Query<T> = QueryExpr<T> | Shorthand<Indexable> | Callback<T, boolean>

逻辑运算

逻辑运算可以出现在 QueryExprFieldExpr 中。根据出现的场合,它们的类型和含义也会有所不同。

$or

  • 类型: QueryExpr[] (作为 QueryExpr 时)
  • 类型: FieldExpr[] (作为 FieldExpr 时)

一组约束条件的或运算。

$and

  • 类型: QueryExpr[] (作为 QueryExpr 时)
  • 类型: FieldExpr[] (作为 FieldExpr 时)

一组约束条件的与运算。

$not

  • 类型: QueryExpr (作为 QueryExpr 时)
  • 类型: FieldExpr (作为 FieldExpr 时)

约束条件的否定。

元素运算

$in

  • 类型: T[] (T extends Indexable)

判断字段的值是否在给定的数组中。

$nin

  • 类型: T[] (T extends Indexable)

判断字段的值是否不在给定的数组中。

比较运算

$eq

  • 类型: T (T extends Comparable)

判断字段的值是否等于给定的值。

$ne

  • 类型: T (T extends Comparable)

判断字段的值是否不等于给定的值。

$gt

  • 类型: T (T extends Comparable)

判断字段的值是否大于给定的值。

$gte

  • 类型: T (T extends Comparable)

判断字段的值是否大于或等于给定的值。

$lt

  • 类型: T (T extends Comparable)

判断字段的值是否小于给定的值。

$lte

  • 类型: T (T extends Comparable)

判断字段的值是否小于或等于给定的值。

列表运算

$el

判断列表中是否存在满足给定约束条件的元素。

WARNING

部分数据库可能不支持使用子条件,因此请尽量只使用 $eq 操作符。

$size

  • 类型: number (T extends any[])

判断列表的长度是否等于给定的值。

正则表达式

$regex

  • 类型: RegExp (T extends string)

判断字段的值是否匹配给定的正则表达式。

$regexFor

  • 类型: string (T extends string)

将字段的值作为正则表达式,判断给定的字符串是否匹配。

位运算

$bitsAllSet

  • 类型: number (T extends number)

判断字段的值是否包含给定的全部位。

$bitsAllClear

  • 类型: number (T extends number)

判断字段的值是否不包含给定的全部位。

$bitsAnySet

  • 类型: number (T extends number)

判断字段的值是否包含给定的任意位。

$bitsAnyClear

  • 类型: number (T extends number)

判断字段的值是否不包含给定的任意位。