···

       
1
       
 
       
<div align="center">

     

       
2
       
-
       
  <img width="540" alt="urql" src="https://raw.githubusercontent.com/FormidableLabs/urql/master/docs/urql-banner.gif" />

     

       
3
       
 
       


     

       
4
       
 
       
  <br />

     

       
5
       
 
       
  <br />

     
···

       
90
       
 
       
Internally, `urql` will create a unique `key` for any operation it starts which is a hash of `query` and

     

       
91
       
 
       
`variables`. The internal "Exchange pipeline" is then responsible for fulfilling the operation.

     

       
92
       
 
       


     

       
93
       
-
       
<img width="606" src="docs/urql-operation-keys.png" alt="Diagram: An Operation key is computed by hashing the combination of the stringified query and the stabily stringified variables. DocumentNodes may either be stringified fully or just by using their operation names. Properties of any variables object need to be stabily sorted." />

     

       
94
       
 
       


     

       
95
       
 
       
The result's error is a [`CombinedError`](https://formidable.com/open-source/urql/docs/api/#combinederror-class), which

     

       
96
       
 
       
normalises GraphQL errors and Network errors by combining them into one wrapping class.

     

       
97
       
 
       


     

       
98
       
-
       
<img width="693" src="docs/urql-combined-error.png" alt="Diagram: A CombinedError has two states. It can either have a property 'networkError', or it can have multiple, rehydrated GraphQL errors on the 'graphQLErrors' property. The message of the CombinedError will always be a summary of the errors it contains." />

     

       
99
       
 
       


     

       
100
       
 
       
