Filter Rules

Directus 中过滤规则的 REST 和 GraphQL API 文档。

筛选规则

权限、验证和 API 的 filter 参数都依赖于特定的 JSON 结构来定义它们的规则。 本页介绍了创建平面、关系或复杂过滤规则的语法。

语法

{
 <field>: {
  <operator>: <value>
 }
}

示例

json
{
  "title": {
    "_contains": "Directus"
  }
}
json
{
  "owner": {
    "_eq": "$CURRENT_USER"
  }
}
json
{
  "datetime": {
    "_lte": "$NOW"
  }
}

过滤运算符

运算标题 (在后台界面)运算描述
等于_eq等于
不等于_neq不等于
少于_lt小于
小于或等于_lte小于或等于
大于_gt大于
大于或等于_gte大于或等于
是其中之一_in匹配任何值
不是其中之一_nin不匹配任何值
一片空白_null是null
不为空_nnull不是null
包含_contains包含子字符串
不包含_ncontains不包含子字符串
以。。开始_starts_with以
不是开头_nstarts_with不以
以。。结束_ends_with以
不以_nends_with不以
在。。。之间_between介于两个值之间(包括)
不在之间_nbetween不在两个值之间(包括)
是空的_empty为空(null 或假)
不是空的_nempty不为空(null 或 假的)
相交_intersects 1值与给定点相交
不相交_nintersects 1值不与给定点相交
相交边界框_intersects_bbox 1值在边界框中
不与边界框相交_nintersects_bbox 1值不在边界框中

以下运算符在过滤器界面上没有标题，因为它仅在验证权限中可用：

Operator描述
_regex 2字段必须匹配正则表达式

1 仅适用于几何类型。 2 JavaScript“风味”正则表达式。 确保避开反斜杠。

关系

您可以通过嵌套字段名称来定位相关值。 例如，如果您有一个关系多对一的 author 字段，则可以使用以下语法为 author.name 字段设置规则。

json
{
  "author": {
    "name": {
      "_eq": "Rijk van Zanten"
    }
  }
}

使用 M2M 关系时，将创建一个联结表，并将过滤器应用于联结表本身。 例如，如果您有一个 books 集合，与每本书的作者具有 M2M 关系，则连接集合可能会被命名为 books_authors 并具有 3 个字段：id、books_id 和 authors_id。 要根据作者过滤特定书籍，您必须通过联结表和 authors_id 字段：

json
{
  "authors": {
    "authors_id": {
      "name": {
        "_eq": "Rijk van Zanten"
      }
    }
  }
}

逻辑运算符

您可以使用 _and 或 _or 逻辑运算符嵌套或分组多个规则。 每个逻辑运算符都包含一组过滤规则，允许进行更复杂的过滤。 另请注意，在示例中，逻辑运算符可以子嵌套到逻辑运算符中。 但是，它们不能被子嵌套到过滤器规则中。

json
{
  "_or": [
    {
      "_and": [
        {
          "user_created": {
            "_eq": "$CURRENT_USER"
          }
        },
        {
          "status": {
            "_in": ["published", "draft"]
          }
        }
      ]
    },
    {
      "_and": [
        {
          "user_created": {
            "_neq": "$CURRENT_USER"
          }
        },
        {
          "status": {
            "_in": ["published"]
          }
        }
      ]
    }
  ]
}

一对多中的Some与None

将过滤器应用于一对多字段时，Directus 将默认为“Some”搜索，例如：

json
{
  "categories": {
    "name": {
      "_eq": "Recipe"
    }
  }
}

如果 one of 类别的名称为“Recipe”，则将返回顶级父级。 可以使用显式的 _some 和 _none 运算符来覆盖此行为，例如：

json
{
  "categories": {
    "_none": {
      "name": {
        "_eq": "Recipe"
      }
    }
  }
}

将获取所有不属于“Recipe”类别的父项

动态变量

除了静态值之外，您还可以使用以下变量过滤 dynamic 值。

  • $CURRENT_USER — 当前认证用户的主键
  • $CURRENT_ROLE — 当前认证用户的角色主键
  • $NOW - 当前时间戳
  • $NOW(<adjustment>) - 当前时间戳加/减给定距离，例如$NOW(-1 year),$NOW(+2 hours)

函数
您还可以在构建过滤器时使用 函数参数。

权限中的嵌套用户/角色变量
配置权限时，$CURRENT_USER 和 $CURRENT_ROLE 允许您指定当前用户/角色下的任何(嵌套)字段以及根 ID。 例如：$CURRENT_ROLE.name 或 $CURRENT_USER.avatar.filesize。 这包括添加到 directus_users/directus_roles 表的自定义字段。

注意：此功能仅适用于权限、验证和预设。 常规过滤器和条件字段目前仅支持根 ID。