GraphQL API

Reading time: 10 min

Learn about the GraphQL Query API used in The Graph.

GraphQL is a query language for APIs and a runtime for executing those queries with your existing data. The Graph uses GraphQL to query subgraphs.

To understand the larger role that GraphQL plays, review developing and creating a subgraph.

In your subgraph schema you define types called Entities. For each Entity type, entity and entities fields will be generated on the top-level Query type.

Query for a single Token entity defined in your schema:

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

Query all Token entities:

{
  tokens {
    id
    owner
  }
}

When querying a collection, you may:

• Use the orderBy parameter to sort by a specific attribute.
• Use the orderDirection to specify the sort direction, asc for ascending or desc for descending.

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

As of Graph Node v0.30.0 entities can be sorted on the basis of nested entities.

The following example shows tokens sorted by the name of their owner:

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

When querying a collection, it's best to:

• Use the first parameter to paginate from the beginning of the collection.
  • The default sort order is by ID in ascending alphanumeric order, not by creation time.
• Use the skip parameter to skip entities and paginate. For instance, first:100 shows the first 100 entities and first:100, skip:100 shows the next 100 entities.
• Avoid using skip values in queries because they generally perform poorly. To retrieve a large number of items, it's best to page through entities based on an attribute as shown in the previous example above.

Query the first 10 tokens:

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

To query for groups of entities in the middle of a collection, the skip parameter may be used in conjunction with the first parameter to skip a specified number of entities starting at the beginning of the collection.

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

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

If a client needs to retrieve a large number of entities, it's more performant to base queries on an attribute and filter by that attribute. For example, a client could retrieve a large number of tokens using this query:

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

The first time, it would send the query with lastID = "", and for subsequent requests it would set lastID to the id attribute of the last entity in the previous request. This approach will perform significantly better than using increasing skip values.

• You can use the where parameter in your queries to filter for different properties.
• You can filter on multiple values within the where parameter.

Query challenges with failed outcome:

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

You can use suffixes like _gt, _lte for value comparison:

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

You can also filter entities that were updated in or after a specified block with _change_block(number_gte: Int).

This can be useful if you are looking to fetch only entities which have changed, for example since the last time you polled. Or alternatively it can be useful to investigate or debug how entities are changing in your subgraph (if combined with a block filter, you can isolate only entities that changed in a specific block).

{
  applications(where: { _change_block: { number_gte: 100 } }) {
    id
    whitelisted
    deposit
  }
}

Filtering on the basis of nested entities is possible in the fields with the _ suffix.

This can be useful if you are looking to fetch only entities whose child-level entities meet the provided conditions.

{
  challenges(where: { application_: { id: 1 } }) {
    challenger
    outcome
    application {
      id
    }
  }
}

As of Graph Node v0.30.0 you can group multiple parameters in the same where argument using the and or the or operators to filter results based on more than one criteria.

The following example filters for challenges with outcome succeeded and number greater than or equal to 100.

{
  challenges(where: { and: [{ number_gte: 100 }, { outcome: "succeeded" }] }) {
    challenger
    outcome
    application {
      id
    }
  }
}

{
  challenges(where: { number_gte: 100, outcome: "succeeded" }) {
    challenger
    outcome
    application {
      id
    }
  }
}

The following example filters for challenges with outcome succeeded or number greater than or equal to 100.

{
  challenges(where: { or: [{ number_gte: 100 }, { outcome: "succeeded" }] }) {
    challenger
    outcome
    application {
      id
    }
  }
}

Full list of parameter suffixes:

_
_not
_gt
_lt
_gte
_lte
_in
_not_in
_contains
_contains_nocase
_not_contains
_not_contains_nocase
_starts_with
_starts_with_nocase
_ends_with
_ends_with_nocase
_not_starts_with
_not_starts_with_nocase
_not_ends_with
_not_ends_with_nocase

In addition, the following global filters are available as part of where argument:

_change_block(number_gte: Int)

You can query the state of your entities not just for the latest block, which is the default, but also for an arbitrary block in the past. The block at which a query should happen can be specified either by its block number or its block hash by including a block argument in the toplevel fields of queries.

The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change.

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

This query will return Challenge entities, and their associated Application entities, as they existed directly after processing block number 8,000,000.

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

This query will return Challenge entities, and their associated Application entities, as they existed directly after processing the block with the given hash.

Fulltext search query fields provide an expressive text search API that can be added to the subgraph schema and customized. Refer to Defining Fulltext Search Fields to add fulltext search to your subgraph.

Fulltext search queries have one required field, text, for supplying search terms. Several special fulltext operators are available to be used in this text search field.

Fulltext search operators:

Using the or operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields.

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

The follow by operator specifies a words a specific distance apart in the fulltext documents. The following query will return all blogs with variations of "decentralize" followed by "philosophy"

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

Combine fulltext operators to make more complex filters. With a pretext search operator combined with a follow by this example query will match all blog entities with words that start with "lou" followed by "music".

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

Graph Node implements specification-based validation of the GraphQL queries it receives using graphql-tools-rs, which is based on the graphql-js reference implementation. Queries which fail a validation rule do so with a standard error - visit the GraphQL spec to learn more.

The schema of your dataSources, i.e. the entity types, values, and relationships that are available to query, are defined through the GraphQL Interface Definition Langauge (IDL).

GraphQL schemas generally define root types for queries, subscriptions and mutations. The Graph only supports queries. The root Query type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest.

All GraphQL types with @entity directives in your schema will be treated as entities and must have an ID field.

All subgraphs have an auto-generated _Meta_ object, which provides access to subgraph metadata. This can be queried as follows:

{
  _meta(block: { number: 123987 }) {
    block {
      number
      hash
      timestamp
    }
    deployment
    hasIndexingErrors
  }
}

If a block is provided, the metadata is as of that block, if not the latest indexed block is used. If provided, the block must be after the subgraph's start block, and less than or equal to the most recently indexed block.

deployment is a unique ID, corresponding to the IPFS CID of the subgraph.yaml file.

block provides information about the latest block (taking into account any block constraints passed to _meta):

• hash: the hash of the block
• number: the block number
• timestamp: the timestamp of the block, if available (this is currently only available for subgraphs indexing EVM networks)

hasIndexingErrors is a boolean identifying whether the subgraph encountered indexing errors at some past block