Configure query run behavior
Learn how configure the run behavior of app queries.
Web or mobile app queries can run either automatically or manually, and include additional run behavior options. These features depend on whether a query is only reading data or making changes.
| Run behavior | Actions | Description |
|---|---|---|
| Automatic | SQL mode and GET requests | The query runs on page load or whenever a referenced value changes, such as a component value. |
| Manual | GUI mode and all other API requests | The query runs only when triggered by an event. |
Use the Run behavior settings in the code editor to view and switch between the available options.
Run a query automatically
SQL mode queries for databases or GET requests for APIs can run automatically. If enabled, the query runs whenever the page loads or a referenced value changes, such as a component value. This is best suited for smaller datasets or when an app needs to reflect changes immediately.
Click Run behavior > Automatic to configure a query to run automatically.
Run a query manually
GUI mode SQL queries or any other type of API request (POST, PUT, etc.) can only run manually. The query must be triggered for it to run. You can trigger queries using an event handler, such as a button click, or with JavaScript code using the query.trigger() method.
You can also configure automatic queries that only read data to run manually. Retool recommends switching to manual run behavior whenever querying a large dataset. Frequent runs of these types of queries can potentially result in rate limits or app performance issues.
Click Run behavior > Manual to configure a query to run manually.
Additional run behavior options
In addition to running queries automatically or manually, you can configure additional options in the Advanced tab. Available options depend on the query's run behavior.
Run a query on page load
Whenever a user launches an app, automatic queries run once the page loads. You can also configure this behavior for manual queries. To configure this option, navigate to the Advanced tab and enable the Run this query on page load? setting.
You can also configure the Page load delay option for queries that run on on page load. This delays the query from running until the specified time, in milliseconds, has passed since the page loaded. For example, a delay of 5000 would result in a query waiting 5 seconds after a user launches the app before running.
Running a query on page load prevents users from triggering the query. If a query is not correctly configured, it could result in erroneous changes or deletion of data.
Run a query periodically
You can configure queries to run at a regular interval. This can be useful for keeping app data current without needing users to perform any action.
Enable Run this query periodically and specify the interval, in milliseconds, at which the query runs again.
Run a query when certain values change
Both automatic and manual queries can be triggered whenever a specified value changes, such as an input field or another query. This is similar to configuring a Change event handler.
Select the values for which the query should monitor in the Watched inputs field, such as {{ textInput1.value }} or {{ query1.data }}.
Require confirmation before running
You can use Markdown formatting in query confirmation messages.
To prevent users making accidental changes when a query runs, you can include a confirmation modal with a custom message. Users can then either confirm the query should run or cancel.
Enable Show a confirmation before running, then provide a confirmation message.
Prevent queries from running
In more complex apps with many queries, you can prevent queries from running if they are not immediately needed. For example, a query should only run if a user selects an option in a Select component.
To prevent a query from running, specify a truthy statement or value in the Disable query field. For example,
{{ !select1.value }}evaluates as true if the component has no current value.{{ password.value.length < 12 }}evaluates as true if the input value for the component is less than 12 characters in length.
