Graphql revampt (#932)

* Rewrite beginning

* copy edits

* Editing

* Fix typo

* Fix build

* Copy tweak

* Fix table

* Fix errors

* Actually fixing

Author: MichaelMacaulay

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

@@ -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:
 
@@ -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.
@@ -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.
 
@@ -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:
 
@@ -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:
 
@@ -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:
 
@@ -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
 {
@@ -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
 {
@@ -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)`.
 
@@ -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.
 
@@ -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`.
 
@@ -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`.
 
@@ -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
 
@@ -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
 {
@@ -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" }) {
@@ -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 |
 | `<->` | `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
 {
@@ -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
 {
@@ -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
 {
@@ -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: