The Query object
Query information and data.
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 this object with supported data types or values. You can write JavaScript almost anywhere in Retool to manipulate or read property values.
allowedGroupIds
A list of allowed group IDs.
| Type | array | ||||
| Array values | string | ||||
| Mutability |
| ||||
| Default | |
Examples
["12345678-1234-1234-1234-123456789012"]
allowedGroups
A list of allowed groups.
| Type | array | ||||
| Array values | string | ||||
| Mutability |
| ||||
| Default | |
Examples
["admin", "viewer"]
cacheKeyTtl
The duration, in seconds, to cache query results.
| Type | number | ||||
| Format | Integer | ||||
| Mutability |
|
Examples
3600
changeset
Edited values for each row.
| Type | array |
| Format | Custom data |
| Array values | object |
| Mutability | Read-only |
changesetIsObject
Whether the changeset is an object.
| Type | boolean |
| Format | True/False |
| Mutability | Read-only |
| Default | |
Examples
true
changesetObject
A list of rows, by key or data index, with edited values. Keys correspond to either the primary key when the table is configured with a Primary key column or the data index of the changed row.
| Type | object |
| Format | Custom data |
| Mutability | Read-only |
Examples
{"row1": {"column1": "value1", "column2": "value2"}, "row2": {"column1": "value3", "column2": "value4"}}
confirmationMessage
The message to display in the confirmation modal before running the query. Available if requireConfirmation is true and Run behavior is set to Manual.
| Type | string | ||||
| Format | Markdown | ||||
| Mutability |
|
Examples
"Are you sure you want to delete **{{ table1.selectedRow.product_id }}**?"
enableCaching
Whether to cache query results.
| Type | boolean | ||||
| Format | True/False | ||||
| Mutability |
|
Examples
true
enableErrorTransformer
Whether to enable the error transformer.
| Type | boolean |
| Format | True/False |
| Mutability | Read-only |
Examples
true
enableTransformer
Whether the query is transforming results.
| Type | boolean | ||||
| Format | True/False | ||||
| Mutability |
| ||||
| Default | |
Examples
true
error
The error message if the action was unsuccessful.
| Type | string |
| Format | Plain Text |
| Mutability | Read-only |
Examples
"Error: Something went wrong"
events
A list of configured event handlers that trigger actions or queries.
| Type | array | ||||
| Array values | object | ||||
| Mutability |
|
Array Object Properties
method
The JavaScript method to perform when type is datasource, widget, state, or localStorage.
| Type | string | ||||
| Mutability |
|
type
The type of action to perform.
| Type | string | ||||||||||||||
| Mutability |
| ||||||||||||||
| Allowed Values |
|
finished
The timestamp for the most recent query run.
| Type | number |
| Format | Timestamp |
| Mutability | Read-only |
Examples
1617024000000
importedQueryInputs
The inputs for imported queries.
| Type | object |
| Format | object |
| Mutability | Read-only |
| Default | |
Examples
[{"date_min": "2024-01-01", "range_in_days": 7}]
Examples
true
isImported
Whether the query was imported from the Query Library.
| Type | boolean |
| Format | True/False |
| Mutability | Read-only |
Examples
true
lastReceivedFromResourceAt
The 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.
| Type | number |
| Format | Timestamp |
| Mutability | Read-only |
Examples
1634025600000
Array Object Properties
Object Properties
Examples
public, immutable, max-age=31556926
Examples
"keep-alive"
content-encoding
The content encoding of the response.
| Type | array |
| Array values | string |
| Mutability | Read-only |
Examples
["gzip"]
Examples
"1234"
Examples
["application/json"]
Examples
"Wed, 01 Jan 2023 00:00:00 GMT"
Examples
"nginx/1.18.0"
Object Properties
Examples
{"key": "value"}
Object Properties
Object Properties
Examples
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
X-Retool-Forwarded-For
The IP address of the user who made the request.
| Type | string |
| Format | IPv4 Address |
| Mutability | Read-only |
Examples
"12345"
Examples
"00-1234567890abcdef1234567890abcdef-1234567890abcdef-01"
Examples
"congo=t61rcWkgMzE"
Examples
{"Content-Type": "application/json"}
Examples
GET
POST
Examples
https://api.example.com/v1/api/get_user
Examples
200
Examples
OK
notificationDuration
The duration that a notification should remain visible, in seconds.
| Type | number |
| Format | Float |
| Mutability | Read-only |
Examples
4.5
overrideOrgCacheForUserCache
Whether to override the organization cache for the user cache.
| Type | boolean |
| Format | True/False |
| Mutability | Read-only |
Examples
true
Examples
123e4567-e89b-12d3-a456-426614174000
privateParams
A list of parameters to exclude from audit logs.
| Type | object | ||||
| Mutability |
|
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.
| Type | string |
| Format | Plain Text |
| Mutability | Read-only |
Examples
SELECT * FROM users
https://api.example.com/v1/users
queryDisabled
Whether to disable the query.
| Type | boolean | ||||
| Format | True/False | ||||
| Mutability |
| ||||
| Default | |
Examples
true
queryDisabledMessage
The message to display if queryDisabled is true.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
This query is disabled.
queryFailureConditions
A set of conditions which determine if the query has failed.
| Type | object | ||||
| Mutability |
|
Object Properties
message
The notification message to display if the query fails based on this condition.
| Type | string |
| Mutability | Read-only |
queryRefreshTime
The interval, in milliseconds, in which the query refreshes automatically.
| Type | number |
| Mutability | Read-only |
queryRunOnSelectorUpdate
Whether the query runs when watched parameters change.
| Type | string | ||||
| Mutability |
|
queryRunTime
The duration, in milliseconds, of the most recent query run.
| Type | number |
| Mutability | Read-only |
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.
| Type | number |
| Mutability | Read-only |
queryTriggerDelay
The duration, in milliseconds, to wait after being triggered before running.
| Type | number |
| Format | Integer |
| Mutability | Read-only |
| Default | |
Examples
1000
requestSentTimestamp
The timestamp the query request was sent.
| Type | number |
| Format | Timestamp |
| Mutability | Read-only |
Examples
1617024000000
requireConfirmation
Whether to require confirmation.
| Type | boolean | ||||
| Format | True/False | ||||
| Mutability |
|
Examples
true
runWhenModelUpdates
Whether to automatically run the query when its parameters change.
| Type | boolean |
| Mutability | Read-only |
runWhenPageLoads
Whether to automatically run the query when the app loads.
| Type | boolean | ||||
| Mutability |
|
runWhenPageLoadsDelay
The duration, in milliseconds, to delay running the query on page load.
| Type | number | ||||
| Mutability |
|
servedFromCache
Whether the most recent query results were returned from the cache.
| Type | boolean |
| Mutability | Read-only |
showFailureToaster
Whether to show a notification on query failure.
| Type | boolean | ||||
| Mutability |
|
showLatestVersionUpdatedWarning
Whether to show a warning if the latest version has been updated.
| Type | boolean |
| Format | True/False |
| Mutability | Read-only |
Examples
true
showSuccessToaster
Whether to show a notification on query success.
| Type | boolean | ||||
| Mutability |
|
showUpdateSetValueDynamicallyToggle
Whether to show the update set value dynamically toggle.
| Type | boolean |
| Format | True/False |
| Mutability | Read-only |
Examples
true
streamResponse
Whether to stream the response.
| Type | boolean | ||||
| Format | True/False | ||||
| Mutability |
|
Examples
true
successMessage
The notification message to display on query success.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
Query succeeded!
timestamp
The timestamp at which the query started to run.
| Type | number |
| Format | Timestamp |
| Mutability | Read-only |
Examples
1617024000000
updateSetValueDynamically
Whether to sync references from the query with the rest of the app.
| Type | boolean |
| Mutability | Read-only |
watchedParams
A list of watched parameters.
| Type | array | ||||
| Array values | string | ||||
| Mutability |
|
Examples
123e4567-e89b-12d3-a456-426614174000
Methods
JavaScript API methods for this object. You can write JavaScript almost anywhere in Retool and use methods to manipulate data and property values.
query.invalidateCache()
Clear cached query data. The query retrieves results from the resource when next run.
query.invalidateCache()
Examples
Clear the cache for query.
query.invalidateCache();
query.queryReset()
Examples
Reset query.
query.queryReset();
await query.trigger(options)
Parameters
Object Properties
Examples
{"key1": "value1", "key2": "value2"}
Examples
function (error) {console.log(error); }
Examples
function (data) {runQuery(i + 1);}
Returns
Examples
Trigger getUsers.
getUsers.trigger({
additionalScope: { i: i },
onFailure: {
function(error) {
console.log(error);
},
onSuccess: {
function(data) {
runQuery(i + 1);
},
},
},
});
Events
Events triggered by user interactions. You can configure event handlers in the IDE to trigger queries or other actions in response to events.
| Event | Description |
|---|---|
| Failure | A query or action has failed. |
| Success | A query or action is successfully completed. |