Merge branch 'graphql-docs-rework' into develop

docs/cloud/resources/best-practices.md

@@ -18,9 +18,11 @@ Batch handler data filtering used to be compulsory before the release of `@subsq
 
 * If your squid [saves its data to a database](/sdk/resources/persisting-data/typeorm), make sure your [schema](/sdk/reference/schema-file) has [`@index` decorators](/sdk/reference/schema-file/indexes-and-constraints) for all entities that will be looked up frequently.
 
-* If your squid serves a [GraphQL API](/sdk/resources/graphql-server), consider:
-  1. configuring the built-in [DoS protection](/sdk/resources/graphql-server/dos-protection) against heavy queries;
-  2. configuring [caching](/sdk/resources/graphql-server/caching).
+* If your squid serves a [GraphQL API](/sdk/resources/basics/serving-graphql)
+  1. Do not use the [SQD GraphQL server](/sdk/resources/basics/serving-graphql/#the-sqd-graphql-server) if your application uses subscriptions. Instead, use [PostGraphile](/sdk/resources/basics/serving-graphql/#postgraphile) or [Hasura](/sdk/resources/basics/serving-graphql/#hasura).
+  2. If you do use the SQD GraphQL server:
+     - configure the built-in [DoS protection](/sdk/reference/graphql-server/configuration/dos-protection) against heavy queries;
+     - configure [caching](/sdk/reference/graphql-server/configuration/caching).
 
 * If you deploy your squid to Subsquid Cloud:
   1. Deploy your squid to a [Professional organization](/cloud/resources/organizations/#professional-organizations).

docs/glossary.md

@@ -70,11 +70,14 @@ An SDK (software development kit) and a smart-contract language for developing W
 
 ### OpenReader
 
-An open-source GraphQL server that automatically generates an expressive API from an input schema file.
+The GraphQL schema generation library at the heart of the open-source [SQD GraphQL server](/sdk/reference/graphql-server).
+
 * [GitHub repo](https://github.com/subsquid/squid-sdk/tree/master/graphql/openreader)
-* [Server documentation](/sdk/resources/graphql-server)
+* [Server documentation](/sdk/reference/graphql-server/overview)
 * [Schema dialect reference](/sdk/reference/schema-file)
-* [GraphQL API reference](/sdk/reference/openreader)
+* [GraphQL API reference](/sdk/reference/graphql-server/openreader)
+
+See [Serving GraphQL](/sdk/resources/basics/serving-graphql) to learn more.
 
 ### Pallet
 

docs/overview.mdx

@@ -51,7 +51,7 @@ For real-time use cases such as app-specific APIs use [Squid SDK](/sdk): it'll u
 - [High-level libraries](/sdk/reference/processors) for extracting and filtering the Subsquid Network data in what can be though of as Extract-Transform-Load (ETL) pipelines
 - [Ergonomic tools](/sdk/resources/tools/typegen) for decoding and normalizing raw data and efficiently accessing [network state](/sdk/resources/tools/typegen/state-queries)
 - Pluggable [data sinks](/sdk/reference/store) to save data into Postgres, files (local or s3) or BigQuery
-- Expressive [GraphQL server](/sdk/resources/graphql-server) with a schema-based [config](/sdk/reference/schema-file)
+- An expressive [GraphQL server](/sdk/resources/basics/serving-graphql#the-sqd-graphql-server) with a schema-based [config](/sdk/reference/schema-file)
 - Seamless handling of [unfinalized blocks and chain reorganizations](/sdk/resources/basics/unfinalized-blocks) for real-time data ingestion
 - rapid data extraction and decoding [for local analytics](/sdk/tutorials/file-csv)
 
@@ -81,7 +81,7 @@ A Platform-as-a-Service for deploying Squid SDK indexers, featuring
 - Learn about [squid components](/sdk/overview), [combining them](/sdk/how-to-start/squid-from-scratch) or follow the [end-to-end development guide](/sdk/how-to-start/squid-development)
 - Explore [tutorials](/sdk/tutorials) or [examples](/sdk/examples)
 - Learn how to [migrate from The Graph](/sdk/resources/migrate/migrate-subgraph)
-- Explore the [GraphQL server options](/sdk/resources/graphql-server) including custom extensions, caching and DoS protection in production
+- Explore the [GraphQL server options](/sdk/resources/basics/serving-graphql)
 
 ```mdx-code-block
 </TabItem>

