diff --git a/docs/cloud/resources/best-practices.md b/docs/cloud/resources/best-practices.md index 65b769d7..8c65236c 100644 --- a/docs/cloud/resources/best-practices.md +++ b/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). diff --git a/docs/glossary.md b/docs/glossary.md index 675544c4..29e802aa 100644 --- a/docs/glossary.md +++ b/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 diff --git a/docs/overview.mdx b/docs/overview.mdx index a275b9f7..6ec94feb 100644 --- a/docs/overview.mdx +++ b/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 diff --git a/docs/sdk/faq.md b/docs/sdk/faq.md index bddf2137..45790e45 100644 --- a/docs/sdk/faq.md +++ b/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? diff --git a/docs/sdk/how-to-start/layout.md b/docs/sdk/how-to-start/layout.md index a8608965..1f58a7b2 100644 --- a/docs/sdk/how-to-start/layout.md +++ b/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). diff --git a/docs/sdk/how-to-start/squid-development.mdx b/docs/sdk/how-to-start/squid-development.mdx index 5f1189d6..abc38f4e 100644 --- a/docs/sdk/how-to-start/squid-development.mdx +++ b/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
NFT ownership on Ethereum -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 ``` -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. diff --git a/docs/sdk/overview.mdx b/docs/sdk/overview.mdx index 9ace965a..41513324 100644 --- a/docs/sdk/overview.mdx +++ b/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 diff --git a/docs/sdk/resources/graphql-server/_category_.json b/docs/sdk/reference/graphql-server/_category_.json similarity index 56% rename from docs/sdk/resources/graphql-server/_category_.json rename to docs/sdk/reference/graphql-server/_category_.json index 282d8113..7b140c91 100644 --- a/docs/sdk/resources/graphql-server/_category_.json +++ b/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" } } diff --git a/docs/sdk/reference/graphql-server/configuration/_category_.json b/docs/sdk/reference/graphql-server/configuration/_category_.json new file mode 100644 index 00000000..ea4bd71a --- /dev/null +++ b/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" + } +} diff --git a/docs/sdk/resources/graphql-server/authorization.md b/docs/sdk/reference/graphql-server/configuration/authorization.md similarity index 95% rename from docs/sdk/resources/graphql-server/authorization.md rename to docs/sdk/reference/graphql-server/configuration/authorization.md index 033dd8fd..d92d554c 100644 --- a/docs/sdk/resources/graphql-server/authorization.md +++ b/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 { ... @@ -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 diff --git a/docs/sdk/resources/graphql-server/caching.md b/docs/sdk/reference/graphql-server/configuration/caching.md similarity index 100% rename from docs/sdk/resources/graphql-server/caching.md rename to docs/sdk/reference/graphql-server/configuration/caching.md diff --git a/docs/sdk/resources/graphql-server/custom-resolvers.md b/docs/sdk/reference/graphql-server/configuration/custom-resolvers.md similarity index 100% rename from docs/sdk/resources/graphql-server/custom-resolvers.md rename to docs/sdk/reference/graphql-server/configuration/custom-resolvers.md diff --git a/docs/sdk/resources/graphql-server/dos-protection.md b/docs/sdk/reference/graphql-server/configuration/dos-protection.md similarity index 98% rename from docs/sdk/resources/graphql-server/dos-protection.md rename to docs/sdk/reference/graphql-server/configuration/dos-protection.md index 63586be7..2b78377e 100644 --- a/docs/sdk/resources/graphql-server/dos-protection.md +++ b/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 `** -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 diff --git a/docs/sdk/resources/graphql-server/subscriptions.md b/docs/sdk/reference/graphql-server/configuration/subscriptions.md similarity index 93% rename from docs/sdk/resources/graphql-server/subscriptions.md rename to docs/sdk/reference/graphql-server/configuration/subscriptions.md index e38a40fb..d09820ac 100644 --- a/docs/sdk/resources/graphql-server/subscriptions.md +++ b/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 diff --git a/docs/sdk/reference/graphql-server/openreader/_category_.json b/docs/sdk/reference/graphql-server/openreader/_category_.json new file mode 100644 index 00000000..e4fed209 --- /dev/null +++ b/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" + } +} diff --git a/docs/sdk/reference/openreader/and-or-filters.md b/docs/sdk/reference/graphql-server/openreader/and-or-filters.md similarity index 75% rename from docs/sdk/reference/openreader/and-or-filters.md rename to docs/sdk/reference/graphql-server/openreader/and-or-filters.md index 25405b1b..5141d303 100644 --- a/docs/sdk/reference/openreader/and-or-filters.md +++ b/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: diff --git a/docs/sdk/reference/openreader/cross-relation-field-queries.md b/docs/sdk/reference/graphql-server/openreader/cross-relation-field-queries.md similarity index 91% rename from docs/sdk/reference/openreader/cross-relation-field-queries.md rename to docs/sdk/reference/graphql-server/openreader/cross-relation-field-queries.md index 1142d451..c6f846e3 100644 --- a/docs/sdk/reference/openreader/cross-relation-field-queries.md +++ b/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: diff --git a/docs/sdk/reference/openreader/intro.md b/docs/sdk/reference/graphql-server/openreader/intro.md similarity index 78% rename from docs/sdk/reference/openreader/intro.md rename to docs/sdk/reference/graphql-server/openreader/intro.md index 585ed764..2a769356 100644 --- a/docs/sdk/reference/openreader/intro.md +++ b/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). diff --git a/docs/sdk/reference/openreader/json-queries.md b/docs/sdk/reference/graphql-server/openreader/json-queries.md similarity index 100% rename from docs/sdk/reference/openreader/json-queries.md rename to docs/sdk/reference/graphql-server/openreader/json-queries.md diff --git a/docs/sdk/reference/openreader/nested-field-queries.md b/docs/sdk/reference/graphql-server/openreader/nested-field-queries.md similarity index 81% rename from docs/sdk/reference/openreader/nested-field-queries.md rename to docs/sdk/reference/graphql-server/openreader/nested-field-queries.md index 79ae0156..eb74dc9a 100644 --- a/docs/sdk/reference/openreader/nested-field-queries.md +++ b/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. diff --git a/docs/sdk/reference/openreader/paginate-query-results.md b/docs/sdk/reference/graphql-server/openreader/paginate-query-results.md similarity index 92% rename from docs/sdk/reference/openreader/paginate-query-results.md rename to docs/sdk/reference/graphql-server/openreader/paginate-query-results.md index 954b097a..1a1cdde6 100644 --- a/docs/sdk/reference/openreader/paginate-query-results.md +++ b/docs/sdk/reference/graphql-server/openreader/paginate-query-results.md @@ -15,7 +15,7 @@ Cursors are used to traverse across entities of an entity set. They work by retu Currently, only forward pagination is supported. If your use case requires bidirectional pagination please let us know at our [Telegram channel](https://t.me/HydraDevs). -In Subsquid GraphQL server, cursor based pagination is implemented with `{entityName}sConnection` queries available for every entity in the input schema. These queries require an explicitly supplied [`orderBy` argument](/sdk/reference/openreader/sorting), and *the field that is used for ordering must also be requested by the query itself*. Check out [this section](/sdk/reference/openreader/paginate-query-results/#important-note-on-orderby) for a valid query template. +In Subsquid GraphQL server, cursor based pagination is implemented with `{entityName}sConnection` queries available for every entity in the input schema. These queries require an explicitly supplied [`orderBy` argument](/sdk/reference/graphql-server/openreader/sorting), and *the field that is used for ordering must also be requested by the query itself*. Check out [this section](/sdk/reference/graphql-server/openreader/paginate-query-results/#important-note-on-orderby) for a valid query template. Example: this query fetches a list of videos where `isExplicit` is true and gets their count. diff --git a/docs/sdk/reference/openreader/queries.md b/docs/sdk/reference/graphql-server/openreader/queries.md similarity index 94% rename from docs/sdk/reference/openreader/queries.md rename to docs/sdk/reference/graphql-server/openreader/queries.md index 69cd321f..e4832598 100644 --- a/docs/sdk/reference/openreader/queries.md +++ b/docs/sdk/reference/graphql-server/openreader/queries.md @@ -29,7 +29,7 @@ query { } } ``` -or, using a [newer](/sdk/resources/graphql-server/overview/#supported-queries) and [more advanced](/sdk/reference/openreader/paginate-query-results) `{entityName}sConnection` query +or, using a [newer](/sdk/reference/graphql-server/overview/#supported-queries) and [more advanced](/sdk/reference/graphql-server/openreader/paginate-query-results) `{entityName}sConnection` query ```graphql query { diff --git a/docs/sdk/reference/openreader/resolve-union-types-interfaces.md b/docs/sdk/reference/graphql-server/openreader/resolve-union-types-interfaces.md similarity index 100% rename from docs/sdk/reference/openreader/resolve-union-types-interfaces.md rename to docs/sdk/reference/graphql-server/openreader/resolve-union-types-interfaces.md diff --git a/docs/sdk/reference/openreader/sorting.md b/docs/sdk/reference/graphql-server/openreader/sorting.md similarity index 100% rename from docs/sdk/reference/openreader/sorting.md rename to docs/sdk/reference/graphql-server/openreader/sorting.md diff --git a/docs/sdk/reference/graphql-server/overview.md b/docs/sdk/reference/graphql-server/overview.md new file mode 100644 index 00000000..76cb7dd7 --- /dev/null +++ b/docs/sdk/reference/graphql-server/overview.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 10 +description: The SQD GraphQL server, built in-house +--- + +# Overview + +:::info +SQD GraphQL server is no longer recommended for use in new squid projects [relying on PostgreSQL](/sdk/resources/persisting-data/typeorm). See [Serving GraphQL](/sdk/resources/basics/serving-graphql) to learn about the new options and the [Known issues](#known-issues) section to understand our motivation. +::: + +The data indexed by a squid into a Postgres database can be automatically presented with a GraphQL API service powered by the [OpenReader](https://github.com/subsquid/squid-sdk/tree/master/graphql/openreader) lib of the Squid SDK. The OpenReader GraphQL server takes [schema file](/sdk/reference/schema-file) as an input and serves a GraphQL API supporting [OpenCRUD](https://www.opencrud.org/) queries for the entities defined in the schema. + +To start the API server based on `schema.graphql` install `@subsquid/graphql-server` and run the following in the squid project root: +```bash +npx squid-graphql-server +``` +The `squid-graphql-server` executable supports multiple optional flags to enable [caching](/sdk/reference/graphql-server/configuration/caching), [subscriptions](/sdk/reference/graphql-server/configuration/subscriptions), [DoS protection](/sdk/reference/graphql-server/configuration/dos-protection) etc. Its features are covered in the next sections. + +The API server listens at port defined by the `GQL_PORT` environment variable (defaults to `4350`). The database connection is configured with the env variables `DB_NAME`, `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`. + +The GraphQL API is enabled by the `api:` service in the `deploy` section of [squid.yaml](/cloud/reference/manifest) for Subsquid Cloud deployments. + +## Supported queries + +The details of the supported OpenReader queries can be found in a separate section [Query a Squid](/sdk/reference/graphql-server/openreader). Here is a brief overview of the queries generated by OpenReader for each entity defined in the schema file: + +- the squid last processed block is available with `squidStatus { height }` query +- a "get one by ID" query with the name `{entityName}ById` for each [entity](/sdk/reference/schema-file/entities) defined in the schema file +- a "get one" query for [`@unique` fields](/sdk/reference/schema-file/indexes-and-constraints), with the name `{entityName}ByUniqueInput` +- Entity queries named `{entityName}sConnection`. Each query supports rich filtering support, including [field-level filters](/sdk/reference/graphql-server/openreader/queries), composite [`AND` and `OR` filters](/sdk/reference/graphql-server/openreader/and-or-filters), [nested queries](/sdk/reference/graphql-server/openreader/nested-field-queries), [cross-relation queries](/sdk/reference/graphql-server/openreader/cross-relation-field-queries) and [Relay-compatible](https://relay.dev/graphql/connections.htm) cursor-based [pagination](/sdk/reference/graphql-server/openreader/paginate-query-results). +- [Subsriptions](/sdk/reference/graphql-server/configuration/subscriptions) via live queries +- (Deprecated in favor of Relay connections) Lookup queries with the name `{entityName}s`. + +[Union and typed JSON types](/sdk/reference/schema-file/unions-and-typed-json) are mapped into [GraphQL Union Types](https://graphql.org/learn/schema/#union-types) with a [proper type resolution](/sdk/reference/graphql-server/openreader/resolve-union-types-interfaces) with `__typename`. + +## Built-in custom scalar types + +The OpenReader GraphQL API defines the following custom scalar types: + +- `DateTime` entity field values are presented in the ISO format +- `Bytes` entity field values are presented as hex-encoded strings prefixed with `0x` +- `BigInt` entity field values are presented as strings + +## Known issues + +- RAM usage of [subscriptions](/sdk/reference/graphql-server/configuration/subscriptions) scales poorly under high load, making the feature unsuitable for most production uses. There are currently no plans to fix this issue. +- Setting up custom resolvers for subscriptions is unreasonably hard. +- `@subsquid/graphql-server` depends on the deprecated Apollo Server v3. diff --git a/docs/sdk/reference/openreader/_category_.json b/docs/sdk/reference/openreader/_category_.json deleted file mode 100644 index 45d1c4d1..00000000 --- a/docs/sdk/reference/openreader/_category_.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "position": 80, - "label": "Core GraphQL API", - "collapsible": true, - "collapsed": true, - "className": "red", - "link": { - "type": "generated-index", - "slug": "/sdk/reference/openreader", - "title": "Core queries exposed by the squid GraphQL API" - } -} diff --git a/docs/sdk/reference/schema-file/entity-relations.md b/docs/sdk/reference/schema-file/entity-relations.md index 6cacae57..aeca917d 100644 --- a/docs/sdk/reference/schema-file/entity-relations.md +++ b/docs/sdk/reference/schema-file/entity-relations.md @@ -10,7 +10,7 @@ The term "entity relation" refers to the situation when an entity instance conta [One-to-one](https://github.com/typeorm/typeorm/blob/master/docs/one-to-one-relations.md) and [one-to-many](https://github.com/typeorm/typeorm/blob/master/docs/many-to-one-one-to-many-relations.md) relations are supported by Typeorm. The "many" side of the one-to-many relations is always the owning side. Many-to-many relations are modeled as [two one-to-many relations with an explicit join table](#many-to-many-relations). -An entity relation is always unidirectional, but it is possible to request the data on the owning entity from the non-owning one. To do so, define a field decorated `@derivedFrom` in the schema. Doing so will cause the Typeorm code generated by [`squid-typeorm-codegen`](/sdk/resources/persisting-data/typeorm) and the GraphQL API served by [`squid-graphql-server`](/sdk/resources/graphql-server/overview/) to show a virtual (that is, **not mapping to a database column**) field populated via inverse lookup queries. +An entity relation is always unidirectional, but it is possible to request the data on the owning entity from the non-owning one. To do so, define a field decorated `@derivedFrom` in the schema. Doing so will cause the Typeorm code generated by [`squid-typeorm-codegen`](/sdk/resources/persisting-data/typeorm) and the GraphQL API served by [`squid-graphql-server`](/sdk/reference/graphql-server/overview) to show a virtual (that is, **not mapping to a database column**) field populated via inverse lookup queries. The following examples illustrate the concepts. diff --git a/docs/sdk/reference/schema-file/interfaces.md b/docs/sdk/reference/schema-file/interfaces.md index 26aadd9f..c95baead 100644 --- a/docs/sdk/reference/schema-file/interfaces.md +++ b/docs/sdk/reference/schema-file/interfaces.md @@ -6,7 +6,7 @@ description: Queriable interfaces # Interfaces -The schema file supports [GraphQL Interfaces](https://graphql.org/learn/schema/#interfaces) for modelling complex types sharing common traits. Interfaces are annotated with `@query` at the type level and do not affect the backing database schema, only enriching the [GraphQL API queries](/sdk/resources/graphql-server) with [inline fragments](https://graphql.org/learn/queries/#inline-fragments). +The schema file supports [GraphQL Interfaces](https://graphql.org/learn/schema/#interfaces) for modelling complex types sharing common traits. Interfaces are annotated with `@query` at the type level and do not affect the database schema, only enriching the [API queries](/sdk/reference/graphql-server/openreader) of the [SQD GraphQL server](/sdk/reference/graphql-server) with [inline fragments](https://graphql.org/learn/queries/#inline-fragments). ### Examples @@ -47,7 +47,7 @@ type Baz implements MyEntity @entity { } ``` -The `MyEntity` interface above enables `myEntities` and `myEntitiesConnection` [GraphQL API queries](/sdk/resources/graphql-server) with inline fragments and the `_type`, `__typename` [meta fields](https://graphql.org/learn/queries/#meta-fields): +The `MyEntity` interface above enables `myEntities` and `myEntitiesConnection` [GraphQL API queries](/sdk/reference/graphql-server/openreader) with inline fragments and the `_type`, `__typename` [meta fields](https://graphql.org/learn/queries/#meta-fields): ```graphql query { @@ -64,4 +64,4 @@ query { ... on Baz { baz } } } -``` \ No newline at end of file +``` diff --git a/docs/sdk/reference/schema-file/intro.md b/docs/sdk/reference/schema-file/intro.md index c75046a2..85631dd1 100644 --- a/docs/sdk/reference/schema-file/intro.md +++ b/docs/sdk/reference/schema-file/intro.md @@ -10,7 +10,7 @@ description: >- The schema file `schema.graphql` uses a GraphQL dialect to model the target entities and entity relations. The tooling around the schema file is then used to: - Generate TypeORM entities (with `squid-typeorm-codegen(1)`, see below) - Generate the database schema from the TypeORM entities (see [db migrations](/sdk/resources/persisting-data/typeorm)) -- Present the target data with a rich API served by a built-in [GraphQL Server](/sdk/resources/graphql-server). A full API reference is covered in the [Query a Squid](/sdk/reference/openreader) section. +- Optionally, the schema can be used to present the target data with a [GraphQL API](/sdk/resources/basics/serving-graphql). The schema file format is loosely compatible with the [subgraph schema](https://thegraph.com/docs/en/developing/creating-a-subgraph/) file, see [Migrate from subgraph](/sdk/resources/migrate/migrate-subgraph) section for details. diff --git a/docs/sdk/resources/basics/multichain.md b/docs/sdk/resources/basics/multichain.md index bf93a065..f8342178 100644 --- a/docs/sdk/resources/basics/multichain.md +++ b/docs/sdk/resources/basics/multichain.md @@ -6,7 +6,7 @@ description: Combine data from multiple chains # Multichain indexing -Squids can extract data from multiple chains into a shared data sink. If the data is [stored to Postgres](/sdk/resources/persisting-data/typeorm) it can then be served as a unified multichain [GraphQL API](/sdk/resources/graphql-server). +Squids can extract data from multiple chains into a shared data sink. If the data is [stored to Postgres](/sdk/resources/persisting-data/typeorm) it can then be served as a unified multichain [GraphQL API](/sdk/resources/basics/serving-graphql). To do this, run one [processor](/sdk/overview) per source network: @@ -69,7 +69,7 @@ Also ensure that async (ctx) => { // ... ``` -2. [Schema](/sdk/reference/schema-file) and [GraphQL API](/sdk/resources/graphql-server) are shared among the processors. +2. [Schema](/sdk/reference/schema-file) and [GraphQL API](/sdk/resources/basics/serving-graphql) are shared among the processors. ### Handling concurrency @@ -79,7 +79,7 @@ Also ensure that - To avoid cross-chain data dependencies, use per-chain records for volatile data. E.g. if you track account balances across multiple chains you can avoid overlaps by storing the balance for each chain in a different table row. - When you need to combine the records (e.g. get a total of all balaces across chains) use a [custom resolver](/sdk/resources/graphql-server/custom-resolvers) to do it on the GraphQL server side. + When you need to combine the records (e.g. get a total of all balaces across chains) use a [custom resolver](/sdk/reference/graphql-server/configuration/custom-resolvers) to do it on the GraphQL server side. - It is OK to use cross-chain [entities](/sdk/reference/schema-file/entities) to simplify aggregation. Just don't store any data in them: ```graphql diff --git a/docs/sdk/resources/graphql-server/database-creds.png b/docs/sdk/resources/basics/serving-graphql-database-creds.png similarity index 100% rename from docs/sdk/resources/graphql-server/database-creds.png rename to docs/sdk/resources/basics/serving-graphql-database-creds.png diff --git a/docs/sdk/resources/basics/serving-graphql.md b/docs/sdk/resources/basics/serving-graphql.md new file mode 100644 index 00000000..42a28526 --- /dev/null +++ b/docs/sdk/resources/basics/serving-graphql.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 80 +title: Serving GraphQL +description: GraphQL servers commonly used in squids +--- + +# Serving GraphQL + +It is common (although not required) for squids to serve GraphQL APIs. Historically, the most common way to do that was to [persist the squid data to PostgreSQL](/sdk/resources/persisting-data/typeorm), then attach the [SQD GraphQL server](#the-sqd-graphql-server) to it. Although this is still supported, we encourage using [PostGraphile](#postgraphile) or [Hasura](#hasura) in new PostgreSQD-based projects. See [SQD GraphQL server known issues](/sdk/reference/graphql-server/overview/#known-issues) if you're curious about our motivation. + +## PostGraphile + +[PostGraphile](https://www.graphile.org/postgraphile/) is an open-source tool that builds powerful, extensible and performant GraphQL APIs from PostgreSQL schemas. + +The recommended way of integrating PostGraphile into squid projects is by making a dedicated entry point at `src/api.ts`. A complete example squid implementing this approach is available in [this repository](https://github.com/subsquid-labs/squid-postgraphile-example/). + +With this entry point in place, we [create a `sqd` command](https://github.com/subsquid-labs/squid-postgraphile-example/blob/f1fd1691eb59da2c9d57c475a71d0ed44cfed891/commands.json#L58) for running PostGraphile with [`commands.json`](/squid-cli/commands-json), then use it in the [`deploy.api` entry](https://github.com/subsquid-labs/squid-postgraphile-example/blob/f1fd1691eb59da2c9d57c475a71d0ed44cfed891/squid.yaml#L15) of [Squid manifest](/cloud/reference/manifest). Although none of this is required, this makes it easier to run the squid both locally (with [`sqd run`](/squid-cli/run)) and in the [Cloud](/cloud). + +As per usual with PostGraphile installations, you can freely extend it with plugins, including your own. Here is an [example plugin for serving the `_squidStatus` queries](https://github.com/subsquid-labs/squid-postgraphile-example/blob/f1fd1691eb59da2c9d57c475a71d0ed44cfed891/src/api.ts#L11) from the standard Squid SDK GraphQL server schema. A plugin for making PostGraphile API fully compatible with old APIs served by the SQD GraphQL server will be made available soon. + +## Hasura + +[Hasura](https://hasura.io) is a powerful open-source GraphQL engine geared towards exposing multiple data sources via a single GraphQL API. You can integrate it with your squid in two ways: +1. **Use Hasura to gather data from multiple sources, including your squid.** + + For this scenario we recommend separating your Hasura instance from your squid, which should consist of just one service, [the processor](/sdk/reference/processors/architecture), plus the database. Supply your database credentials to Hasura, then configure it to produce the desired API. + + If you run your squid in our [Cloud](/cloud) you can find database credentials in [the app](https://app.subsquid.io/squids): + + ![database creds](serving-graphql-database-creds.png) + +2. **Run a dedicated Hasura instance for serving the data just from your squid.** + + A complete example implementing this approach is available in [this repository](https://github.com/subsquid-labs/squid-hasura-example). More TBA. + + + +## The SQD GraphQL server + +The [SQD GraphQL server](/sdk/reference/graphql-server) is a GraphQL server developed by the SQD team. Although still supported, it's not recommeded for new PostgreSQL-powered projects due to its [known issues](/sdk/reference/graphql-server/overview/#known-issues), especially for APIs implementing GraphQL subscriptions. + +The server uses the [schema file](/sdk/reference/schema-file) to produce its [core API](/sdk/reference/graphql-server/openreader) that can be extended with [custom resolvers](/sdk/reference/graphql-server/configuration/custom-resolvers). Extra features include [DoS protection](/sdk/reference/graphql-server/configuration/dos-protection). diff --git a/docs/sdk/resources/graphql-server/alternatives.md b/docs/sdk/resources/graphql-server/alternatives.md deleted file mode 100644 index 1e07b476..00000000 --- a/docs/sdk/resources/graphql-server/alternatives.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -sidebar_position: 90 -title: Alternatives -description: Using Squid SDK with PostGraphile or Hasura ---- - -# Alternatives to the SDK GraphQL server - -We encourage using squids with third-party GraphQL tools like [PostGraphile](https://www.graphile.org/postgraphile/) and [Hasura](https://hasura.io). No special configuration is required and there aren't any constraints on running them in [Subsquid Cloud](/cloud). - -## PostGraphile - -Here we cover one possible way of integrating PostGraphile into a squid project ([full example](https://github.com/subsquid-labs/squid-postgraphile-example/)). Note the following: - -* There is a dedicated entry point for PostGraphile (`src/api.ts`). It is complemented by an [`sqd` command](https://github.com/subsquid-labs/squid-postgraphile-example/blob/f1fd1691eb59da2c9d57c475a71d0ed44cfed891/commands.json#L58) and a [manifest entry](https://github.com/subsquid-labs/squid-postgraphile-example/blob/f1fd1691eb59da2c9d57c475a71d0ed44cfed891/squid.yaml#L15). This makes it easier to run the squid both locally (with [`sqd run`](/squid-cli/run)) and in [Cloud](/cloud). - -* As per usual with PostGraphile installations, you can freely extend it with plugins, including your own. Here is an [example plugin for serving the `_squidStatus` queries](https://github.com/subsquid-labs/squid-postgraphile-example/blob/f1fd1691eb59da2c9d57c475a71d0ed44cfed891/src/api.ts#L11) from the standard Squid SDK GraphQL server schema. - -## Hasura - -If you want to run Hasura in [Subsquid Cloud](/cloud), visit the [`hasura` addon page](/cloud/reference/hasura). - -When running it elsewhere, simply supply database credentials in your Hasura configuration. For squids running in Subsquid Cloud you can find the credentials in [the Cloud app](https://app.subsquid.io/squids). - -![database creds](database-creds.png) diff --git a/docs/sdk/resources/graphql-server/overview.md b/docs/sdk/resources/graphql-server/overview.md deleted file mode 100644 index 596f8d1e..00000000 --- a/docs/sdk/resources/graphql-server/overview.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_position: 10 -description: Zero-config GraphQL server ---- - -# Overview - -The data indexed by a squid into a Postgres database can be automatically presented with a GraphQL API service powered by the [OpenReader](https://github.com/subsquid/squid-sdk/tree/master/graphql/openreader) lib of the Squid SDK. The OpenReader GraphQL server takes [the schema file](/sdk/reference/schema-file) as an input and serves a GraphQL API supporting [OpenCRUD](https://www.opencrud.org/) queries for the entities defined in the schema. - -To start the API server based on the `schema.graphql` run in the squid project root: -```bash -npx squid-graphql-server -``` -or, for more options, -```bash -npx squid-graphql-server -``` -The `squid-graphql-server` binary supports multiple optional flags to enable caching, subscriptions, DoS protection etc. Its features are covered in the next sections. - -The API server listens at port defined by `GQL_PORT` (defaults to `4350`). The database connection is configured with the env variables `DB_NAME`, `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`. - -The GraphQL API is enabled by the `api:` service in the `deploy` section of [squid.yaml](/cloud/reference/manifest) for Subsquid Cloud deployments. - -## Supported Queries - -The details of the supported OpenReader queries can be found in a separate section [Query a Squid](/sdk/reference/openreader). Here is a brief overview of the queries generated by OpenReader for each entity defined in the schema file: - -- the squid last processed block is available with `squidStatus { height }` query -- a "get one by ID" query with the name `{entityName}ById` for each [entity](/sdk/reference/schema-file/entities) defined in the schema file -- a "get one" query for [`@unique` fields](/sdk/reference/schema-file/indexes-and-constraints), with the name `{entityName}ByUniqueInput` -- Entity queries named `{entityName}sConnection`. Each query supports rich filtering support, including [field-level filters](/sdk/reference/openreader/queries), composite [`AND` and `OR` filters](/sdk/reference/openreader/and-or-filters), [nested queries](/sdk/reference/openreader/nested-field-queries), [cross-relation queries](/sdk/reference/openreader/cross-relation-field-queries) and [Relay-compatible](https://relay.dev/graphql/connections.htm) cursor-based [pagination](/sdk/reference/openreader/paginate-query-results). -- [Subsriptions](/sdk/resources/graphql-server/subscriptions) via live queries -- (Deprecated in favor of Relay connections) Lookup queries with the name `{entityName}s`. - -[Union and typed JSON types](/sdk/reference/schema-file/unions-and-typed-json) are mapped into [GraphQL Union Types](https://graphql.org/learn/schema/#union-types) with a [proper type resolution](/sdk/reference/openreader/resolve-union-types-interfaces) with `__typename`. - -## Built-in custom scalar types - -The OpenReader GraphQL API defines the following custom scalar types: - -- `DateTime` entity field values are presented in the ISO format -- `Bytes` entity field values are presented as hex-encoded strings prefixed with `0x` -- `BigInt` entity field values are presented as strings diff --git a/docs/sdk/resources/migrate/migrate-subgraph.md b/docs/sdk/resources/migrate/migrate-subgraph.md index fb1b818b..67d80ca2 100644 --- a/docs/sdk/resources/migrate/migrate-subgraph.md +++ b/docs/sdk/resources/migrate/migrate-subgraph.md @@ -14,7 +14,7 @@ git clone https://github.com/subsquid-labs/gravatar-squid.git `EvmBatchProcessor` provided by the Squid SDK defines a single handler that indexes EVM logs and transaction data in batches. It differs from the programming model of subgraph mappings that defines a separate data handler for each EVM log topic to be indexed. Due to significantly less frequent database hits (once per batch compared to once per log) the batch-based handling model shows up to a 10x increase in the indexing speed. -At the same time, concepts of the [schema file](/sdk/reference/schema-file), [code generation from the schema file](/sdk/reference/schema-file/intro/#typeorm-codegen) and [auto-generated GraphQL API](/sdk/resources/graphql-server) should be familiar to subgraph developers. In most cases the schema file of a subgraph can be imported into a squid as is. +At the same time, concepts of the [schema file](/sdk/reference/schema-file), [code generation from the schema file](/sdk/reference/schema-file/intro/#typeorm-codegen) and [auto-generated GraphQL API](/sdk/resources/basics/serving-graphql) should be familiar to subgraph developers. In most cases the schema file of a subgraph can be imported into a squid as is. There are some known limitations: - Many-to-Many entity relations should be [modeled explicitly](/sdk/reference/schema-file/entity-relations/#many-to-many-relations) as two many-to-one relations @@ -24,10 +24,10 @@ On top of the features provided by subgraphs, Squid SDK and Subsquid Cloud offer - Full control over the target database (Postgres), including custom migrations and ad-hoc queries in the handler - Custom target databases and data formats (e.g. CSV) - Arbitrary code execution in the data handler -- [Extension of the GraphQL API](/sdk/resources/graphql-server/custom-resolvers) with arbitrary SQL +- [Extension of the GraphQL API](/sdk/reference/graphql-server/configuration/custom-resolvers) with arbitrary SQL - [Secret environment variables](/cloud/resources/env-variables), allowing to seamlessly use private third-party JSON-RPC endpoints and integrate with external APIs - [API versioning and aliasing](/cloud/resources/production-alias) -- [API caching](/sdk/resources/graphql-server/caching) +- [API caching](/sdk/reference/graphql-server/configuration/caching) For a full feature set comparison, see [Subsquid vs The Graph](/sdk/subsquid-vs-thegraph). diff --git a/docs/sdk/troubleshooting.mdx b/docs/sdk/troubleshooting.mdx index c79aa4dc..20f0494d 100644 --- a/docs/sdk/troubleshooting.mdx +++ b/docs/sdk/troubleshooting.mdx @@ -69,13 +69,13 @@ PostgreSQL doesn't support storing `NULL (\0x00)` characters in text fields. Usu API queries are too slow - Make sure all the necessary fields are [indexed](/sdk/reference/schema-file/indexes-and-constraints/) -- Annotate the schema and [set reasonable limits](/sdk/resources/graphql-server/dos-protection/) for the incoming queries to protect against DoS attacks +- Annotate the schema and [set reasonable limits](/sdk/reference/graphql-server/configuration/dos-protection/) for the incoming queries to protect against DoS attacks
`response might exceed the size limit` -Make sure the input query has limits set or the entities are decorated with `@cardinality`. We recommend using `XXXConnection` queries for pagination. For configuring limits and max response sizes, see [DoS protection](/sdk/resources/graphql-server/dos-protection/). +Make sure the input query has limits set or the entities are decorated with `@cardinality`. We recommend using `XXXConnection` queries for pagination. For configuring limits and max response sizes, see [DoS protection](/sdk/reference/graphql-server/configuration/dos-protection/).
diff --git a/redirectRules.js b/redirectRules.js index 4ca83c04..cfd28ad1 100644 --- a/redirectRules.js +++ b/redirectRules.js @@ -25,7 +25,7 @@ const urlList = [ }, { "from": "/develop-a-squid/graphql-api", - "to": "/sdk/resources/graphql-server" + "to": "/sdk/resources/basics/serving-graphql" }, { "from": "/develop-a-squid/typegen/squid-substrate-typegen", @@ -409,31 +409,31 @@ const urlList = [ }, { "from": "/graphql-api/authorization", - "to": "/sdk/resources/graphql-server/authorization" + "to": "/sdk/reference/graphql-server/configuration/authorization" }, { "from": "/graphql-api/caching", - "to": "/sdk/resources/graphql-server/caching" + "to": "/sdk/reference/graphql-server/configuration/caching" }, { "from": "/graphql-api/custom-resolvers", - "to": "/sdk/resources/graphql-server/custom-resolvers" + "to": "/sdk/reference/graphql-server/configuration/custom-resolvers" }, { "from": "/graphql-api/dos-protection", - "to": "/sdk/resources/graphql-server/dos-protection" + "to": "/sdk/reference/graphql-server/configuration/dos-protection" }, { "from": "/graphql-api/overview", - "to": "/sdk/resources/graphql-server/overview" + "to": "/sdk/resources/basics/serving-graphql" }, { "from": "/graphql-api/subscriptions", - "to": "/sdk/resources/graphql-server/subscriptions" + "to": "/sdk/reference/graphql-server/configuration/subscriptions" }, { "from": "/graphql-api", - "to": "/sdk/resources/graphql-server" + "to": "/sdk/resources/basics/serving-graphql" }, { "from": "/migrate/subsquid-vs-thegraph", @@ -457,43 +457,43 @@ const urlList = [ }, { "from": "/query-squid/nested-field-queries", - "to": "/sdk/reference/openreader/nested-field-queries" + "to": "/sdk/reference/graphql-server/openreader/nested-field-queries" }, { "from": "/query-squid/sorting", - "to": "/sdk/reference/openreader/sorting" + "to": "/sdk/reference/graphql-server/openreader/sorting" }, { "from": "/query-squid/intro", - "to": "/sdk/reference/openreader/intro" + "to": "/sdk/reference/graphql-server/openreader/intro" }, { "from": "/query-squid/and-or-filters", - "to": "/sdk/reference/openreader/and-or-filters" + "to": "/sdk/reference/graphql-server/openreader/and-or-filters" }, { "from": "/query-squid/resolve-union-types-interfaces", - "to": "/sdk/reference/openreader/resolve-union-types-interfaces" + "to": "/sdk/reference/graphql-server/openreader/resolve-union-types-interfaces" }, { "from": "/query-squid/cross-relation-field-queries", - "to": "/sdk/reference/openreader/cross-relation-field-queries" + "to": "/sdk/reference/graphql-server/openreader/cross-relation-field-queries" }, { "from": "/query-squid/json-queries", - "to": "/sdk/reference/openreader/json-queries" + "to": "/sdk/reference/graphql-server/openreader/json-queries" }, { "from": "/query-squid/queries", - "to": "/sdk/reference/openreader/queries" + "to": "/sdk/reference/graphql-server/openreader/queries" }, { "from": "/query-squid/paginate-query-results", - "to": "/sdk/reference/openreader/paginate-query-results" + "to": "/sdk/reference/graphql-server/openreader/paginate-query-results" }, { "from": "/query-squid", - "to": "/sdk/reference/openreader" + "to": "/sdk/reference/graphql-server/openreader" }, { "from": "/quickstart/quickstart-substrate", @@ -746,6 +746,78 @@ const urlList = [ { "from": "/subsquid-network/public", "to": "/subsquid-network/faq" + }, + { + "from": "/sdk/resources/graphql-server/alternatives", + "to": "/sdk/resources/basics/serving-graphql" + }, + { + "from": "/sdk/resources/graphql-server/overview", + "to": "/sdk/resources/basics/serving-graphql" + }, + { + "from": "/sdk/resources/graphql-server", + "to": "/sdk/resources/basics/serving-graphql" + }, + { + "from": "/sdk/resources/graphql-server/authorization", + "to": "/sdk/reference/graphql-server/configuration/authorization" + }, + { + "from": "/sdk/resources/graphql-server/caching", + "to": "/sdk/reference/graphql-server/configuration/caching" + }, + { + "from": "/sdk/resources/graphql-server/custom-resolvers", + "to": "/sdk/reference/graphql-server/configuration/custom-resolvers" + }, + { + "from": "/sdk/resources/graphql-server/dos-protection", + "to": "/sdk/reference/graphql-server/configuration/dos-protection" + }, + { + "from": "/sdk/resources/graphql-server/subscriptions", + "to": "/sdk/reference/graphql-server/configuration/subscriptions" + }, + { + "from": "/sdk/reference/openreader", + "to": "/sdk/reference/graphql-server/openreader" + }, + { + "from": "/sdk/reference/openreader/intro", + "to": "/sdk/reference/graphql-server/openreader/intro" + }, + { + "from": "/sdk/reference/openreader/and-or-filters", + "to": "/sdk/reference/graphql-server/openreader/and-or-filters" + }, + { + "from": "/sdk/reference/openreader/cross-relation-field-queries", + "to": "/sdk/reference/graphql-server/openreader/cross-relation-field-queries" + }, + { + "from": "/sdk/reference/openreader/json-queries", + "to": "/sdk/reference/graphql-server/openreader/json-queries" + }, + { + "from": "/sdk/reference/openreader/nested-field-queries", + "to": "/sdk/reference/graphql-server/openreader/nested-field-queries" + }, + { + "from": "/sdk/reference/openreader/paginate-query-results", + "to": "/sdk/reference/graphql-server/openreader/paginate-query-results" + }, + { + "from": "/sdk/reference/openreader/queries", + "to": "/sdk/reference/graphql-server/openreader/queries" + }, + { + "from": "/sdk/reference/openreader/resolve-union-types-interfaces", + "to": "/sdk/reference/graphql-server/openreader/resolve-union-types-interfaces" + }, + { + "from": "/sdk/reference/openreader/sorting", + "to": "/sdk/reference/graphql-server/openreader/sorting" } ]