Queries let your components read or write data from various datasources. Retool supports querying most databases, as well as any API.
Your components then connect to queries via their props - for example, you could set your Table's data to be {{query1.data}}, and the table would then show data from query1. Similarly, you could change the onClick of a Button to trigger a {{resetPassword}} function for example, which could fire an API request.
Overview
Queries that don't mutate data (eg. read-only SQL statements, or GET API requests) are automatically run on page load. Then they populate their .data field, which you can access via queryName.data. Afterwards, when their parameters change (eg. select * from users where id = {{textinput1.value}}), read-only queries are automatically re-run.
Queries that mutate data are only run when you explicitly tell them to. For example, if you have a table of users, and you have a POST request that resets the selected user's password, the POST query won't automatically run when you change rows. Instead, POST and other write requests must be run explicitly, generally via a Button. That way, we won't write data back accidentally.
Tips
Triggering other queries on success
You'll often want to trigger more queries when a query finishes. For example, after you change something in a database table, you probably want to refresh the users query that pulls in all your users. So updateUsername should cause your users query to refresh.
To do that, just add it to "queries to refresh":
Refreshing users after updateEmail succeeds.
When queries run and refresh
Queries that read data (SQL statements + GET API queries) will automatically refresh when their parameters change. For example, the following query will auto-update every time textinput.value changes:
select * from users where customer_id = {{textinput.value}}Queries that write data don't automatically run when their parameters change
Queries that write data (SQL actions with our GUI editor + all other HTTP methods excluding GET) will not automatically refresh when their parameters change. If you want them to change, you can check the "run query when parameters change" checkbox at the bottom of the query.
But you probably don't want that - since if your query pulls in the value from a TextInput, every time you entered a keystroke in the TextInput, the query would get called once. So you would find multiple rows inserted in your database: m, ma, mar, and mary. We suggest adding a button that triggers the POST.
Additional options
Requiring confirmation before running
If you don't want to a query to run automatically (whether because parameters change or because you triggered it), you can require confirmation before running. Before the query is run, a modal will pop up (the message can be dynamic), asking whether you're sure you want to run the query.
Requiring a confirmation message before running the delete user query.
Running queries periodically
Retool also provides the mechanism to periodically run a query in a user specified period. Here is an example of this.
Example of a query refreshing every 5 seconds (5000 milliseconds)
Disabling queries dynamically
On more complex pages with many queries, it is sometimes useful to stop queries from running if they are not immediately needed. For example, if you are using a tabbed container, you might only want a query to run when the user switches the active tab to the second tab. To do this, you could write the following.
Only run a query when the second tab is active.
Hiding parameters from audit logs
All run queries are logged in the audit logs. If you have a sensitive parameter (eg. an API key), you shouldn't log it. Just add the parameter to "drop from audit logs" dropdown.
Blacklisting the value of textinput1.value.
Query throttling
If you find that Retool performance is slow, it might be because your queries are refreshing too frequently (eg. on every keystroke). To solve that, you can throttle query such that it runs less frequently. The default is 750ms.
Query timeout
You can set a timeout for queries if you don't want them to run endlessly. The default timeout is 10000ms.
What's Next
Here's how you read and write from specific resources:
| APIs |
| Reading from SQL |
| Writing to SQL |
| GraphQL |
| Google Sheets |