docs/sdk/faq.md

@@ -24,7 +24,7 @@ Since the ArrowSquid release, the Squid SDK has the option to ingest unfinalized
 
 ### How do I enable GraphQL subscriptions for local runs?
 
-Add `--subscription` flag to the `serve` command defined in `commands.json`. See [Subscriptions](/sdk/resources/graphql-server/subscriptions) for details.
+Add `--subscription` flag to the `serve` command defined in `commands.json`. See [Subscriptions](/sdk/reference/graphql-server/configuration/subscriptions) for details.
 
 ### How do squids keep track of their sync progress?
 

docs/sdk/how-to-start/layout.md

@@ -13,13 +13,13 @@ All files and folders except `package.json` are optional.
 - `tsconfig.json` -- Configuration of `tsc`. Required for most squids.
 - [Deployment manifest](/cloud/reference/manifest) (`squid.yaml` by default) -- Definitions of squid services used for running it locally with [`sqd run`](/squid-cli/run) and deploying to [Subsquid Cloud](/cloud).
 - `.squidignore` -- Files and patterns to be excluded when sending the squid code to the [Cloud](/cloud). When not supplied, some files will still be omitted: see the [reference page](/cloud/reference/squidignore) for details.
-- `schema.graphql` -- [The schema definition file](/sdk/reference/schema-file). Required if your squid uses the [built-in GraphQL server](/sdk/resources/graphql-server).
+- `schema.graphql` -- [The schema definition file](/sdk/reference/schema-file). Required if your squid [stores its data in PostgreSQL](/sdk/resources/persisting-data/typeorm).
 - `/src` -- The TypeScript source code folder for the squid processor.
    + `/src/main.ts` -- The entry point of the squid processor process. Typically, contains a `processor.run()` call.
    + `/src/processor.ts` -- Processor object ([EVM](/sdk/reference/processors/evm-batch) or [Substrate](/sdk/reference/processors/substrate-batch)) definition and configuration.
    + `/src/model/generated` -- The folder for the TypeORM entities generated from `schema.graphql`.
    + `/src/model` -- The module exporting the entity classes.
-   + `/src/server-extension/resolvers` -- A folder for [user-defined GraphQL resolvers](/sdk/resources/graphql-server/custom-resolvers).
+   + `/src/server-extension/resolvers` -- A folder for [user-defined GraphQL resolvers](/sdk/reference/graphql-server/configuration/custom-resolvers) used by the [SQD GraphQL server](/sdk/reference/graphql-server).
    + `/src/types` -- A folder for types generated by the Substrate [typegen](/sdk/resources/tools/typegen/) tool for use in data decoding.
    + `/src/abi` -- A folder for modules generated by the EVM [typegen](/sdk/resources/tools/typegen/) tool containing type definitions and data decoding boilerplate code.
 - `/db` -- The designated folder with the [database migrations](/sdk/resources/persisting-data/typeorm).

docs/sdk/how-to-start/squid-development.mdx

