Overview
The data indexed by a squid into a Postgres database can be automatically presented with a GraphQL API service powered by the OpenReader lib of the Squid SDK. The OpenReader GraphQL server takes the schema file as an input and serves a GraphQL API supporting OpenCRUD queries for the entities defined in the schema.
To start the API server based on the schema.graphql run in the squid project root:
npx squid-graphql-server
or, for more options,
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 for Subsquid Cloud deployments.
Supported Queries
The details of the supported OpenReader queries can be found in a separate section Query a Squid. 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}ByIdfor each entity defined in the schema file - a "get one" query for
@uniquefields, with the name{entityName}ByUniqueInput - Entity queries named
{entityName}sConnection. Each query supports rich filtering support, including field-level filters, compositeANDandORfilters, nested queries, cross-relation queries and Relay-compatible cursor-based pagination. - Subsriptions via live queries
- (Deprecated in favor of Relay connections) Lookup queries with the name
{entityName}s.
Union and typed JSON types are mapped into GraphQL Union Types with a proper type resolution with __typename.
Built-in custom scalar types
The OpenReader GraphQL API defines the following custom scalar types:
DateTimeentity field values are presented in the ISO formatBytesentity field values are presented as hex-encoded strings prefixed with0xBigIntentity field values are presented as strings