Skip to content

Graphql revampt #932

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 23, 2025
Merged

Graphql revampt #932

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ff23e78
Rewrite beginning
MichaelMacaulay Apr 11, 2025
4e51bda
copy edits
MichaelMacaulay Apr 17, 2025
4d4f007
Editing
MichaelMacaulay Apr 22, 2025
615b390
Fix typo
MichaelMacaulay Apr 22, 2025
842b8bb
Fix build
MichaelMacaulay Apr 22, 2025
f135af6
Copy tweak
MichaelMacaulay Apr 22, 2025
cb39acb
Fix table
MichaelMacaulay Apr 22, 2025
222bac3
Fix errors
MichaelMacaulay Apr 22, 2025
d278384
Actually fixing
MichaelMacaulay Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 46 additions & 48 deletions website/src/pages/en/subgraphs/querying/graphql-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,35 @@
title: GraphQL API
---

Learn about the GraphQL Query API used in The Graph.
Explore the GraphQL Query API for interacting with Subgraphs on The Graph Network.

## What is GraphQL?

[GraphQL](https://graphql.org/learn/) 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](/subgraphs/developing/introduction/) and [creating a Subgraph](/developing/creating-a-subgraph/).
## Core Concepts

### Entities

- **What they are**: Persistent data objects defined with `@entity` in your schema
- **Key requirement**: Must contain `id: ID!` as primary identifier
- **Usage**: Foundation for all query operations

### Schema

- **Purpose**: Blueprint defining the data structure and relationships using GraphQL [IDL](https://facebook.github.io/graphql/draft/#sec-Type-System)
- **Key characteristics**:
- Auto-generates query endpoints
- Read-only operations (no mutations)
- Defines entity interfaces and derived fields

## Queries with GraphQL

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.
In the Subgraph schema, types called `Entities`. For each `Entity` type, `entity` and `entities` fields will be generated on the top-level `Query` type.

> Note: `query` does not need to be included at the top of the `graphql` query when using The Graph.
### Example Queries

### Examples
> Note: `query` does not need to be included at the top of the `graphql` query when using The Graph.

Query for a single `Token` entity defined in your schema:

Expand Down Expand Up @@ -44,7 +58,7 @@ Query all `Token` entities:

### Sorting

When querying a collection, you may:
When querying a collection, you can:

- 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.
Expand All @@ -60,7 +74,7 @@ When querying a collection, you may:
}
```

#### Example for nested entity sorting
#### Example for Nested Entity Sorting

As of Graph Node [`v0.30.0`](https://github.com/graphprotocol/graph-node/releases/tag/v0.30.0) entities can be sorted on the basis of nested entities.

Expand Down Expand Up @@ -88,7 +102,7 @@ When querying a collection, it's best to:
- 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.

#### Example using `first`
#### Example Using `first`

Query the first 10 tokens:

Expand All @@ -101,9 +115,9 @@ Query the first 10 tokens:
}
```

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.
To query for groups of entities in the middle of a collection, the `skip` parameter can be used in conjunction with the `first` parameter to skip a specified number of entities starting at the beginning of the collection.

#### Example using `first` and `skip`
#### Example Using `first` and `skip`

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

Expand All @@ -116,7 +130,7 @@ Query 10 `Token` entities, offset by 10 places from the beginning of the collect
}
```

#### Example using `first` and `id_ge`
#### Example Using `first` and `id_ge`

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:

Expand All @@ -136,9 +150,9 @@ The first time, it would send the query with `lastID = ""`, and for subsequent r
- You can use the `where` parameter in your queries to filter for different properties.
- You can filter on multiple values within the `where` parameter.

#### Example using `where`
#### Using `where` Filtering

Query challenges with `failed` outcome:
Query challenges with `failed` outcome using 'where' filter:

```graphql
{
Expand All @@ -154,7 +168,7 @@ Query challenges with `failed` outcome:

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

#### Example for range filtering
#### Range Filtering

```graphql
{
Expand All @@ -166,7 +180,7 @@ You can use suffixes like `_gt`, `_lte` for value comparison:
}
```

#### Example for block filtering
#### Block Filtering

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

Expand All @@ -182,7 +196,7 @@ This can be useful if you are looking to fetch only entities which have changed,
}
```

#### Example for nested entity filtering
#### Nested Entity Filtering

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

Expand All @@ -200,11 +214,11 @@ This can be useful if you are looking to fetch only entities whose child-level e
}
```

#### Logical operators
### Logical Operators

