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

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

官方文档|托管服务之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类型上生成一个entityentities字段。 请注意,使用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搜索字段中可以使用几个特殊的全文运算符。

全文搜索运算符:

符号

运算

描述

&

And

用于将多个搜索词组合到包含所有提供的词的实体的过滤器中

|

Or

带有多个搜索词(由或运算符分隔)的查询将返回与提供的任何字词匹配的所有实体

<->

Follow by

指定两个单词之间的距离。

:*

Prefix

使用前缀搜索词查找前缀匹配的单词(需要2个字符。)

例子

使用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架构通常定义queriessubscriptionsmutations的根类型。 Graph仅支持queries。 子图的根Query类型是根据子图清单中包含的GraphQL架构自动生成的。

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

实体


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

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