GraphQL API

website/pages/en/querying/graphql-api.mdx

@@ -2,11 +2,19 @@
 title: GraphQL API
 ---
 
-This guide explains the GraphQL Query API that is used for The Graph Protocol.
+Learn about the GraphQL Query API used in The Graph.
 
-## Queries
+## What is GraphQL?
 
-In your subgraph schema you define types called `Entities`. For each `Entity` type, an `entity` and `entities` field will be generated on the top-level `Query` type. Note that `query` does not need to be included at the top of the `graphql` query when using The Graph.
+[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](/network/developing/) and [creating a subgraph](/developing/creating-a-subgraph/).
+
+## 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.
+
+> Note: `query` does not need to be included at the top of the `graphql` query when using The Graph.
 
 ### Examples
 
@@ -21,7 +29,7 @@ Query for a single `Token` entity defined in your schema:
 }
 ```
 
-> **Note:** When querying for a single entity, the `id` field is required, and it must be a string.
+> Note: When querying for a single entity, the `id` field is required, and it must be writen as a string.
 
 Query all `Token` entities:
 
@@ -36,7 +44,10 @@ Query all `Token` entities:
 
 ### Sorting
 
-When querying a collection, the `orderBy` parameter may be used to sort by a specific attribute. Additionally, the `orderDirection` can be used to specify the sort direction, `asc` for ascending or `desc` for descending.
+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.
 
 #### Example
 
@@ -53,7 +64,7 @@ When querying a collection, the `orderBy` parameter may be used to sort by a spe
 
 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.
 
-In the following example, we sort the tokens by the name of their owner:
+The following example shows tokens sorted by the name of their owner:
 
 ```graphql
 {
@@ -70,11 +81,12 @@ In the following example, we sort the tokens by the name of their owner:
 
 ### Pagination
 
-When querying a collection, the `first` parameter can be used to paginate from the beginning of the collection. It is worth noting that the default sort order is by ID in ascending alphanumeric order, not by creation time.
-
-Further, the `skip` parameter can be used to skip entities and paginate. e.g. `first:100` shows the first 100 entities and `first:100, skip:100` shows the next 100 entities.
+When querying a collection, it's best to:
 
-Queries should avoid using very large `skip` values since they generally perform poorly. For retrieving a large number of items, it is much better to page through entities based on an attribute as shown in the last example.
+- 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.
 
 #### Example using `first`
 
@@ -106,7 +118,7 @@ Query 10 `Token` entities, offset by 10 places from the beginning of the collect
 
 #### Example using `first` and `id_ge`
 
-If a client needs to retrieve a large number of entities, it is much more performant to base queries on an attribute and filter by that attribute. For example, a client would retrieve a large number of tokens using this query:
+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:
 
 ```graphql
 query manyTokens($lastID: String) {
@@ -117,11 +129,12 @@ query manyTokens($lastID: String) {
 }
 ```
 
-The first time, it would send the query with `lastID = ""`, and for subsequent requests 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.
+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.
 
 ### Filtering
 
-You can use the `where` parameter in your queries to filter for different properties. You can filter on multiple values within the `where` parameter.
+- 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`
 
@@ -155,7 +168,7 @@ You can use suffixes like `_gt`, `_lte` for value comparison:
 
 #### Example for block filtering
 
-You can also filter entities by the `_change_block(number_gte: Int)` - this filters entities which were updated in or after the specified block.
+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).
 
@@ -193,7 +206,7 @@ As of Graph Node [`v0.30.0`](https://github.com/graphprotocol/graph-node/release
 
 ##### `AND` Operator
 
-In the following example, we are filtering for challenges with `outcome` `succeeded` and `number` greater than or equal to `100`.
+The following example filters for challenges with `outcome` `succeeded` and `number` greater than or equal to `100`.
 
 ```graphql
 {
@@ -223,7 +236,7 @@ In the following example, we are filtering for challenges with `outcome` `succee
 
 ##### `OR` Operator
 
-In the following example, we are filtering for challenges with `outcome` `succeeded` or `number` greater than or equal to `100`.
+The following example filters for challenges with `outcome` `succeeded` or `number` greater than or equal to `100`.
 
 ```graphql
 {
@@ -278,9 +291,9 @@ _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.
+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 that 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 that the result of a query by block hash for a block that can not be considered final yet might 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.
+> 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
 
@@ -376,11 +389,11 @@ Graph Node implements [specification-based](https://spec.graphql.org/October2021
 
 ## Schema
 
-The schema of your data source--that is, the entity types, values, and relationships that are available to query--are defined through the [GraphQL Interface Definition Langauge (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System).
+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)](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.
+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.
+> Note: Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications.
 
 ### Entities