全局查询参数 Global Parameters

在 Directus 中运行查询的 REST 和 GraphQL API 文档。大多数 Directus API 端点操作都可以使用以下参数进行操作。 了解它们以充分利用平台非常重要。

Fields

选择当前数据集中返回的字段。 该参数支持点表示法来请求嵌套的关系字段。 您还可以使用通配符 (*) 来包含特定深度的所有字段。

示例

获取所有顶级字段：*

获取所有顶级字段和所有二级关系字段：*.*

提高查询速度
虽然字段通配符对于调试目的非常有用，但我们建议仅请求 特定 字段以供生产使用。 通过仅请求您真正需要的字段，您可以加快请求速度，并减少整体输出大小。

获取图片中所有顶级字段和二级关系字段：*,images.*

仅获取 first_name 和 last_name 字段：first_name,last_name

获取 images.thumbnails 中所有顶级和二级关系字段以及三级字段：*.*,images.thumbnails.*

多对任意(联合类型)

看到多对任意 (M2A) 字段具有来自多个集合的嵌套数据，它并不总是安全/想要从每个相关集合中获取相同的字段。 在 M2A 字段中，您可以使用以下语法来指定要从哪个相关嵌套集合类型中获取哪些字段：\ ?fields=<m2a-field>:<collection-scope>.<field>。

假设我们有一个集合pages，其中包含一个名为sections的多对任意字段，它指向headings、paragraphs和videos。 我们只想从headings中获取title和level，从paragraphs中获取body和从videos中获取source。 我们可以通过使用：

js
sections.item:headings.title
sections.item:headings.level
sections.item:paragraphs.body
sections.item:videos.source

在 GraphQL 中，这可以使用联合类型来实现。

REST API

js
?fields=title,body,featured_image.*
// or
?fields[]=title
&fields[]=body
&fields[]=featured_image.*

GraphQL

GraphQL 原生支持

Filter

用于搜索集合中与过滤器条件匹配的项目。 过滤器参数遵循 过滤器规则规范，其中包括有关逻辑运算符 (AND/OR)、嵌套关系过滤和动态变量的附加信息。

示例

检索 first_name 等于 "Rijk" 的所有项目

json
{
  "first_name": {
    "_eq": "Rijk"
  }
}

检索以下类别之一中的所有项目：“vegetables”、“fruit”

json
{
  "categories": {
    "_in": ["vegetables", "fruit"]
  }
}

检索在两个日期之间发布的所有项目

json
{
  "date_published": {
    "_between": ["2021-01-24", "2021-02-23"]
  }
}

检索作者的“vip”标签为真的所有项目

json
{
  "author": {
    "vip": {
      "_eq": true
    }
  }
}

嵌套过滤器
上面的示例将根据条件 in 相关项过滤 top level 项。 如果您想自己过滤相关项目，请查看 deep 参数！

REST API

js
?filter[first_name][_eq]=Rijk
// or
?filter={ "first_name": { "_eq": "Rijk" }}

GraphQL

js
query {
 users(filter: { first_name: { _eq: "Rijk" } }) {
  id
 }
}

Filtering M2A fields
由于 GraphQL 中的属性名称不能包含 : 字符，因此您需要将其替换为双下划线。 例如，不要在过滤器中使用 sections.item:heading，而需要使用 sections.item__heading(请参阅下面的完整示例)。

js
query {
    articles(filter: {
        sections: {
            item__headings: {  # Instead of: item:headings
                title: {
                    _eq: "Section 1"
                }
            }
        }
    }): {
        id
    }
}

search 参数允许您对集合中的所有字符串和文本类型字段执行搜索。 这是一种无需创建复杂字段过滤器即可搜索项目的简单方法——尽管它的优化程度要低得多。 它只搜索根项目的字段，不包括相关项目的字段。

示例

查找所有提及 Directus `Directus' 的项目

REST API

js
?search=Directus

GraphQL

js
query {
 articles(search: "Directus") {
  id
 }
}

Sort

要排序的字段。 排序默认为升序，但可以使用减号 (-) 将其反转为降序。 字段按参数中的顺序排列优先级。 排序时必须使用点符号 具有嵌套字段的值。

示例

  • 按创建日期降序排序：-date_created
  • 按sort字段排序，然后是发布日期降序：sort, -publish_date
  • 按“排序”字段排序，后跟嵌套的作者姓名：sort, -author.name

REST API

js
?sort=sort,-date_created,author.name
// or
?sort[]=sort
&sort[]=-date_created
&sort[]=-author.name

GraphQL

js
query {
 articles(sort: ["sort", "-date_created", "author.name"]) {
  id
 }
}

Limit

设置将返回的最大项目数。 默认限制设置为“100”。

示例

获取前 200 个项目：200

获取所有项目：-1

所有项目
根据集合的大小，获取无限数据可能会导致性能下降或超时，请谨慎使用。

REST API

js
?limit=200

GraphQL

js
query {
 articles(limit: 200) {
  id
 }
}

Offset

跳过查询结果中的前 n 个项目。 可用于分页。

示例

获取项目，从101到200：100

REST API

js
?offset=100

GraphQL

js
query {
 articles(offset: 100) {
  id
 }
}

Page

offset 的替代方法。 Page 是一种通过计算 limit * page 来设置 offset 的方法。 当前列表页是从1到已索引过的页数。

示例

Get items 1-100：1

Get items 101-200：2

REST API

js
?page=2

GraphQL

js
query {
 articles(page: 2) {
  id
 }
}

Aggregation Grouping

聚合函数允许您对一组值执行计算，返回单个结果。

Directus 中提供了以下聚合函数：

名称描述
count计算有多少项目
countDistinct计算有多少独特的项目
sum将给定字段中的值相加
sumDistinct将给定字段中的唯一值相加
avg获取给定字段的平均值
avgDistinct获取给定字段中唯一值的平均值
min返回字段中的最小值
max返回字段中的最大值
countAll等价于 ?aggregate[count]=*(仅限 GraphQL)

分组

默认情况下，上述聚合函数在整个数据集上运行。 为了允许更灵活的报告，您可以将上述聚合与分组结合起来。 分组允许基于共享值运行聚合函数。 这允许诸如 “每月平均评分” 或 “牛仔裤类别中商品的总销售额” 之类的内容。

groupBy 查询允许同时对多个字段进行分组。 结合 函数，这允许按 年-月-日 进行汇总报告。

REST API

js
?aggregate[avg]=cost
&groupBy[]=author
&groupBy[]=year(publish_date)

GraphQL

js
query {
 articles_aggregated(groupBy: ["author", "year(publish_date)"]) {
  group
  sum {
   revenue
  }
 }
}

Deep

Deep 允许您在嵌套关系数据集上设置任何其他查询参数。

示例

将嵌套的相关文章限制为 3

json
{
  "related_articles": {
    "_limit": 3
  }
}

仅获得 3 篇相关文章，仅嵌套评分最高的评论

json
{
  "related_articles": {
    "_limit": 3,
    "comments": {
      "_sort": "rating",
      "_limit": 1
    }
  }
}

REST API

js
?deep[translations][_filter][languages_code][_eq]=en-US
// or
?deep={ "translations": { "_filter": { "languages_code": { "_eq": "en-US" }}}}

GraphQL

GraphQL 原生支持：

js
query {
 members {
  favorite_games(filter: { name: { _eq: "Mariokart 8" } }) {
   id
   featured_image {
    filename_disk
   }
  }
 }
}

Aliases

别名 允许您即时重命名字段，并使用不同的过滤器多次请求相同的嵌套数据集。

嵌套字段
只能为相同级别的字段起别名。 嵌套字段的别名，f.e. field.nested，将不起作用。

REST API

js
?alias[all_translations]=translations
&alias[dutch_translations]=translations
&deep[dutch_translations][_filter][code][_eq]=nl-NL

GraphQL

GraphQL 原生支持：

js
query {
 articles {
  dutch_translations: translations(filter: { code: { _eq: "nl-NL" } }) {
   id
  }

  all_translations: translations {
   id
  }
 }
}

Export

将当前 API 响应保存到文件中。

将 API 响应保存到文件中。 接受 json、csv、xml、yaml 之一。

REST API

js
?export=json
?export=csv
?export=xml
?export=yaml

GraphQL

n/a

Functions

函数允许对存储在字段中的值进行“实时”修改。 函数可用于通常提供字段键的任何查询参数，包括字段、聚合和过滤器。

可以通过将字段键包装在类似 JavaScript 的语法中来使用函数，例如：

timestamp -> year(timestamp)

日期时间函数

FilterDescription
year从日期时间/日期/时间戳字段中提取年份
month从日期时间/日期/时间戳字段中提取月份
week从日期时间/日期/时间戳字段中提取星期
day从日期时间/日期/时间戳字段中提取日期
weekday从日期时间/日期/时间戳字段中提取工作日
hour从日期时间/日期/时间戳字段中提取小时
minute从日期时间/日期/时间戳字段中提取分钟
second从日期时间/日期/时间戳字段中提取第二个

Array Functions

FilterDescription
count从 JSON 数组或关系字段中提取项目数

GraphQL
名称不允许在 GraphQL 中包含任何特殊字符，从而阻止使用 () 语法。

作为替代方案，可以通过在字段名称末尾附加 _func 并使用函数名称作为嵌套字段来使用上述函数(参见下面的示例)。

REST API

js
?fields=id,title,weekday(date_published)
&filter[year(date_published)][_eq]=2021

GraphQL

js
query {
 articles(filter: { date_published_func: { year: { _eq: 2021 } } }) {
  id
  title
  date_published_func {
   weekday
  }
 }
}

Metadata

元数据允许您检索有关您正在获取的集合中的项目的一些附加信息。 * 可以用作通配符来检索所有元数据。

Total Count

返回您正在查询的集合的总项目数。

Filter Count

返回您正在查询的集合的项目计数，同时考虑当前的过滤器/搜索参数。

REST API

js
?meta=total_count

?meta=filter_count

?meta=*

GraphQL

n/a