[Learn more about `useQuery` in the Getting Started guide](https://formidable.com/open-source/urql/docs/getting-started/#writing-queries)

     

       
101
       
 
       


     
···

       
196
       
 
       
In `urql` all operations are controlled by a central [`Client`](https://formidable.com/open-source/urql/docs/api/#client-class).

     

       
197
       
 
       
This client is responsible for managing GraphQL operations and sending requests.

     

       
198
       
 
       


     

       
199
       
-
       
<img width="787" src="docs/urql-client-architecture.png" alt="Diagram: The Client is an event hub on which operations may be dispatched by hooks. This creates an input stream (displayed as operations A, B, and C). Each Operation Result that then comes back from the client corresponds to one operation that has been sent to the client. This is the output stream of results (displayed as results A, B, and C)" />

     

       
200
       
 
       


     

       
201
       
 
       
Any hook in `urql` dispatches its operation on the client (A, B, C) which will be handled by the client on a

     

       
202
       
 
       
single stream of inputs. As responses come back from the cache or your GraphQL API one or more results are

     

       
203
       
 
       
dispatched on an output stream that correspond to the operations, which update the hooks.

     

       
204
       
 
       


     

       
205
       
-
       
<img width="709" src="docs/urql-event-hub.png" alt="Diagram: The 'useQuery' hook dispatches an operation on the client when it mounts or updates. When it unmounts it dispatches a 'teardown' operation that cancels the original operation. Results that come back from the client update the hook and are filtered by the operation's original key."/>

     

       
206
       
 
       


     

       
207
       
 
       
Hence the client can be seen as an event hub. Operations are sent to the client, which executes them and

     

       
208
       
 
       
sends back a result. A special teardown-event is issued when a hook unmounts or updates to a different

     

       
209
       
 
       
operation.

     

       
210
       
 
       


     

       
211
       
-
       
<img width="700" src="docs/urql-signals.png" alt="Diagram: Operations can be seen as signals. Operations with an 'operationName' of query, mutation, or subscription start a query of the given DocumentNode operation. The same operation with an 'operationName' of 'teardown' instructs the client to stop or cancel an ongoing operation of the same key. Operation Results carry the original operation on an 'operation' property, which means they can be identified by reading the key of this operation."/>

     

       
212
       
 
       


     

       
213
       
 
       
[Learn more about the shape of operations and results in our Architecture section!](https://formidable.com/open-source/urql/docs/architecture/)

     

       
214
       
 
       


     
···

       
223
       
 
       
Instead _Exchanges_ are nested and deal with two streams, the input stream of operations and the output stream of results,

     

       
224
       
 
       
where the stream of operations go through a pipeline like an intersection in an arbitrary order.

     

       
225
       
 
       


     

       
226
       
-
       
<img width="634" src="docs/urql-exchanges.png" alt="Diagram: By default the client has three exchanges. Operations flow through a 'dedup', 'cache', and 'fetch' exchange in this exact order. Their results are flowing backwards through this same chain of exchanges. The 'dedupExchange' deduplicates ongoing operations by their key. The 'cacheExchange' caches results and retrieves them by the operations' keys. The 'fetchExchange' sends operations to a GraphQL API and supports cancellation." />

     

       
227
       
 
       


     

       
228
       
 
       
By default there are three exchanges. The `dedupExchange` deduplicates operations with the same key, the

     

       
229
       
 
       
cache exchange handles caching and has a "document" strategy by default, and the `fetchExchange` is typically

     
···

       
243
       
 
       
These results are aggressively invalidated. Whenever you send a mutation, each result that contains `__typename`s

     

       
244
       
 
       
that also occur in the mutation result is invalidated.

     

       
245
       
 
       


     

       
246
       
-
       
<img width="736" src="docs/urql-document-caching.png" alt="Diagram: First, a query is made that gets a type, in this example a 'Book'. The result contains the '__typename' field that says 'Book'. This is stored in a mapping of all types to the operations that contained this type. Later a mutation may change some data and will have overlapping types, in this example a 'Book' is liked. The mutation also contains a 'Book' so it retrieves the original operation that was getting a 'Book' and reexecutes and invalidates it." />

     

       
247
       
 
       


     

       
248
       
 
       
### Normalized Caching

     

       
249
       
 
       


     
···

       
251
       
 
       
package. The normalized cache is a cache that stores every separate entity in a big graph. Therefore multiple separate queries, subscriptions, and mutations

     

       
252
       
 
       
can update each other, if they contain overlapping data with the same type and ID.

     

       
253
       
 
       


     

       
254
       
-
       
<img width="466" src="docs/urql-normalized-cache.png" alt="Diagram: A normalized cache contains a graph of different nodes. Queries point to different nodes, which point to other nodes, and so on and so forth. Nodes may be reused and are called 'entities'. Each entity corresponds to an object that came back from the API." />

     

       
255
       
 
       


     

       
256
       
 
       
Getting started with Graphcache is easy and is as simple as installing it and adding it to your client.

     

       
257
       
 
       
Afterwards it comes with a lot of ways to configure it so that less requests need to be sent to your API.

     
···

       
373
       
 
       


     

       
374
       
 
       
**Active:** Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.

     

       
375
       
 
       


     

       
376
       
-
       
<img width="100%" src="docs/urql-spoiler.png" />

     

···

       
1
       
 
       
<div align="center">

     

       
2
       
+
       
  <img alt="urql" width="250" src="docs/assets/urql-logo.png" />

     

       
3
       
 
       


     

       
4
       
 
       
  <br />

     

       
5
       
 
       
  <br />

     
···

       
90
       
 
       
Internally, `urql` will create a unique `key` for any operation it starts which is a hash of `query` and

     

       
91
       
 
       
`variables`. The internal "Exchange pipeline" is then responsible for fulfilling the operation.

     

       
92
       
 
       


     

       
93
       
+
       
<img width="606" src="docs/assets/urql-operation-keys.png" alt="Diagram: An Operation key is computed by hashing the combination of the stringified query and the stabily stringified variables. DocumentNodes may either be stringified fully or just by using their operation names. Properties of any variables object need to be stabily sorted." />

     

       
94
       
 
       


     

       
95
       
 
       
The result's error is a [`CombinedError`](https://formidable.com/open-source/urql/docs/api/#combinederror-class), which

     

       
96
       
 
       
normalises GraphQL errors and Network errors by combining them into one wrapping class.

     

       
97
       
 
       


     

       
98
       
+
       
<img width="693" src="docs/assets/urql-combined-error.png" alt="Diagram: A CombinedError has two states. It can either have a property 'networkError', or it can have multiple, rehydrated GraphQL errors on the 'graphQLErrors' property. The message of the CombinedError will always be a summary of the errors it contains." />

     

       
99
       
 
       


     

       
100
       
 
       
[Learn more about `useQuery` in the Getting Started guide](https://formidable.com/open-source/urql/docs/getting-started/#writing-queries)

     

       
101
       
 
       


     
···

       
196
       
 
       
In `urql` all operations are controlled by a central [`Client`](https://formidable.com/open-source/urql/docs/api/#client-class).

     

       
197
       
 
       
This client is responsible for managing GraphQL operations and sending requests.

     

       
198
       
 
       


     

       
199
       
+
       
<img width="787" src="docs/assets/urql-client-architecture.png" alt="Diagram: The Client is an event hub on which operations may be dispatched by hooks. This creates an input stream (displayed as operations A, B, and C). Each Operation Result that then comes back from the client corresponds to one operation that has been sent to the client. This is the output stream of results (displayed as results A, B, and C)" />

     

       
200
       
 
       


     

       
201
       
 
       
Any hook in `urql` dispatches its operation on the client (A, B, C) which will be handled by the client on a

     

       
202
       
 
       
single stream of inputs. As responses come back from the cache or your GraphQL API one or more results are

     

       
203
       
 
       
dispatched on an output stream that correspond to the operations, which update the hooks.

     

       
204
       
 
       


     

       
205
       
+
       
<img width="709" src="docs/assets/urql-event-hub.png" alt="Diagram: The 'useQuery' hook dispatches an operation on the client when it mounts or updates. When it unmounts it dispatches a 'teardown' operation that cancels the original operation. Results that come back from the client update the hook and are filtered by the operation's original key."/>

     

       
206
       
 
       


     

       
207
       
 
       
Hence the client can be seen as an event hub. Operations are sent to the client, which executes them and

     

       
208
       
 
       
sends back a result. A special teardown-event is issued when a hook unmounts or updates to a different

     

       
209
       
 
       
operation.

     

       
210
       
 
       


     

       
211
       
+
       
<img width="700" src="docs/assets/urql-signals.png" alt="Diagram: Operations can be seen as signals. Operations with an 'operationName' of query, mutation, or subscription start a query of the given DocumentNode operation. The same operation with an 'operationName' of 'teardown' instructs the client to stop or cancel an ongoing operation of the same key. Operation Results carry the original operation on an 'operation' property, which means they can be identified by reading the key of this operation."/>

     

       
212
       
 
       


     

       
213
       
 
       
[Learn more about the shape of operations and results in our Architecture section!](https://formidable.com/open-source/urql/docs/architecture/)

     

       
214
       
 
       


     
···

       
223
       
 
       
Instead _Exchanges_ are nested and deal with two streams, the input stream of operations and the output stream of results,

     

       
224
       
 
       
where the stream of operations go through a pipeline like an intersection in an arbitrary order.

     

       
225
       
 
       


     

       
226
       
+
       
<img width="634" src="docs/assets/urql-exchanges.png" alt="Diagram: By default the client has three exchanges. Operations flow through a 'dedup', 'cache', and 'fetch' exchange in this exact order. Their results are flowing backwards through this same chain of exchanges. The 'dedupExchange' deduplicates ongoing operations by their key. The 'cacheExchange' caches results and retrieves them by the operations' keys. The 'fetchExchange' sends operations to a GraphQL API and supports cancellation." />

     

       
227
       
 
       


     

       
228
       
 
       
By default there are three exchanges. The `dedupExchange` deduplicates operations with the same key, the

     

       
229
       
 
       
cache exchange handles caching and has a "document" strategy by default, and the `fetchExchange` is typically

     
···

       
243
       
 
       
These results are aggressively invalidated. Whenever you send a mutation, each result that contains `__typename`s

     

       
244
       
 
       
that also occur in the mutation result is invalidated.

     

       
245
       
 
       


     

       
246
       
+
       
<img width="736" src="docs/assets/urql-document-caching.png" alt="Diagram: First, a query is made that gets a type, in this example a 'Book'. The result contains the '__typename' field that says 'Book'. This is stored in a mapping of all types to the operations that contained this type. Later a mutation may change some data and will have overlapping types, in this example a 'Book' is liked. The mutation also contains a 'Book' so it retrieves the original operation that was getting a 'Book' and reexecutes and invalidates it." />

     

       
247
       
 
       


     

       
248
       
 
       
### Normalized Caching

     

       
249
       
 
       


     
···

       
251
       
 
       
package. The normalized cache is a cache that stores every separate entity in a big graph. Therefore multiple separate queries, subscriptions, and mutations

     

       
252
       
 
       
can update each other, if they contain overlapping data with the same type and ID.

     

       
253
       
 
       


     

       
254
       
+
       
<img width="466" src="docs/assets/urql-normalized-cache.png" alt="Diagram: A normalized cache contains a graph of different nodes. Queries point to different nodes, which point to other nodes, and so on and so forth. Nodes may be reused and are called 'entities'. Each entity corresponds to an object that came back from the API." />

     

       
255
       
 
       


     

       
256
       
 
       
Getting started with Graphcache is easy and is as simple as installing it and adding it to your client.

     

       
257
       
 
       
Afterwards it comes with a lot of ways to configure it so that less requests need to be sent to your API.

     
···

       
373
       
 
       


     

       
374
       
 
       
**Active:** Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.

     

       
375
       
 
       


     

       
376
       
+
       
<img width="100%" src="docs/assets/urql-spoiler.png" />