The Query object
Query object properties and JavaScript API methods.
Each Query object represents a query within an app, such as an SQL query or transformer. Each instance has a unique name with which to reference (e.g., getUsers.trigger()).
Properties
All properties for query with supported data types or values. You can write JavaScript almost anywhere in Retool to manipulate or read property values.
cacheKeyTtl
The duration, in seconds, to cache query results.
confirmationMessage
The message to display in the confirmation modal before running the query, if query.requireConfirmation is true.
enableCaching
Whether to cache query results.
enableTransformer
Whether the query is transforming results.
error
The message if an error occurred.
Properties
event
The event type.
Values
0
A user changes the value.
1
A user clicks or taps the component.
2
A user submits the value.
3
A user selects the input field.
4
A user deselects the input field.
5
A user scans a barcode.
6
A user opens the component.
7
A user closes the component.
8
A user sets the value to true.
9
A user sets the value to false.
10
A user selects a value.
11
A user clears the value.
12
A user uploads a file.
13
An uploaded file is parsed.
14
A user changes the value of the input field.
change | A user changes the value. |
click | A user clicks or taps the component. |
submit | A user submits the value. |
focus | A user selects the input field. |
blur | A user deselects the input field. |
scan | A user scans a barcode. |
open | A user opens the component. |
close | A user closes the component. |
true | A user sets the value to |
false | A user sets the value to |
select | A user selects a value. |
clear | A user clears the value. |
upload | A user uploads a file. |
parse | An uploaded file is parsed. |
inputValueChange | A user changes the value of the input field. |
method
The JavaScript method to perform when type is datasource, widget, state, or localStorage.
Values
0
Control query.
1
Control component.
2
Run script.
3
Set variable.
4
Set localStorage.
5
Perform utility action (e.g., Open URL or Confetti).
datasource | Control query. |
widget | Control component. |
script | Run script. |
state | Set variable. |
localStorage | Set localStorage. |
util | Perform utility action (e.g., Open URL or Confetti). |
finished
The UNIX timestamp for the most recent query run.
id
The name.
isFetching
Whether data is being fetched.
isImported
Whether the query was imported from the Query Library.
lastReceivedFromResourceAt
The UNIX timestamp for when data was last fetched. If enableCaching is true, the lastReceivedFromResourceAt and cacheKeyTtl properties determine whether to return results from the cache the next time the query runs.
notificationDuration
The duration that a notification should remain visible, in seconds.
pluginType
The plugin type.
privateParams
A list of parameters to exclude from audit logs.
query
The raw query string. For JavaScript and SQL queries, this is the entire query body. For REST API queries, this is the endpoint string.
queryDisabledMessage
The message to display if queryDisabled is true.
queryFailureConditions
A set of conditions which determine if the query has failed.
queryRefreshTime
The frequency, in milliseconds, at which to run if the query is set to run periodically.
queryRunTime
The duration, in milliseconds, of the most recent query run.
queryTimeout
The duration, in milliseconds, to wait before the query times out. After 120 seconds (120000 ms), all queries time out, even if queryTimeout is higher.
queryTriggerDelay
The duration, in milliseconds, to wait after being triggered before running.
rawData
The initial query data before any transformation of results.
requestSentTimestamp
The Unix timestamp the query request was sent.
runWhenModelUpdates
Whether to automatically run the query when its parameters change.
runWhenPageLoads
Whether to automatically run the query when the app loads.
runWhenPageLoadsDelay
The duration, in milliseconds, to delay running the query on page load.
servedFromCache
Whether the most recent query results were returned from the cache.
showFailureToaster
Whether to show a notification on query failure.
showSuccessToaster
Whether to show a notification on query success.
successMessage
The notification message to display on query success.
timestamp
The Unix timestamp at which the query started to run.
transformer
The JavaScript code for transforming results.
updateSetValueDynamically
Whether to sync component references from the query with the rest of the app.
Methods
JavaScript API methods for interacting with query. You can write JavaScript almost anywhere in Retool and use methods to manipulate data and property values.
invalidateCache
Clear cached query data. The query retrieves results from the resource when next run.
query.invalidateCache()
queryReset
Reset query data and clear error messages.
query.queryReset()
trigger
Trigger the query to run.
Events
Events are triggered by user interactions, such as clicking a button or entering a value. Use event handlers to trigger queries or other actions in response to events.
failure
A query or action fails to complete.
success
A query or action is successfully completed.