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}ById for each entity defined in the schema file
• a "get one" query for @unique fields, with the name {entityName}ByUniqueInput
• Entity queries named {entityName}sConnection. Each query supports rich filtering support, including field-level filters, composite AND and OR filters, 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:

• 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