···

       
1
       
1
       
 
       
<div align="center">

     

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

     

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

     

       
3
       
3
       
 
       


     

       
4
       
4
       
 
       
  <br />

     

       
5
       
5
       
 
       
  <br />

     
···

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

     

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

     

       
92
       
92
       
 
       


     

       
93
       
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." />

     

       
93
       
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
       
94
       
 
       


     

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

     

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

     

       
97
       
97
       
 
       


     

       
98
       
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." />

     

       
98
       
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
       
99
       
 
       


     

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

     

       
101
       
101
       
 
       


     
···

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

     

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

     

       
198
       
198
       
 
       


     

       
199
       
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)" />

     

       
199
       
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
       
200
       
 
       


     

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

     

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

     

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

     

       
204
       
204
       
 
       


     

       
205
       
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."/>

     

       
205
       
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
       
206
       
 
       


     

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

     

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

     

       
209
       
209
       
 
       
operation.

     

       
210
       
210
       
 
       


     

       
211
       
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."/>

     

       
211
       
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
       
212
       
 
       


     

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

     

       
214
       
214
       
 
       


     
···

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

     

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

     

       
225
       
225
       
 
       


     

       
226
       
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." />

     

       
226
       
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
       
227
       
 
       


     

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

     

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

     
···

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

     

       
244
       
244
       
 
       
that also occur in the mutation result is invalidated.

     

       
245
       
245
       
 
       


     

       
246
       
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." />

     

       
246
       
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
       
247
       
 
       


     

       
248
       
248
       
 
       
### Normalized Caching

     

       
249
       
249
       
 
       


     
···

       
251
       
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
       
252
       
 
       
can update each other, if they contain overlapping data with the same type and ID.

     

       
253
       
253
       
 
       


     

       
254
       
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." />

     

       
254
       
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
       
255
       
 
       


     

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

     

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

     
···

       
373
       
373
       
 
       


     

       
374
       
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
       
375
       
 
       


     

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

     

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

     

This is a binary file and will not be displayed.

This is a binary file and will not be displayed.