@@ -27,7 +27,7 @@ See also the [Environment set up](/sdk/how-to-start/development-environment-set-
 Consider your business requirements and find out
 
 1. How the data should be delivered. Options:
-   - [PostgreSQL](/sdk/resources/persisting-data/typeorm) with an optional [GraphQL API](/sdk/resources/graphql-server) - can be real-time
+   - [PostgreSQL](/sdk/resources/persisting-data/typeorm) with an optional [GraphQL API](/sdk/resources/basics/serving-graphql) - can be real-time
    - [file-based dataset](/sdk/resources/persisting-data/file) - local or on S3
    - [Google BigQuery](/sdk/resources/persisting-data/bigquery/)
 2. What data should be delivered
@@ -57,10 +57,10 @@ Suppose you want to train a prototype ML model on all trades done on Uniswap Pol
 <details>
 <summary>NFT ownership on Ethereum</summary>
 
-Suppose you want to make a website that shows the image and ownership history for ERC721 NFTs from a certain Polygon contract.
+Suppose you want to make a website that shows the image and ownership history for ERC721 NFTs from a certain Ethereum contract.
 
 1. For this application it makes sense to deliver a GraphQL API.
-2. Output data might have `Token`, `Owner` and `Transfer` [entities](/sdk/reference/openreader/queries), with e.g. `Token` supplying all the fields necessary to show ownership history and the image.
+2. Output data might have `Token`, `Owner` and `Transfer` database tables / [entities](/sdk/reference/schema-file/entities), with e.g. `Token` supplying all the fields necessary to show ownership history and the image.
 3. Ethereum is an EVM chain.
 4. Data on token mints and ownership history can be derived from `Transfer(address,address,uint256)` EVM event logs emitted by the contract. To render images, you will also need token metadata URLs that are only available by [querying the contract state](/sdk/resources/tools/typegen/state-queries) with the `tokenURI(uint256)` function.
 5. You'll need to retrieve the off-chain token metadata (usually from IPFS).
@@ -464,7 +464,7 @@ At `src/main.ts`, change the [`Database`](/sdk/resources/persisting-data/overvie
 <TabItem value="typeorm" label="PostgreSQL+GraphQL">
 ```
 
-1. Define the schema of the database (and the [core schema of the GraphQL API](/sdk/reference/openreader) if it is used) at [`schema.graphql`](/sdk/reference/schema-file).
+1. Define the schema of the database (and the [core schema of the GraphQL API](/sdk/reference/graphql-server/openreader) if it is used) at [`schema.graphql`](/sdk/reference/schema-file).
 
 2. Regenerate the TypeORM model classes with
    ```bash
@@ -641,4 +641,4 @@ For complete examples of complex squids take a look at the [Giant Squid Explorer
 ## Next steps
 
 * Deploy your squid [on own infrastructure](/sdk/resources/basics/self-hosting) or to [Subsquid Cloud](/cloud)
-* If your squid serves a GraphQL API, consult the [Core GraphQL API reference](/sdk/reference/openreader) while writing your frontend
+* If your squid serves a [SQD GraphQL server](/sdk/reference/graphql-server/)-compatible API, consult the [core GraphQL API reference](/sdk/reference/graphql-server/openreader) while writing your frontend application.

docs/sdk/overview.mdx

@@ -75,9 +75,9 @@ Install these with `--save-dev`.
 
 ### GraphQL server
 
-Squids that store their data in PostgreSQL can subsequently make it available as a GraphQL API. To use this functionality, install [`@subsquid/graphql-server`](https://www.npmjs.com/package/@subsquid/graphql-server).
+Squids that store their data in PostgreSQL can subsequently make it available as a GraphQL API via a variety of supported servers. See [Serving GraphQL](/sdk/resources/basics/serving-graphql).
 
-The [server](/sdk/resources/graphql-server) runs as a separate process. [Core API](/sdk/reference/openreader) is automatically derived from the database schema; it is possible to extend it with [custom queries](/sdk/resources/graphql-server/custom-resolvers) and [basic access control](/sdk/resources/graphql-server/authorization).
+Among other alternatives, SQD provides its own server via the [`@subsquid/graphql-server`](https://www.npmjs.com/package/@subsquid/graphql-server) package. The server runs as a separate process. [Core API](/sdk/reference/graphql-server/openreader) is automatically derived from the schema file; it is possible to extend it with [custom queries](/sdk/reference/graphql-server/configuration/custom-resolvers) and [basic access control](/sdk/reference/graphql-server/configuration/authorization).
 
 ### Misc utilities
 

docs/sdk/resources/graphql-server/_category_.json → docs/sdk/reference/graphql-server/_category_.json

@@ -1,12 +1,12 @@
 {
-    "position": 11,
+    "position": 80,
     "label": "GraphQL server",
     "collapsible": true,
     "collapsed": true,
     "className": "red",
     "link": {
       "type": "generated-index",
-      "slug": "/sdk/resources/graphql-server",
-      "title": "GraphQL API server for squid data"
+      "slug": "/sdk/reference/graphql-server",
+      "title": "The SQD GraphQL server, built in-house"
     }
 }

docs/sdk/reference/graphql-server/configuration/_category_.json

@@ -0,0 +1,12 @@
+{
+    "position": 20,
+    "label": "Configuration",
+    "collapsible": true,
+    "collapsed": true,
+    "className": "red",
+    "link": {
+      "type": "generated-index",
+      "slug": "/sdk/reference/graphql-server/configuration",
+      "title": "Configuring and extending the server"
+    }
+}

docs/sdk/resources/graphql-server/authorization.md → docs/sdk/reference/graphql-server/configuration/authorization.md

@@ -48,7 +48,7 @@ Here,
 
 ## Sending user data to resolvers
 
-Authentication data such as user name can be passed from `requestCheck()` to a [custom resolver](/sdk/resources/graphql-server/custom-resolvers/) through Openreader context:
+Authentication data such as user name can be passed from `requestCheck()` to a [custom resolver](/sdk/reference/graphql-server/configuration/custom-resolvers/) through Openreader context:
 ```typescript
 export async function requestCheck(req: RequestCheckContext): Promise<boolean | string> {
   ...
@@ -100,7 +100,7 @@ export class UserCommentResolver {
 ```
 See full code in [this branch](https://github.com/subsquid-labs/access-control-example/tree/interacting-with-resolver).
 
-This approach does not work with [subscriptions](/sdk/resources/graphql-server/subscriptions/).
+This approach does not work with [subscriptions](/sdk/reference/graphql-server/configuration/subscriptions/).
 
 ## Examples
 

docs/sdk/resources/graphql-server/dos-protection.md → docs/sdk/reference/graphql-server/configuration/dos-protection.md

@@ -65,7 +65,7 @@ In a nutshell, assuming that the schema file is properly decorated with `@cardin
 
 **`--subscription-max-response-size <nodes>`**
 
-Same as `--max-response-size` but for live query [subscriptions](/sdk/resources/graphql-server/subscriptions).
+Same as `--max-response-size` but for live query [subscriptions](/sdk/reference/graphql-server/configuration/subscriptions).
 
 #### Example
 

docs/sdk/resources/graphql-server/subscriptions.md → docs/sdk/reference/graphql-server/configuration/subscriptions.md

@@ -4,7 +4,11 @@ title: Subscriptions
 description: Subscribe to updates over a websocket
 ---
 
-# Query subscriptions
+# Subscriptions
+
+:::danger
+RAM usage of subscriptions scales poorly under high load, making the feature unsuitable for most production uses. There are currently no plans to fix this issue.
+:::
 
 OpenReader supports [GraphQL subscriptions](https://www.apollographql.com/docs/react/data/subscriptions/) via live queries. To use these, a client opens a websocket connection to the server and sends a `subscription` query there. The query body is then repeatedly executed (every 5 seconds by default) and the results are sent to the client whenever they change.
 
@@ -16,7 +20,7 @@ npx squid-graphql-server --help
 For each entity types, the following queries are supported for subscriptions:
 - `${EntityName}ById` -- query a single entity
 - `${EntityName}s` -- query multiple entities with a `where` filter
-Note that despite being [deprecated](/sdk/resources/graphql-server/overview/#supported-queries) from the regular query set, `${EntityName}s` queries will continue to be available for subscriptions going forward.
+Note that despite being [deprecated](/sdk/reference/graphql-server/overview/#supported-queries) from the regular query set, `${EntityName}s` queries will continue to be available for subscriptions going forward.
 
 ## Local runs
 

docs/sdk/reference/graphql-server/openreader/_category_.json

@@ -0,0 +1,12 @@
+{
+  "position": 30,
+  "label": "Core API",
+  "collapsible": true,
+  "collapsed": true,
+  "className": "red",
+  "link": {
+    "type": "generated-index",
+    "slug": "/sdk/reference/graphql-server/openreader",
+    "title": "Core queries exposed by the SQD GraphQL server API"
+  }
+}

docs/sdk/reference/openreader/and-or-filters.md → docs/sdk/reference/graphql-server/openreader/and-or-filters.md

@@ -9,11 +9,11 @@ description: >-
 
 ## Overview
 
-Our GraphQL implementation offers a vast selection of tools to filter and section results. One of these is the `where` clause, very common in most database query languages and [explained here](/sdk/reference/openreader/queries/#filter-query-results--search-queries) in detail.
+Our GraphQL implementation offers a vast selection of tools to filter and section results. One of these is the `where` clause, very common in most database query languages and [explained here](/sdk/reference/graphql-server/openreader/queries/#filter-query-results--search-queries) in detail.
 
 In our GraphQL server implementation, we included logical operators to be used in the `where` clause, allowing to group multiple parameters in the same `where` argument using the `AND` and `OR` operators to filter results based on more than one criteria.
 
-Note that the [newer](/sdk/resources/graphql-server/overview/#supported-queries) and [more advanced](/sdk/reference/openreader/paginate-query-results) `{entityName}sConnection` queries support exactly the same format of the `where` argument as the older `{entityName}s` queries used in the examples provided here.
+Note that the [newer](/sdk/reference/graphql-server/overview/#supported-queries) and [more advanced](/sdk/reference/graphql-server/openreader/paginate-query-results) `{entityName}sConnection` queries support exactly the same format of the `where` argument as the older `{entityName}s` queries used in the examples provided here.
 
 ### Example of an `OR` clause:
 

docs/sdk/reference/openreader/cross-relation-field-queries.md → docs/sdk/reference/graphql-server/openreader/cross-relation-field-queries.md

@@ -9,7 +9,7 @@ description: >-
 
 ## Introduction
 
-The [previous section](/sdk/reference/openreader/nested-field-queries) has already demonstrated that queries can return not just scalars such as a String, but also fields that refer to object or entity types. What's even more interesting is that queries can leverage fields of related objects to filter results.
+The [previous section](/sdk/reference/graphql-server/openreader/nested-field-queries) has already demonstrated that queries can return not just scalars such as a String, but also fields that refer to object or entity types. What's even more interesting is that queries can leverage fields of related objects to filter results.
 
 Let's take this sample schema with two entity types and a one-to-many relationship between them:
 

docs/sdk/reference/openreader/intro.md → docs/sdk/reference/graphql-server/openreader/intro.md

@@ -6,14 +6,14 @@ description: >-
 ---
 
 :::info
-At the moment, [Squid SDK GraphQL server](/sdk/resources/graphql-server) can only be used with squids that use Postgres as their target database.
+At the moment, [Squid SDK GraphQL server](/sdk/reference/graphql-server) can only be used with squids that use Postgres as their target database.
 :::
 
 GraphQL is an API query language, and a server-side runtime for executing queries using a custom type system. Head over to the [official documentation website](https://graphql.org/learn/) for more info.
 
-A GraphQL API served by the [GraphQL server](/sdk/resources/graphql-server) has two components:
+A GraphQL API served by the [GraphQL server](/sdk/reference/graphql-server) has two components:
 
 1. Core API is defined by the [schema file](/sdk/reference/schema-file).
-2. Extensions added via [custom resolvers](/sdk/resources/graphql-server/custom-resolvers).
+2. Extensions added via [custom resolvers](/sdk/reference/graphql-server/configuration/custom-resolvers).
 
 In this section we cover the core GraphQL API, with short explanations on how to perform GraphQL queries, how to paginate and sort results. This functionality is supported via [OpenReader](https://github.com/subsquid/squid-sdk/tree/master/graphql/openreader), Subsquid's own implementation of [OpenCRUD](https://www.opencrud.org).

docs/sdk/reference/openreader/nested-field-queries.md → docs/sdk/reference/graphql-server/openreader/nested-field-queries.md

@@ -44,4 +44,4 @@ query {
 }
 
 ```
-Note that the [newer](/sdk/resources/graphql-server/overview/#supported-queries) and [more advanced](/sdk/reference/openreader/paginate-query-results) `{entityName}sConnection` queries support exactly the same format of the `where` argument as the older `{entityName}s` queries used in the examples provided here.
+Note that the [newer](/sdk/reference/graphql-server/overview/#supported-queries) and [more advanced](/sdk/reference/graphql-server/openreader/paginate-query-results) `{entityName}sConnection` queries support exactly the same format of the `where` argument as the older `{entityName}s` queries used in the examples provided here.