The Graph Client Tools

You can create a single unified GraphQL layer from multiple Subgraphs by adding multiple sources to your .graphclientrc.yml. The client will stitch these schemas together.

sources:
  - name: uniswapv2
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
  - name: compoundv2
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/graphprotocol/compound-v2

You can then run a single query that accesses fields from both sources.

The Graph Client supports built-in transforms like Block Tracking and Auto Pagination. Additionally, you can leverage GraphQL Mesh transforms in your project.

To use a specific GraphQL Mesh transform, you must install its corresponding dependency. For example, if you want to use the prefix transform, you need to install @graphql-mesh/transform-prefix as a development dependency.

When defining a subgraph as a source, you can specify how the client interacts with its underlying indexers or hosted services using different querying strategies. The client provides built-in strategies and interfaces for custom ones:

• RaceStrategy: Sends the query to multiple sources and uses the result from the first one to respond (racing them).
• FallbackStrategy: Attempts to query the first source; if it returns an error, it falls back to the next available source.
• RetryStrategy: If a query to a source fails, the client automatically retries the operation.
• HighestValueStrategy: Queries multiple sources and selects the result based on a specific metric, such as max(_meta.block_number), to ensure the most up-to-date data is used.

Subgraph Composition allows you to merge multiple subgraphs into a single unified schema on the client-side. This is achieved using graphql-tools to create a remote schema or Executor.

Developers can compose schemas using:

• Raw graphql-tools transformers.
• The GraphQL-Mesh declarative API for composing schemas from multiple subgraph GraphQL schemas.

The @graphprotocol/client-auto-pagination transformer allows you to bypass the 1000-record limit imposed by graph-node queries. It enables running queries with any limit by automatically breaking the request into multiple concurrent requests using first: and after: filters, then merging the responses into a single result.

This package is installed automatically when using the graph-client CLI package.

The Graph Client is designed to be agnostic and can be used in two primary modes:

1. Standalone mode: The client runs directly in the Browser or Node.js environment, acting as the orchestrator that plans queries and executes them against multiple subgraphs.
2. With any GraphQL client: The client can be integrated into existing workflows using libraries like Apollo or Urql. It uses a Compatibility Layer (e.g., an Apollo Link or Urql Exchange) to intercept requests and pass them to the Graph-Client orchestrator/query planner.

The Graph Client can provide a smooth developer experience for real-time data by implementing a "subscription-as-query" mechanism.

Instead of relying on native subgraph subscription support (which may be limited), the client allows developers to write standard GraphQL subscription queries. Under the hood, the client executes these as GraphQL query operations. To trigger updates, the client can connect to external hooks or probes (such as watching for Smart Contract events) to re-run the query, effectively bridging the gap between standard queries and real-time requirements.

To explore the composed schema and test queries visually, you can run the Graph Client DevTools using the following command within the example directory.

$ yarn graphiql

Run the CLI to generate the .graphclient directory containing the unified schema and the execute function. Note that you should prefix the command with yarn or add it to your package.json scripts.

graphclient build

To run the transforms example, you must first install dependencies and build the project from the root of the monorepo, then navigate to the example directory to start it.

Follow these steps:

1. Install dependencies in the monorepo root.
2. Build the project.
3. Navigate to examples/transforms/.
4. Run the start command.

# In the root directory
$ yarn install
$ yarn build
$ cd examples/transforms/
$ yarn start