Resource queries
Learn more about how queries access data.
Resource queries allow you to read and write data from your data sources. Retool supports querying most databases and APIs.
Connect queries to components
You connect query results to components using the query's .data property. For example, to populate a Table component with data from query1, you set the table's Data source to {{ query1.data }}.
For write queries, you can use event handlers to trigger queries from component interactions. For example, to trigger a resetPassword query which sends a POST request, you can set the Click property of a Button component to trigger resetPassword.
Automatic query runs
Queries that don't mutate data (e.g., read-only SQL statements) automatically run on page load, and by default, when their parameters change. For example, the following query runs every time textInput1.value changes:
select customer_id, first_name, last_name from users where customer_id = {{textInput1.value}}
To trigger these queries manually, select Run query only when manually triggered in the query editor.
Manual query runs
By default, queries that mutate data (e.g., POST API requests) are run when explicitly triggered. For example, given a table of users and a POST request that resets the selected user's password, the POST query doesn't automatically run when you select new rows. Instead, these requests must be run explicitly, often triggered from buttons or other components. This prevents Retool from accidentally writing incomplete or incorrect data.
To trigger queries when input data changes, select Run query automatically when inputs change in the query editor.
Use caution when implementing write queries which update when inputs change. For example, if your query runs on changes in a Text Input component, the query triggers for every keystroke. This means for a single string, e.g., mary, rows for m, a, r, and y are written to your data source. To avoid this, add a button to trigger write queries instead.
Prevent query variable spoofing
To prevent a user from manipulating network requests to pass in arbitrary values to prepared statements, query spoofing is enabled by default. Retool rejects network requests that refer to current_user properties (e.g., current_user.email) which don’t match the expected values for the user making the query. If you include additional logic in your expression (e.g., current_user.groups.map(group => group.name)), query spoofing prevention is not available.
Use query results
When a query completes, you may want to trigger follow-up queries, notify users about successful updates or failures, or use query data in components by accessing query.data.
Transform data
If your data returns in a format unsuitable for components or other elements in your app, you can apply changes in Transform results. The return value of this transformation is then used wherever you access query.data.
For example, the following query transformer is used to avoid needing to repeatedly access query2.data.results. Instead, you can access query2.data, and use it directly in the Table component. The formatDataAsArray and formatDataAsObject methods are especially useful in query transformers.
See the transformers documentation to learn more about transformer behavior.
Trigger queries on success or failure
It's common to trigger additional queries or events when a query finishes. For example, after you update a database table, you probably want to refresh the query that pulls in all your data. To do that, add a success event handler to trigger the query that retrieves your table's data.
Response options
By default, queries show notifications in the center of the app screen on any failures. JavaScript queries also show notification messages on success. You can modify the messages, adjust the notification duration, and disable these success or failure notifications from the Response tab of the query editor.