Using Persisted Operations with Federated GraphQL
Learn how to leverage Persisted Operations / Persisted Queries / Trusted Documents with Cosmo & Cosmo Router
Last updated
Was this helpful?
Learn how to leverage Persisted Operations / Persisted Queries / Trusted Documents with Cosmo & Cosmo Router
Last updated
Was this helpful?
Persisted Operations, also known as Trusted Documents or Persisted Queries, allow you to register GraphQL Operations on the Router. This way, you can execute an operation by its identifier instead of sending the whole operation to the router on each query, reducing bandwidth requirements and increasing security. This is also known as Operation Safelisting.
Follow the From Zero to Federation in 5 Steps using Cosmo tutorial to set up your demo subgraphs, install the required tools, and create a Cosmo account.
Let's start by writing an operation in our playground. The easiest way to open it is to use Cosmo Studio. Navigate to your federated graph's Playground
by clicking its link in the sidebar.
Now type and execute the following operation:
The router will return a list of IDs for every employee in the subgraph.
To get ourselves familiar with curl
, let's also execute this operation using the command line:
Now let's turn this query into a persisted operation. To register persisted operations, we will use wgc
, which we installed in the prerequisites step. Open a text editor and create a file named employees.graphql
with the operation body that we previously used:
To register the operation, run:
There are a few things to note from this command:
The first argument is the federated graph name to push the operations to. This is the federated graph we created while following From Zero to Federation in 5 Steps using Cosmo, named federation
.
After the federated subgraph name, we must also indicate a client name. Persisted operations in Cosmo are always associated with a given client. If needed, Cosmo will automatically register the given client name the first time it sees it. During operation execution, the client name is obtained from the graphql-client-name
HTTP header.
Finally, we specify one or more files that contain GraphQL operations. Here we're using a plain .graphql
file, but other formats are also supported, including:
Now run the command and notice its output. It will show how many operations were pushed, along with their status (created or up to date) and their identifiers.
Write down the ID of the operation, which might be different than the one in the example, because we will use it later.
Now that we've pushed an operation, let's execute it. To make things simple, we'll use curl
to run the operation. So, instead of sending the operation contents, we will send its identifier. Run the following command, indicating the client name (in the graphql-client-name
header) and the operation identifier (in the payload):
This will return the same data as executing the operation by returning its contents.
Check the router documentation for Persisted Operations.
Check the documentation for Push command.