Skip to main content

The Query object

Query information and data.

Version: Cloud and 3.179 Edge

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
ControlUsage
Retool UI Code editor
Default
[]
Examples
["12345678-1234-1234-1234-123456789012"]

allowedGroups​

A list of allowed groups.

Type array
Array values string
Mutability
ControlUsage
Retool UI Code editor > Advanced > Access Controls
Default
[]
Examples
["admin", "viewer"]

cacheKeyTtl​

The duration, in seconds, to cache query results.

Type number
Format Integer
Mutability
ControlUsage
Retool UI Code editor
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
false
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
ControlUsage
Retool UI Code editor > Advanced > Query Running Feedback
Examples
"Are you sure you want to delete **{{ table1.selectedRow.product_id }}**?"

data​

The data.

Type array
Format Custom data
Mutability Read-only

enableCaching​

Whether to cache query results.

Type boolean
Format True/False
Mutability
ControlUsage
Retool UI Code editor > Advanced > Cache
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
ControlUsage
Retool UI Code editor
Default
false
Examples
true

error​

The error message if the action was unsuccessful.

Type string
Format Plain Text
Mutability Read-only
Examples
"Error: Something went wrong"

errorTransformer​

The error transformer.

Type string
Mutability Read-only

events​

A list of configured event handlers that trigger actions or queries.

Type array
Array values object
Mutability
ControlUsage
Retool UI Code editor > Interaction
Array Object Properties

event​

(No description available)

Type unknown
Mutability Read-only

method​

The JavaScript method to perform when type is datasource, widget, state, or localStorage.

Type string
Mutability
ControlUsage
Retool UI Inspector > Interaction > Event handlers > Edit event handler

type​

The type of action to perform.

Type string
Mutability
ControlUsage
Retool UI Inspector > Interaction > Event handlers > Edit event handler
Allowed Values
ValueDescription
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 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}]

isFetching​

Whether data is being fetched.

Type boolean
Format True/False
Mutability Read-only
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

metadata​

Relevant metadata for the query.

Type array
Array values object
Mutability Read-only
Array Object Properties

headers​

The headers of the response.

Type object
Mutability Read-only
Object Properties

cache-control​

The cache control of the response.

Type array
Array values string
Mutability Read-only
Examples
public, immutable, max-age=31556926

connection​

The connection of the response.

Type array
Array values string
Mutability Read-only
Examples
"keep-alive"

content-encoding​

The content encoding of the response.

Type array
Array values string
Mutability Read-only
Examples
["gzip"]

content-length​

The content length of the response.

Type array
Array values string
Mutability Read-only
Examples
"1234"

content-type​

The content type of the response.

Type array
Array values string
Mutability Read-only
Examples
["application/json"]

date​

The date of the response.

Type array
Array values string
Mutability Read-only
Examples
"Wed, 01 Jan 2023 00:00:00 GMT"

server​

The server of the response.

Type array
Array values string
Mutability Read-only
Examples
"nginx/1.18.0"

request​

Deatails about the request performed by the qeury.

Type object
Mutability Read-only
Object Properties

body​

The body of the request.

Type string
Mutability Read-only
Examples
{"key": "value"}

headers​

The headers of the request.

Type object
Mutability Read-only
Object Properties

headers​

The headers of the request.

Type object
Mutability Read-only
Object Properties

User-Agent​

The user agent of the request.

Type string
Mutability Read-only
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

ot-baggage-requestId​

The request ID.

Type string
Mutability Read-only
Default
undefined
Examples
"12345"

traceparent​

The trace parent.

Type string
Mutability Read-only
Default
undefined
Examples
"00-1234567890abcdef1234567890abcdef-1234567890abcdef-01"

tracestate​

The trace state.

Type string
Mutability Read-only
Default
undefined
Examples
"congo=t61rcWkgMzE"
Examples
{"Content-Type": "application/json"}

method​

The HTTP method used.

Type string
Mutability Read-only
Examples
GET
POST

url​

The URL of the request.

Type string
Mutability Read-only
Examples
https://api.example.com/v1/api/get_user

