官方文档|托管服务之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类型上生成一个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
搜索字段中可以使用几个特殊的全文运算符。
全文搜索运算符:
符号 | 运算 | 描述 |
& | 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架构通常定义queries
,subscriptions
和mutations
的根类型。 Graph仅支持queries
。 子图的根Query
类型是根据子图清单中包含的GraphQL架构自动生成的。
注意:我们的API不会暴露突变,因为开发人员应直接从其应用程序针对基础区块链发布交易。
实体
架构中所有带有@entity
指令的GraphQL类型都将被视为实体,并且必须具有ID
字段。
注意:当前,架构中的所有类型都必须具有@entity
指令。 将来,我们会将不带@entity
指令的类型视为值对象,但是尚不支持。