As of Graph Node [`v0.30.0`](https://github.com/graphprotocol/graph-node/releases/tag/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.

##### `AND` Operator
#### Using `and` Operator

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

Expand Down Expand Up @@ -234,7 +248,7 @@ The following example filters for challenges with `outcome` `succeeded` and `num
> }
> ```

##### `OR` Operator
#### Using `or` Operator

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

Expand All @@ -250,7 +264,7 @@ The following example filters for challenges with `outcome` `succeeded` or `numb
}
```

> **Note**: When constructing queries, it is important to consider the performance impact of using the `or` operator. While `or` can be a useful tool for broadening search results, it can also have significant costs. One of the main issues with `or` is that it can cause queries to slow down. This is because `or` requires the database to scan through multiple indexes, which can be a time-consuming process. To avoid these issues, it is recommended that developers use and operators instead of or whenever possible. This allows for more precise filtering and can lead to faster, more accurate queries.
> **Note**: When writing queries, it is important to consider the performance impact of using the `or` operator. While `or` can be a useful tool for broadening search results, it can also have significant costs. One of the main issues with `or` is that it can cause queries to slow down. This is because `or` requires the database to scan through multiple indexes, which can be a time-consuming process. To avoid these issues, it is recommended that developers use and operators instead of or whenever possible. This allows for more precise filtering and can lead to faster, more accurate queries.

#### All Filters

Expand Down Expand Up @@ -287,15 +301,15 @@ In addition, the following global filters are available as part of `where` argum
_change_block(number_gte: Int)
```

### Time-travel queries
### Time-travel Queries

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.

> Note: The current implementation is still subject to certain limitations that might violate these guarantees. The implementation can not always tell that a given block hash is not on the main chain at all, or if a query result by a block hash for a block that is not yet considered final could be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. [This issue](https://github.com/graphprotocol/graph-node/issues/1405) explains what these limitations are in detail.

#### Example
#### Example Time-travel Queries

```graphql
{
Expand All @@ -311,8 +325,6 @@ The result of such a query will not change over time, i.e., querying at a certai

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

#### Example

```graphql
{
challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) {
Expand All @@ -327,24 +339,24 @@ This query will return `Challenge` entities, and their associated `Application`

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 Queries
### Full-text Search Queries

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](/developing/creating-a-subgraph/#defining-fulltext-search-fields) to add fulltext search to your Subgraph.
Full-text search query fields provide an expressive text search API that can be added to the Subgraph schema and customized. Refer to [Defining Full-text Search Fields](/developing/creating-a-subgraph/#defining-fulltext-search-fields) to add full-text 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.
Full-text search queries have one required field, `text`, for supplying search terms. Several special full-text operators are available to be used in this `text` search field.

Fulltext search operators:
Full-text search operators:

| Symbol | Operator | Description |
| --- | --- | --- |
| --- | --- | --- | --- |
| `&` | `And` | For combining multiple search terms into a filter for entities that include all of the provided terms |
| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms |
| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be |, no?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean with the backticks. Otherwise it will be interpreted as a new column by the Markdown parser, right?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MichaelMacaulay (in case you don't get a notification if I don't tag you, since this PR was already merged :P)

| `<->` | `Follow by` | Specify the distance between two words. |
| `:*` | `Prefix` | Use the prefix search term to find words whose prefix match (2 characters required.) |

#### Examples
#### Full-text Query Examples

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

```graphql
{
Expand All @@ -357,7 +369,7 @@ Using the `or` operator, this query will filter to blog entities with variations
}
```

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"
The `follow by` operator specifies that two words must appear a specific distance apart in full-text documents.. The following query will return all blogs with variations of "decentralize" followed by "philosophy"

```graphql
{
Expand All @@ -370,7 +382,7 @@ The `follow by` operator specifies a words a specific distance apart in the full
}
```

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".
Combine full-text 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".

```graphql
{
Expand All @@ -387,20 +399,6 @@ Combine fulltext operators to make more complex filters. With a pretext search o

Graph Node implements [specification-based](https://spec.graphql.org/October2021/#sec-Validation) validation of the GraphQL queries it receives using [graphql-tools-rs](https://github.com/dotansimha/graphql-tools-rs#validation-rules), which is based on the [graphql-js reference implementation](https://github.com/graphql/graphql-js/tree/main/src/validation). Queries which fail a validation rule do so with a standard error - visit the [GraphQL spec](https://spec.graphql.org/October2021/#sec-Validation) to learn more.

## Schema

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 Language (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System).

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](/developing/creating-a-subgraph/#components-of-a-subgraph).

> Note: Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications.

### Entities

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

> **Note:** Currently, all types in your schema must have an `@entity` directive. In the future, we will treat types without an `@entity` directive as value objects, but this is not yet supported.

### Subgraph Metadata

All Subgraphs have an auto-generated `_Meta_` object, which provides access to Subgraph metadata. This can be queried as follows:
Expand Down