筛选表达式参考

filter 搜索参数需要一个过滤表达式。过滤表达式由属性、值和若干运算符组成。

filter 需要一个包含一个或多个条件的过滤表达式。过滤表达式可以写成字符串、数组或两者的混合形式。

​

数据类型

过滤器接受数值和字符串值。空字段或包含空数组的字段将被忽略。

过滤器不支持 NaN 和无限值（如 inf 和 -inf），因为这些值不被 JSON 支持。如果将无限值和 NaN 值作为字符串解析，则可以过滤它们，除非在处理 _geo 字段时。

​

条件

条件是过滤器的基本构建块。它们以 属性 运算符 值 的格式编写，其中：

• 属性 是要过滤的字段属性
• 运算符 可以是 =, !=, >, >=, <, <=, TO, EXISTS, IN, NOT, AND 或 OR
• 值 是 运算符 要在 属性 中查找的值

​

示例

一个基本条件，请求 genres 属性等于 horror 的电影：

genres = horror

包含空格的字符串值必须用单引号或双引号括起来：

director = 'Jordan Peele'
director = "Tim Burton"

​

过滤运算符

​

相等运算符 (=)

相等运算符 (=) 返回给定属性包含特定值的所有文档：

genres = action

当作用于字符串时，= 是大小写不敏感的。

相等运算符对于 null 和空数组不会返回任何结果。

​

不等运算符 (!=)

不等运算符 (!=) 返回所有未被相等运算符选中的文档。当作用于字符串时，!= 是大小写不敏感的。

以下表达式返回所有不包含 action 类型的电影：

genres != action

​

比较运算符 (>, <, >=, <=)

比较运算符 (>, <, >=, <=) 选择满足比较条件的文档。比较运算符适用于数值和字符串值。

下面的表达式返回用户评分高于 85 的所有文档：

rating.users > 85

字符串比较按字典序解析：符号优先于数字，数字优先于按字母顺序排列的字母。以下表达式返回 2004 年 1 月 1 日之后发布的所有文档：

release_date > 2004-01-01

​

TO 运算符

TO 等同于 >= AND <=。以下表达式返回评分在 80 分及以上但低于 90 分的所有文档：

rating.users 80 TO 89

​

EXISTS 运算符

EXISTS 运算符检查字段是否存在。值为空或 null 的字段仍被视为存在。

以下表达式返回包含 release_date 字段的所有文档：

release_date EXISTS

上述表达式的否定形式有两种等效写法：

release_date NOT EXISTS
NOT release_date EXISTS

​

IS EMPTY 运算符

IS EMPTY 运算符用于选择指定属性存在但值为空的文档。以下表达式仅返回 overview 字段为空的文档：

overview IS EMPTY

IS EMPTY 会匹配以下 JSON 值：

• ""（空字符串）
• []（空数组）
• {}（空对象）

Meilisearch 不会将 null 值视为空值。要匹配 null 字段，请使用 IS NULL 运算符。

使用 NOT 构建 IS EMPTY 的否定形式：

overview IS NOT EMPTY
NOT overview IS EMPTY

​

IS NULL 运算符

IS NULL 运算符用于选择指定属性存在但值为 null 的文档。以下表达式仅返回 overview 字段为 null 的文档：

overview IS NULL

使用 NOT 构建 IS NULL 的否定形式：

overview IS NOT NULL
NOT overview IS NULL

​

IN 运算符

IN 运算符通过接受一个由方括号包裹的逗号分隔值数组来组合相等性判断。它会选择所选字段包含至少一个指定值的所有文档。

以下表达式返回 genres 字段包含 horror 或 comedy（或两者都包含）的所有文档：

genres IN [horror, comedy]
genres = horror OR genres = comedy

上述表达式的否定形式可以写作：

genres NOT IN [horror, comedy]
NOT genres IN [horror, comedy]

​

CONTAINS 包含匹配

CONTAINS 操作符用于筛选包含指定字符串模式的部分匹配结果，类似于 SQL 中的 LIKE 语句。

以下表达式返回所有名称包含 "kef" 的乳制品：

dairy_products.name CONTAINS kef

上述表达式的否定形式可以写作：

dairy_products.name NOT CONTAINS kef
NOT dairy_product.name CONTAINS kef

curl \
  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "containsFilter": true
  }'

​

STARTS WITH 开头匹配

STARTS WITH 操作符用于筛选值以指定字符串模式开头的结果。

以下表达式返回所有名称以 "kef" 开头的乳制品：

dairy_products.name STARTS WITH kef

上述表达式的否定形式可以写作：

dairy_products.name NOT STARTS WITH kef
NOT dairy_product.name STARTS WITH kef

curl \
  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "containsFilter": true
  }'

​

NOT 逻辑非

否定运算符 (NOT) 用于选择不满足条件的文档。其优先级高于 AND 和 OR。

以下表达式将返回所有 genres 字段不包含 horror 的文档，以及 genres 字段缺失的文档：

NOT genres = horror

​

过滤表达式

您可以通过使用 AND 和 OR 组合基本条件来构建过滤表达式。过滤表达式可以写成字符串、数组或两者的混合形式。

​

过滤表达式分组运算符

​

AND

AND 连接两个条件，仅返回同时满足这两个条件的文档。AND 的优先级高于 OR。

以下表达式返回同时匹配两个条件的所有文档：

genres = horror AND director = 'Jordan Peele'

​

OR

OR 连接两个条件，返回满足其中至少一个条件的结果。

以下表达式返回匹配任一条件的文档：

genres = horror OR genres = comedy

​

使用字符串运算符和括号创建过滤表达式

Meilisearch 从左到右读取字符串表达式。您可以使用括号确保表达式被正确解析。

例如，如果您希望结果仅包含 1995 年 3 月之后发布的 comedy 和 horror 类文档，以下查询中的括号是必需的：

(genres = horror OR genres = comedy) AND release_date > 795484800

如果不添加这些括号，相同的查询将被解析为：

genres = horror OR (genres = comedy AND release_date > 795484800)

用自然语言解释，上述表达式将仅返回 1995 年 3 月之后发布的喜剧片，或所有恐怖片（无论其 release_date 如何）。

​

使用数组创建筛选表达式

数组表达式通过嵌套字符串数组来建立逻辑连接。数组筛选器的最大深度为两层。包含三层或更多层嵌套的表达式将抛出错误。

外层数组元素通过 AND 运算符连接。以下表达式返回由 Jordan Peele 执导的 horror 类型电影：

["genres = horror", "director = 'Jordan Peele'"]

内层数组元素通过 OR 运算符连接。以下表达式返回 horror 或 comedy 类型的电影：

[["genres = horror", "genres = comedy"]]

内外层数组可以自由组合。以下表达式返回由 Jordan Peele 执导的 horror 和 comedy 类型电影：

[["genres = horror", "genres = comedy"], "director = 'Jordan Peele'"]

​

结合数组和字符串运算符

您也可以创建同时使用数组和字符串语法的筛选表达式。

以下筛选器以字符串形式编写，仅返回不属于 Jordan Peele 执导且属于 comedy 或 horror 类型的电影：

"(genres = comedy OR genres = horror) AND director != 'Jordan Peele'"

您可以使用数组和字符串混合编写相同的筛选器：

[["genres = comedy", "genres = horror"], "NOT director = 'Jordan Peele'"]