Persisted queries in GraphQL - Step-by-Step Execution

Concept Flow - Persisted queries

Client prepares query

↓

Check if query is persisted?

Yes→Send query ID only

↓

Server looks up query

↓

Send full query to server

↓

Execute stored query

↓

Server stores query

↓

Return result

↓

Execute query

↓

Client receives data

Client sends queries; if query is new, server stores it and executes; later client sends only query ID for faster execution.

Execution Sample

GraphQL

mutation PersistQuery {
  persistQuery(query: "{ user { id name } }") {
    id
  }
}

query GetUser {
  user {
    id
    name
  }
}

First, client sends a mutation to store the query and get an ID; later client sends query ID to fetch user data.

Execution Table

Step	Action	Input	Server Behavior	Output
1	Client sends persistQuery mutation	{ user { id name } }	Stores query, generates ID 'abc123'	{ id: "abc123" }
2	Client sends query with ID 'abc123'	ID: 'abc123'	Looks up stored query by ID	Executes query and returns user data
3	Server returns user data	N/A	N/A	{ user: { id: "1", name: "Alice" } }
4	Client receives data	N/A	N/A	User data displayed

💡 Execution stops after client receives the requested data.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
query	null	{ user { id name } }	ID 'abc123'	Stored query fetched	Executed query result
queryID	null	'abc123'	'abc123'	'abc123'	'abc123'
response	null	{ id: "abc123" }	User data	User data	User data

Key Moments - 2 Insights

Why does the client send only the query ID after the first time?

Because the server has stored the full query linked to that ID (see execution_table step 2), so sending only the ID saves bandwidth and speeds up the request.

What happens if the client sends a query ID that the server does not recognize?

The server cannot find the stored query and will return an error or ask the client to send the full query again (not shown in this trace but important to know).

Visual Quiz - 3 Questions

Look at the execution_table, what does the server return after storing the query in step 1?

A Error message

B { id: 'abc123' }

C User data

D Empty response

💡 Hint

Check the Output column in step 1 of execution_table.

At which step does the server execute the stored query?

A Step 3

B Step 1

C Step 2

D Step 4

💡 Hint

Look at the Server Behavior and Output columns in steps 2 and 3.

If the client sends a new query instead of an ID, what would happen according to the flow?

A Server executes the new query and stores it

B Server rejects the query

C Server returns cached data

D Client receives an error

💡 Hint

Refer to the concept_flow where new queries are stored and executed.

Concept Snapshot

Persisted queries let clients send a query once to store it on the server.
Later, clients send only the query ID to run the stored query.
This reduces data sent and speeds up requests.
If the server doesn't recognize the ID, it asks for the full query again.
Common in GraphQL to optimize network usage.

Full Transcript

Persisted queries are a way to optimize GraphQL requests. First, the client sends the full query to the server using a special mutation to store it. The server saves the query and returns a unique ID. Later, the client sends only this ID to request data. The server looks up the stored query by ID, executes it, and returns the result. This saves bandwidth and speeds up communication. If the client sends an unknown ID, the server will ask for the full query again. This process helps reduce repeated sending of large queries over the network.