Revert "Graphql revampt (#932)"

This reverts commit c9382c6.

Author: MichaelMacaulay

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

@@ -2,36 +2,22 @@
 title: GraphQL API
 ---
 
-Explore the GraphQL Query API for interacting with Subgraphs on The Graph Network.
+Learn about the GraphQL Query API used in The Graph.
 
 ## 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.
 
-## 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
+To understand the larger role that GraphQL plays, review [developing](/subgraphs/developing/introduction/) and [creating a Subgraph](/developing/creating-a-subgraph/).
 
 ## Queries with GraphQL
 
-In the Subgraph schema, types called `Entities`. For each `Entity` type, `entity` and `entities` fields will be generated on the top-level `Query` type.
-
-### Example Queries
+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
+
 Query for a single `Token` entity defined in your schema:
 
 ```graphql
@@ -58,7 +44,7 @@ Query all `Token` entities:
 
 ### Sorting
 
-When querying a collection, you can:
+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.
@@ -74,7 +60,7 @@ When querying a collection, you can:
 }
 ```
 
-#### 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.
 
@@ -102,7 +88,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:
 
@@ -115,9 +101,9 @@ Query the first 10 tokens:
 }
 ```
 
-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.
+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.
 
-#### Example Using `first` and `skip`
+#### Example using `first` and `skip`
 
 Query 10 `Token` entities, offset by 10 places from the beginning of the collection:
 
@@ -130,7 +116,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:
 
@@ -150,9 +136,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.
 
-#### Using `where` Filtering
+#### Example using `where`
 
-Query challenges with `failed` outcome using 'where' filter:
+Query challenges with `failed` outcome:
 
 ```graphql
 {
@@ -168,7 +154,7 @@ Query challenges with `failed` outcome using 'where' filter:
 
 You can use suffixes like `_gt`, `_lte` for value comparison:
 
-#### Range Filtering
+#### Example for range filtering
 
 ```graphql
 {
@@ -180,7 +166,7 @@ You can use suffixes like `_gt`, `_lte` for value comparison:
 }
 ```
 
-#### Block Filtering
+#### Example for block filtering
 
 You can also filter entities that were updated in or after a specified block with `_change_block(number_gte: Int)`.
 
@@ -196,7 +182,7 @@ This can be useful if you are looking to fetch only entities which have changed,
 }
 ```
 
-#### Nested Entity Filtering
+#### Example for nested entity filtering
 
 Filtering on the basis of nested entities is possible in the fields with the `_` suffix.
 
@@ -214,11 +200,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.
 
-#### Using `and` Operator
+##### `AND` Operator
 
 The following example filters for challenges with `outcome` `succeeded` and `number` greater than or equal to `100`.
 
@@ -248,7 +234,7 @@ The following example filters for challenges with `outcome` `succeeded` and `num
 > }
 > ```
 
-#### Using `or` Operator
+##### `OR` Operator
 
 The following example filters for challenges with `outcome` `succeeded` or `number` greater than or equal to `100`.
 
@@ -264,7 +250,7 @@ The following example filters for challenges with `outcome` `succeeded` or `numb
 }
 ```
 
-> **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.
+> **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.
 
 #### All Filters
 
@@ -301,15 +287,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 Time-travel Queries
+#### Example
 
 ```graphql
 {
@@ -325,6 +311,8 @@ 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" }) {
@@ -339,24 +327,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.
 
-### Full-text Search Queries
+### Fulltext Search Queries
 
-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 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 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 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 operators:
+Fulltext 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.) |
 
-#### Full-text Query Examples
+#### Examples
 
-Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their full-text fields.
+Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields.
 
 ```graphql
 {
@@ -369,7 +357,7 @@ Using the `or` operator, this query will filter to blog entities with variations
 }
 ```
 
-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"
+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"
 
 ```graphql
 {
@@ -382,7 +370,7 @@ The `follow by` operator specifies that two words must appear a specific distanc
 }
 ```
 
-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".
+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".
 
 ```graphql
 {
@@ -399,6 +387,20 @@ Combine full-text operators to make more complex filters. With a pretext search
 
 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: