官方文档｜托管服务之GraphQL API

GRT Fans首发
原文作者：The Graph
译者：Becky
原文出处：https://thegraph.com/docs/graphql-api
翻译出处：https://www.yuque.com/becky-sltzq/kaab7x/qgf9or

本文档说明了如何使用GraphQL查询API的语句和示例。

查询

在你的子图模式subgraph schema中，定义称为Entities实体的类型。 对于每种Entity类型，将在顶层的Query类型上生成一个entity和entities字段。 请注意，使用NAS Graph调用查询时，不需要在graphql顶部再加query。

例子

查询你在子图模式subgraph schema中定义的单个Token entity实体。

{
  token(id: "1") {
    id
    owner
  }
}

注意：当查询单个实体时，必须带上id字段，且必须为一个字符串。

查询所有Token entity实体。

{
  tokens {
    id
    owner
  }
}

排序

查询集合时，可以使用orderBy参数按特定属性进行排序。 另外，orderDirection可用于指定排序方向，asc表示升序，desc表示降序。

例子

按token价格升序排序。

{
  tokens(orderBy: price, orderDirection: asc) {
    id
    owner
  }
}

分页

查询集合时，可以使用first参数作为集合的开头进行分页。 值得注意的是，默认排序顺序是按ID升序字母数字顺序，而不是按创建时间。

此外，skip参数可用于跳过实体和分页。 例如 first:100显示前100个实体，first:100, skip:100显示后100个实体。

注意，查询时应避免使用非常大的skip值，因为它们通常表现不佳。 对于检索大量数据的项目，最好根据上一个示例中所示的属性来对实体进行分类。

例子

查询前10个token：

{
  tokens(first: 10) {
    id
    owner
  }
}

为了查询集合中间的实体组，可以将skip参数与first参数结合使用，从集合的开头开始跳过指定数量的实体。

例子

查询10个Token实体，从集合开始偏移10个位置：

{
  tokens(first: 10, skip: 10) {
    id
    owner
  }
}

例子

如果客户端需要检索大量实体，则将查询基于属性并按该属性进行过滤会更有效率。 例如，可以使用以下方法查询检索大量token：

{
  query manyTokens($lastID: String) {
    tokens(first: 1000, where: { id_gt: $lastID  }) {
      id
      owner
    }
  }
}

第一次，它将发送带有lastID = ""的查询，并且对于后续请求，会将lastID设置为上一个请求中最后一个实体的id属性。 与使用增加skip值相比，此方法的性能要好得多。

筛选

你可以在查询中使用where参数来筛选不同的属性。 你可以过滤where参数中的多重值。

例子

查询failed输出：

{
  challenges(where: { outcome: "failed" }) {
    challenger
    outcome
    application {
      id
    }
  }
}

你可以使用诸如_gt，_lte之类的后缀进行值比较：

例子

{
  applications(where: { deposit_gt: "10000000000" }) {
    id
    whitelisted
    deposit
  }
}

参数后缀的完整列表：

_not
_gt
_lt
_gte
_lte
_in
_not_in
_contains
_not_contains
_starts_with
_ends_with
_not_starts_with
_not_ends_with

请注意，某些后缀仅适用于特定类型。 例如，Boolean仅支持_not，_in和_not_in。

Time-travel查询

你不仅可以查询最新一个区块实体的状态，（默认情况下是查最新的区块），还可以查询过去的任意块。通过在查询的顶层字段中包含block参数，可以通过其块号或其块哈希来指定查询哪些区块。

这样的查询结果不会随时间变化，即，无论执行什么时候，在特定的过去的区块中查询都将返回相同的结果，但如果你在非常靠近公链网络开头的区块中进行查询，如果该区块不在主链上并且链被重组过，结果可能会改变。一旦一个区块可以被认为是最终的，查询的结果将不会改变。

请注意，当前的实现仍然受到某些可能会违反这些保证的限制。该实现不能总是说出给定的区块哈希值根本不在主链上，或者不能通过区块哈希值查询一个不能被视为最终块的查询结果，可能会受到同时运行的链重组的影响。当区块是最终的且已知位于主链上时，按区块哈希查询的结果就不受影响。此处原文详细解释了这些限制。

例子

{
  challenges(block: { number: 8000000 }) {
    challenger
    outcome
    application {
      id
    }
  }
}

查询返回在8,000,000个区块后，存在的Challenge实体及其关联的Application实体。

例子

{
  challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) {
    challenger
    outcome
    application {
      id
    }
  }
}

查询返回在给定的区块哈希后，存在的Challenge实体及其关联的Application实体。

全文搜索查询

全文搜索查询字段提供了可表达的文本搜索API，可以将其添加到子图模式并进行自定义。 请参阅原文定义全文搜索字段以将全文搜索添加到子图。

全文搜索查询具有一个必填字段，即test，用于提供搜索词。 在test搜索字段中可以使用几个特殊的全文运算符。

全文搜索运算符：

例子

使用or运算符，此查询将过滤出全文字段中具有“无政府主义”或“烤饼”的博客。

{
    blogSearch(text: "anarchism | crumpets") {
        id
        title
        body
        author    
    }
}

follow by符运算符在全文文档中指定相距特定距离的单词。 以下查询将返回所有带有“去中心化”后跟“哲学”的博客。

{
    blogSearch(text: "decentralized <-> philosophy") {
        id
        title
        body
        author    
    }
}

结合全文运算符可以制作更复杂的过滤器。 在此示例的前面加上前缀搜索运算符后，查询将匹配所有博客，并以“ lou”后跟“ music”开头的单词匹配。

{
    blogSearch(text: "lou:* <-> music") {
        id
        title
        body
        author    
    }
}

架构

数据源的架构（即可供查询的实体类型，值和关系）是通过GraphQL接口定义语言（IDL）定义的。

GraphQL架构通常定义queries，subscriptions和mutations的根类型。 Graph仅支持queries。 子图的根Query类型是根据子图清单中包含的GraphQL架构自动生成的。

注意：我们的API不会暴露突变，因为开发人员应直接从其应用程序针对基础区块链发布交易。

实体

架构中所有带有@entity指令的GraphQL类型都将被视为实体，并且必须具有ID字段。

注意：当前，架构中的所有类型都必须具有@entity指令。 将来，我们会将不带@entity指令的类型视为值对象，但是尚不支持。