status​

The HTTP status code.

Type number
Format Integer
Mutability Read-only
Examples
200

statusText​

The HTTP status text.

Type string
Mutability Read-only
Examples
OK

notificationDuration​

The duration that a notification should remain visible, in seconds.

Type number
Format Float
Mutability Read-only
Examples
4.5

offlineOptimisticResponse​

The optimistic response for offline mode.

Type object
Mutability Read-only

offlineQueryType​

The offline query type.

Type string
Mutability Read-only

offlineUserQueryInputs​

The user query inputs for offline mode.

Type object
Mutability Read-only

overrideOrgCacheForUserCache​

Whether to override the organization cache for the user cache.

Type boolean
Format True/False
Mutability Read-only
Examples
true

playgroundQueryId​

The query ID for the playground.

Type string
Mutability Read-only

playgroundQuerySaveId​

The query save ID for the playground.

Type string
Mutability Read-only

playgroundQueryUuid​

(No description available)

Type unknown
Mutability Read-only

privateParams​

A list of parameters to exclude from audit logs.

Type object
Mutability
ControlUsage
Retool UI Code editor

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
ControlUsage
Retool UI Code editor > Advanced
Default
false
Examples
true

queryDisabledMessage​

The message to display if queryDisabled is true.

Type string
Format Plain Text
Mutability
ControlUsage
Retool UI Code editor
Examples
This query is disabled.

queryFailureConditions​

A set of conditions which determine if the query has failed.

Type object
Mutability
ControlUsage
Retool UI Code editor
Object Properties

condition​

The condition that determines if the query has failed.

Type string
Mutability Read-only

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
ControlUsage
Retool UI Code editor

queryRunTime​

The duration, in milliseconds, of the most recent query run.

Type number
Mutability Read-only

queryThrottleTime​

The query throttle time, in milliseconds.

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
750
Examples
1000

rawData​

The initial data before any transformation of results.

Type object
Mutability Read-only

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
ControlUsage
Retool UI Code editor
Examples
true

resourceNameOverride​

The resource name override.

Type string
Mutability Read-only

resourceTypeOverride​

The resource type override.

Type string
Mutability Read-only

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
ControlUsage
Retool UI Code editor

runWhenPageLoadsDelay​

The duration, in milliseconds, to delay running the query on page load.

Type number
Mutability
ControlUsage
Retool UI Code editor

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
ControlUsage
Retool UI Code editor

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
ControlUsage
Retool UI Code editor

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
ControlUsage
Retool UI Code editor
Examples
true

successMessage​

The notification message to display on query success.

Type string
Format Plain Text
Mutability
ControlUsage
Retool UI Code editor
Examples
Query succeeded!

timestamp​

The timestamp at which the query started to run.

Type number
Format Timestamp
Mutability Read-only
Examples
1617024000000

transformer​

The JavaScript code for transforming results.

Type string
Mutability Read-only

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
ControlUsage
Retool UI Code editor

workflowId​

The UUID of the workflow.

Type unknown
Mutability Read-only

workflowParams​

The workflow parameters.

Type object
Mutability Read-only

workflowRunBodyType​

The workflow run body type.

Type string
Mutability Read-only

workflowRunExecutionType​

The workflow run execution type.

Type string
Mutability Read-only

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.

Definition
query.invalidateCache()

query.queryReset()​

Reset query data and clear error messages.

Definition
query.queryReset()
Examples

Reset query.

query.queryReset();

query.trigger()​

Trigger the query to run.

Definition
await query.trigger(options)
Parameters

options

object

Additional options to use.

Object Properties

additionalScope

object

Data to pass to query.

onFailure

string

Function to call if the query unsuccessfully runs.

onSuccess

string

Function to call after the query successfully runs.

Examples

Trigger getUsers.

getUsers.trigger({ additionalScope: { i: i } });

Events​

Events triggered by user interactions. Use event handlers to trigger queries or other actions in response to events.

success​

A query or action is successfully completed.

failure​

A query or action has failed.