How to Use Data Transformers in Retool

In the Retool editor, click the '+' button in the bottom panel (or press Cmd+K and search 'Add transformer'). Select 'Transformer' from the options. A new transformer named 'transformer1' appears in the Code tab. Click the name to rename it to something descriptive like 'processedUsers' or 'chartData'. Transformers appear in the Code tab alongside JS Queries. They are visually distinct — transformers show a function icon and always have an explicit return value.

Inside the transformer, write JavaScript that references query data and component values using standard Retool references. When you reference query1.data, Retool automatically tracks this as a dependency — the transformer will re-run whenever query1 completes or its data changes. Always end with a return statement. A transformer with no return statement will output undefined as its value.

1// Transformer: processedUsers
2// References: query1.data (auto-tracked as dependency)
3
4const users = query1.data || [];
5
6return users
7  .filter(user => user.is_active)
8  .map(user => ({
9    id: user.id,
10    name: user.first_name + ' ' + user.last_name,
11    email: user.email,
12    department: user.department ?? 'Unassigned',
13    joinYear: new Date(user.created_at).getFullYear()
14  }))
15  .sort((a, b) => a.name.localeCompare(b.name));

The transformer's output is available anywhere in the app as {{ transformer1.value }} (or {{ processedUsers.value }} if you renamed it). Bind a Table component to it by setting the Table's Data source to {{ processedUsers.value }}. Reference it in text components, charts, or other transformers. The .value suffix is always required for transformers — unlike queries which use .data.

1// Table Inspector → General → Data source:
2{{ processedUsers.value }}
3
4// Text component showing count:
5{{ processedUsers.value.length + ' active users' }}
6
7// Chart component data:
8{{ chartDataTransformer.value }}
9
10// Another transformer referencing this one:
11const processed = processedUsers.value;
12return processed.filter(u => u.department === departmentFilter.value);

One of the most powerful uses of standalone transformers is joining data from two queries — something a query-attached transformer cannot do. Reference both queries in the transformer and merge them using JavaScript. Example: join users from query1 with their order counts from query2.

1// Transformer: usersWithOrders
2// Joins query1 (users) with query2 (order counts by user_id)
3
4const users = query1.data || [];
5const orderCounts = query2.data || []; // [{ user_id, order_count }]
6
7// Build a lookup map for O(1) access
8const orderMap = {};
9orderCounts.forEach(item => {
10  orderMap[item.user_id] = item.order_count;
11});
12
13return users.map(user => ({
14  ...user,
15  orderCount: orderMap[user.id] ?? 0,
16  isHighValue: (orderMap[user.id] ?? 0) >= 10
17}));

Transformers are excellent for preparing aggregated data for chart components. Group, sum, or count data from a query and return it in the format your chart expects. Retool's Chart component expects data in a specific shape — transformers let you adapt your query response to that shape.

1// Transformer: salesByMonth
2// Prepares data for a Bar Chart component
3
4const sales = query1.data || [];
5
6// Group by month and sum revenue
7const monthlyTotals = sales.reduce((acc, sale) => {
8  const month = new Date(sale.sale_date).toLocaleDateString('en-US', {
9    year: 'numeric', month: 'short'
10  });
11  acc[month] = (acc[month] || 0) + Number(sale.amount);
12  return acc;
13}, {});
14
15// Convert to chart-ready array
16return Object.entries(monthlyTotals)
17  .map(([month, total]) => ({ month, total }))
18  .sort((a, b) => new Date(a.month) - new Date(b.month));
19
20// Chart series: x = month, y = total

Transformers can reference component values like textInput1.value or selectBox1.value. When those components change, the transformer automatically re-runs. This enables reactive client-side filtering without re-querying the database. This is a good alternative to server-side filtering when your dataset is small enough to load in full.

1// Transformer: filteredByDepartment
2// Re-runs when departmentSelect.value changes
3
4const users = query1.data || [];
5const selectedDept = departmentSelect.value;
6
7if (!selectedDept || selectedDept === 'all') {
8  return users;
9}
10
11return users.filter(user => user.department === selectedDept);

Transformers are read-only and synchronous. They execute in a restricted environment where side effects are not allowed. Specifically: - Cannot call query.trigger() or any query method - Cannot call variable.setValue() or useState() - Cannot use await or Promises - Cannot make fetch() calls or use browser APIs If your logic needs to do any of these, convert it to a JS Query. JS Queries support async/await and can trigger other queries, but they do NOT auto-execute on dependency changes the way transformers do.

1// WRONG — transformer trying to do side effects:
2query2.trigger(); // Error: cannot trigger queries in transformer
3await myState.setValue(result); // Error: cannot set state
4
5// CORRECT — move side effects to a JS Query:
6// In a JS Query named 'processAndSave':
7const processed = await query1.trigger();
8const result = processed.data.map(/* ... */);
9await myState.setValue(result);
10await saveQuery.trigger({ additionalScope: { data: result } });

To debug your transformer, open the State panel (left sidebar → State tab or Cmd+Shift+S). Find your transformer in the list — it shows the current value of transformer1.value. If the value is undefined, check: (1) your transformer has a return statement, (2) the referenced queries have run, and (3) there are no JavaScript errors in the transformer code. You can also click 'Preview' inside the transformer editor to run it immediately and see the output.