GraphQL API

GraphQL API

In the previous chapter, we talked about using GraphQL to define entities.

GraphQL is a language used for API queries. It provides a set of easy-to-understand and complete descriptions of the data in the API, so that the client can accurately obtain the data it needs. Therefore, it can be used to describe the data entity, and it can also be used to request the desired data and get the result. The data entities in the subgraph are described and defined using GraphQL Interface Definition Language (IDL).

This section explains how to use GraphQL to query data in HyperGraph.

Query

In the subgraph schema.graphql, the types called entities are defined. For each entity type, an entity and entity-associated field will be generated on the top-level query type.

example

Query a single Token entity defined in the entity definition file:

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

Note: When querying a single entity, the id field is a required field, and must be a string, usually an address or Hash and other uniquely identifying values.

Query all Token entities:

tokens {
 id
 owner
 }}

Sort

When querying the collection, you can use the orderBy parameter to sort by specific attributes. In addition, orderDirection can be used to specify the sorting direction, ascending order means ascending order, and descending order means descending order.

For example

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

Pagination

When querying a collection, you can use the first parameter to page from the beginning of the collection. It is worth noting that the default sort order is sorted by ID in ascending alphabetic and numerical order, not by creation time.

In addition, the skip parameter can be used to skip entities and paging. For example, first: 100 displays the first 100 entities, first: 100, skip: 100 displays the next 100 entities starting with the 100th. This is very similar to Limit start, number in SQL query.

Queries should avoid using very large skip values because they are usually very slow. For retrieving large amounts of data, it is best to paginate entities based on the attributes shown in the previous example.

For example:

Query the first 10 tokens:

tokens(first: 10) {
 id
 owner
 }}

In order to query a group of entities in the middle of a collection, you can combine the skip parameter with the first parameter to skip a specified number of entities from the beginning of the collection.

For example:

Query 10 Token entities, offset 10 positions from the beginning of the collection:

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

For example:

If you need to retrieve a large number of entities, it is more efficient to base the query on an attribute and filter by that attribute. For example, use the following query to retrieve data for a large number of Token entities:

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

For the first time, it will send a query with lastID="", and for subsequent requests, it will set lastID to the id attribute of the last entity in the previous request. Compared with using the increased skip value, the performance of this method is much better.

Filter

You can use the where parameter in the query to filter different attributes. You can filter multiple values in the where parameter, that is, set multiple conditions in where.

For example:

Challenges that failed to query:

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

You can use suffixes such as _gt, _lte for value comparison:

For example:

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

The complete list of parameter suffixes:

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

Note that some suffixes only apply to certain types. For example, Boolean only supports _not, _in and _not_in.

Time traversal query

Not only can you query the status of entities in the latest block (by default, the latest block is checked), but you can also query the status of any block in the past. By including the block parameter in the top-level field of the query, the block to be queried can be specified by its block number or its block hash.

The result of such a query will not change over time, that is, no matter when it is executed, the query in a specific past block will return the same result, with one exception, if you query in a block very close to the beginning of Ethereum , If the block is not on the main chain and the chain is reorganized, the result may change. Once a block can be considered final confirmation, the result of the query will not change.

For example:

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

The query will return the challenge entity and its associated application entity, because they exist directly after 8,000,000 blocks.

For example:

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

The query will return the challenge entity and its associated application entity, because they exist directly after using the block corresponding to the given hash.