kitten.sh
1---
2title: Auto-populate Mutations
3order: 9
4---
5
6# Automatically populating Mutations
7
8The `populateExchange` allows you to auto-populate selection sets in your mutations using the
9`@populate` directive. In combination with [Graphcache](../graphcache/README.md) this is a useful
10tool to update the data in your application automatically following a mutation, when your app grows,
11and it becomes harder to track all fields that have been queried before.
12
13> **NOTE:** The `populateExchange` is _experimental_! Certain patterns and usage paths
14> like GraphQL field arguments aren't covered yet, and the exchange hasn't been extensively used
15> yet.
16
17## Installation and Setup
18
19The `populateExchange` can be installed via the `@urql/exchange-populate` package.
20
21```sh
22yarn add @urql/exchange-populate
23# or
24npm install --save @urql/exchange-populate
25```
26
27Afterwards we can set the `populateExchange` up by adding it to our list of `exchanges` in the
28client options.
29
30```ts
31import { Client, fetchExchange } from '@urql/core';
32import { populateExchange } from '@urql/exchange-populate';
33
34const client = new Client({
35 // ...
36 exchanges: [populateExchange({ schema }), cacheExchange, fetchExchange],
37});
38```
39
40The `populateExchange` should be placed in front of the `cacheExchange`, especially if you're using
41[Graphcache](../graphcache/README.md), since it won't understand the `@populate` directive on its
42own. It should also be placed in front the `cacheExchange` to avoid unnecessary work.
43
44Adding the `populateExchange` now enables us to use the `@populate` directive in our mutations.
45
46The `schema` option is the introspection result for your backend graphql schema, more information
47about how to get your schema can be found [in the "Schema Awareness" Page of the Graphcache documentation.](../graphcache/schema-awareness.md#getting-your-schema).
48
49## Example usage
50
51Consider the following queries, which have been requested in other parts of your application:
52
53```graphql
54# Query 1
55{
56 todos {
57 id
58 name
59 }
60}
61
62# Query 2
63{
64 todos {
65 id
66 createdAt
67 }
68}
69```
70
71Without the `populateExchange` you may write a mutation like the following which returns a newly created todo item:
72
73```graphql
74# Without populate
75mutation addTodo(id: ID!) {
76 addTodo(id: $id) {
77 id # To update Query 1 & 2
78 name # To update Query 1
79 createdAt # To update Query 2
80 }
81}
82```
83
84By using `populateExchange`, you no longer need to manually specify the selection set required to update your other queries. Instead you can just add the `@populate` directive.
85
86```graphql
87# With populate
88mutation addTodo(id: ID!) {
89 addTodo(id: $id) @populate
90}
91```
92
93### Choosing when to populate
94
95You may not want to populate your whole mutation response. To reduce your payload, pass populate lower in your query.
96
97```graphql
98mutation addTodo(id: ID!) {
99 addTodo(id: $id) {
100 id
101 user @populate
102 }
103}
104```
105
106### Using aliases
107
108If you find yourself using multiple queries with variables, it may be necessary to
109[use aliases](https://graphql.org/learn/queries/#aliases) to allow merging of queries.
110
111> **Note:** This caveat may change in the future or this restriction may be lifted.
112
113**Invalid usage**
114
115```graphql
116# Query 1
117{
118 todos(first: 10) {
119 id
120 name
121 }
122}
123
124# Query 2
125{
126 todos(last: 20) {
127 id
128 createdAt
129 }
130}
131```
132
133**Usage with aliases**
134
135```graphql
136# Query 1
137{
138 firstTodos: todos(first: 10) {
139 id
140 name
141 }
142}
143
144# Query 2
145{
146 lastTodos: todos(last: 20) {
147 id
148 createdAt
149 }
150}
151```