The Query object

Classic apps

You're viewing documentation for classic apps, which use Retool's original app editor. The new app builder is the recommended way to build apps and where Retool focuses new development.

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
Configurability	Code editor > Advanced > Allowed group IDs
Default	`[]`

Examples

false["12345678-1234-1234-1234-123456789012"]

`allowedGroups`

A list of allowed groups.

Type	array
Array values	string
Configurability	Code editor > Advanced > Access Controls > Allowed groups
Default	`[]`

Examples

false["admin", "viewer"]

`cacheKeyTtl`

The duration, in seconds, to cache query results.

Type	number
Format	Integer
Configurability	Code editor
Default	`null`

Examples

false3600

`changeset`

Edited values for each row.

Type	array
Format	Custom data
Array values	object
Configurability	Read-only
Default	`null`

`changesetIsObject`

Whether the changeset is an object.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`false`

Examples

falsetrue

`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
Configurability	Read-only
Default	`null`

Examples

false{"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
Configurability	Code editor > Advanced > Query Running Feedback > Show a confirmation message before running
Default	`null`

Examples

false"Are you sure you want to delete **{{ table1.selectedRow.product_id }}**?"

`data`

The data.

Type	array
Format	Custom data
Configurability	Read-only
Default	`null`

`enableCaching`

Whether to cache query results.

Type	boolean
Format	True/False
Configurability	Code editor > Advanced > Cache > Cache the results of this query
Default	`null`

Examples

falsetrue

`enableErrorTransformer`

Whether to enable the error transformer.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`null`

Examples

falsetrue

`enableTransformer`

Whether the query is transforming results.

Type	boolean
Format	True/False
Configurability	Code editor
Default	`false`

Examples

falsetrue

`error`

The error message if the action was unsuccessful.

Type	string
Format	Plain Text
Configurability	Read-only
Default	`null`

Examples

false"Error: Something went wrong"

`errorTransformer`

The error transformer.

Type	string
Configurability	Read-only
Default	`null`

`events`

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

Type	array
Array values	object
Configurability	Code editor > Interaction > Event handlers
Default	`null`

Array Object Properties

`event`

The event that triggers the action. Refer to the events section for details of available events for this object.

Type	string
Configurability	Inspector > Interaction > Event handlers > Event
Default	`null`

`method`

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

Type	string
Configurability	Inspector > Interaction > Event handlers > Edit event handler > Run script actions
Default	`null`

`type`

The type of action to perform.

Type string

Configurability Inspector > Interaction > Event handlers > Edit event handler > Action

Allowed Values

Value	Description
`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).

Default null

`finished`

The timestamp for the most recent query run.

Type	number
Format	Timestamp
Configurability	Read-only
Default	`null`

Examples

false1617024000000

`importedQueryInputs`

The inputs for imported queries.

Type	object
Format	object
Configurability	Read-only
Default	`{}`

Examples

false[{"date_min": "2024-01-01", "range_in_days": 7}]

`isFetching`

Whether data is being fetched.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`null`

Examples

falsetrue

`isImported`

Whether the query was imported from the Query Library.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`null`

Examples

falsetrue

`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
Configurability	Read-only
Default	`null`

Examples

false1634025600000

`metadata`

Relevant metadata for the query.

Type	array
Array values	object
Configurability	Read-only
Default	`null`

Array Object Properties

`headers`

The headers of the response.

Type	object
Configurability	Read-only
Default	`null`

Object Properties

`cache-control`

The cache control of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

falsepublic, immutable, max-age=31556926

`connection`

The connection of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

false"keep-alive"

`content-encoding`

The content encoding of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

false["gzip"]

`content-length`

The content length of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

false"1234"

`content-type`

The content type of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

false["application/json"]

`date`

The date of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

false"Wed, 01 Jan 2023 00:00:00 GMT"

`server`

The server of the response.

Type	array
Array values	string
Configurability	Read-only
Default	`null`

Examples

false"nginx/1.18.0"

`request`

Deatails about the request performed by the qeury.

Type	object
Configurability	Read-only
Default	`null`

Object Properties

`body`

The body of the request.

Type	string
Configurability	Read-only
Default	`null`

Examples

false{"key": "value"}

`headers`

The headers of the request.

Type	object
Configurability	Read-only
Default	`null`

Object Properties

`headers`

The headers of the request.

Type	object
Configurability	Read-only
Default	`null`

Object Properties

`User-Agent`

The user agent of the request.

Type	string
Configurability	Read-only
Default	`null`

Examples

false"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
Configurability	Read-only
Default	`null`

`ot-baggage-requestId`

The request ID.

Type	string
Configurability	Read-only
Default	`undefined`

Examples

false"12345"

`traceparent`

The trace parent.

Type	string
Configurability	Read-only
Default	`undefined`

Examples

false"00-1234567890abcdef1234567890abcdef-1234567890abcdef-01"

`tracestate`

The trace state.

Type	string
Configurability	Read-only
Default	`undefined`

Examples

false"congo=t61rcWkgMzE"

Examples

false{"Content-Type": "application/json"}

`method`

The HTTP method used.

Type	string
Configurability	Read-only
Default	`null`

Examples

falseGET

falsePOST

`url`

The URL of the request.

Type	string
Configurability	Read-only
Default	`null`

Examples

falsehttps://api.example.com/v1/api/get_user

`status`

The HTTP status code.

Type	number
Format	Integer
Configurability	Read-only
Default	`null`

Examples

false200

`statusText`

The HTTP status text.

Type	string
Configurability	Read-only
Default	`null`

Examples

falseOK

`notificationDuration`

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

Type	number
Format	Float
Configurability	Read-only
Default	`null`

Examples

false4.5

`offlineOptimisticResponse`

The optimistic response for offline mode.

Type	object
Configurability	Read-only
Default	`null`

`offlineQueryType`

The offline query type.

Type	string
Configurability	Read-only
Default	`null`

`offlineUserQueryInputs`

The user query inputs for offline mode.

Type	object
Configurability	Read-only
Default	`null`

`overrideOrgCacheForUserCache`

Whether to override the organization cache for the user cache.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`null`

Examples

falsetrue

`playgroundQueryId`

The query ID for the playground.

Type	string
Configurability	Read-only
Default	`null`

`playgroundQuerySaveId`

The query save ID for the playground.

Type	string
Configurability	Read-only
Default	`null`

`playgroundQueryUuid`

The query UUID for the playground.

Type	string
Format	UUID
Configurability	Read-only
Default	`null`

Examples

false123e4567-e89b-12d3-a456-426614174000

`privateParams`

A list of parameters to exclude from audit logs.

Type	object
Configurability	Code editor
Default	`null`

`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
Configurability	Read-only
Default	`null`

Examples

falseSELECT * FROM users

falsehttps://api.example.com/v1/users

`queryDisabled`

Whether to disable the query.

Type	boolean
Format	True/False
Configurability	Code editor > Advanced > Disabled query
Default	`false`

Examples

falsetrue

`queryDisabledMessage`

The message to display if queryDisabled is true.

Type	string
Format	Plain Text
Configurability	Code editor
Default	`null`

Examples

falseThis query is disabled.

`queryFailureConditions`

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

Type	object
Configurability	Code editor
Default	`null`

Object Properties

`condition`

The condition that determines if the query has failed.

Type	string
Configurability	Read-only
Default	`null`

`message`

The notification message to display if the query fails based on this condition.

Type	string
Configurability	Read-only
Default	`null`

`queryRefreshTime`

The interval, in milliseconds, in which the query refreshes automatically.

Type	number
Configurability	Read-only
Default	`null`

`queryRunOnSelectorUpdate`

Whether the query runs when watched parameters change.

Type	string
Configurability	Code editor
Default	`null`

`queryRunTime`

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

Type	number
Configurability	Read-only
Default	`null`

`queryThrottleTime`

The query throttle time, in milliseconds.

Type	number
Configurability	Read-only
Default	`null`

`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
Configurability	Read-only
Default	`null`

`queryTriggerDelay`

The duration, in milliseconds, to wait after being triggered before running.

Type	number
Format	Integer
Configurability	Read-only
Default	`750`

Examples

false1000

`rawData`

The initial data before any transformation of results.

Type	object
Configurability	Read-only
Default	`null`

`requestSentTimestamp`

The timestamp the query request was sent.

Type	number
Format	Timestamp
Configurability	Read-only
Default	`null`

Examples

false1617024000000

`requireConfirmation`

Whether to require confirmation.

Type	boolean
Format	True/False
Configurability	Code editor
Default	`null`

Examples

falsetrue

`resourceNameOverride`

The resource name override.

Type	string
Configurability	Read-only
Default	`null`

`resourceTypeOverride`

The resource type override.

Type	string
Configurability	Read-only
Default	`null`

`runWhenModelUpdates`

Whether to automatically run the query when its parameters change.

Type	boolean
Configurability	Read-only
Default	`null`

`runWhenPageLoads`

Whether to automatically run the query when the app loads.

Type	boolean
Configurability	Code editor
Default	`null`

`runWhenPageLoadsDelay`

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

Type	number
Configurability	Code editor
Default	`null`

`servedFromCache`

Whether the most recent query results were returned from the cache.

Type	boolean
Configurability	Read-only
Default	`null`

`showFailureToaster`

Whether to show a notification on query failure.

Type	boolean
Configurability	Code editor
Default	`null`

`showLatestVersionUpdatedWarning`

Whether to show a warning if the latest version has been updated.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`null`

Examples

falsetrue

`showSuccessToaster`

Whether to show a notification on query success.

Type	boolean
Configurability	Code editor
Default	`null`

`showUpdateSetValueDynamicallyToggle`

Whether to show the update set value dynamically toggle.

Type	boolean
Format	True/False
Configurability	Read-only
Default	`null`

Examples

falsetrue

`streamResponse`

Whether to stream the response.

Type	boolean
Format	True/False
Configurability	Code editor
Default	`null`

Examples

falsetrue

`successMessage`

The notification message to display on query success.

Type	string
Format	Plain Text
Configurability	Code editor
Default	`null`

Examples

falseQuery succeeded!

`timestamp`

The timestamp at which the query started to run.

Type	number
Format	Timestamp
Configurability	Read-only
Default	`null`

Examples

false1617024000000

`transformer`

The JavaScript code for transforming results.

Type	string
Configurability	Read-only
Default	`null`

`updateSetValueDynamically`

Whether to sync references from the query with the rest of the app.

Type	boolean
Configurability	Read-only
Default	`null`

`watchedParams`

A list of watched parameters.

Type	array
Array values	string
Configurability	Code editor
Default	`null`

`workflowId`

The UUID of the workflow.

Type	string
Format	UUID
Configurability	Read-only
Default	`null`

Examples

false123e4567-e89b-12d3-a456-426614174000

`workflowParams`

The workflow parameters.

Type	object
Configurability	Read-only
Default	`null`

`workflowRunBodyType`

The workflow run body type.

Type	string
Configurability	Read-only
Default	`null`

`workflowRunExecutionType`

The workflow run execution type.

Type	string
Configurability	Read-only
Default	`null`

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()

Examples

Clear the cache for query.

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. This method returns a promise and can only be used in JavaScript queries, not in transformers or {{ }} dynamic expressions.

Definition
await query.trigger(options)

Parameters

`options`

Additional options to use.

Type

object

Object Properties

`additionalScope`

Additional scope variables to use in the query.

Type	object
Format	Custom data

Examples

{"key1": "value1", "key2": "value2"}

`onFailure`

The function to run when the query fails.

Type	string
Format	Function

Examples

function (error) {console.log(error); }

`onSuccess`

The function to run when the query succeeds.

Type	string
Format	Function

Examples

function (data) {runQuery(i + 1);}

Returns

Returns a Promise that resolves to the following:

`data`

The data.

Type	string \| number \| boolean \| object \| array
Format	Custom data

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.

Properties​

allowedGroupIds​

allowedGroups​

cacheKeyTtl​

changeset​

changesetIsObject​

changesetObject​

confirmationMessage​

data​

enableCaching​

enableErrorTransformer​

enableTransformer​

error​

errorTransformer​

events​

event​

method​

type​

finished​

importedQueryInputs​

isFetching​

isImported​

lastReceivedFromResourceAt​

metadata​

headers​

cache-control​

connection​

content-encoding​

content-length​

content-type​

date​

server​

request​

body​

headers​

headers​

User-Agent​

X-Retool-Forwarded-For​

ot-baggage-requestId​

traceparent​

tracestate​

method​

url​

status​

statusText​

notificationDuration​

offlineOptimisticResponse​

offlineQueryType​

offlineUserQueryInputs​

overrideOrgCacheForUserCache​

playgroundQueryId​

playgroundQuerySaveId​

playgroundQueryUuid​

privateParams​

query​

queryDisabled​

queryDisabledMessage​

queryFailureConditions​

condition​

message​

queryRefreshTime​

queryRunOnSelectorUpdate​

queryRunTime​

queryThrottleTime​

queryTimeout​

queryTriggerDelay​

rawData​

requestSentTimestamp​

requireConfirmation​

resourceNameOverride​

resourceTypeOverride​

runWhenModelUpdates​

runWhenPageLoads​

runWhenPageLoadsDelay​

servedFromCache​

showFailureToaster​

showLatestVersionUpdatedWarning​

showSuccessToaster​

showUpdateSetValueDynamicallyToggle​

streamResponse​

Properties

`allowedGroupIds`

`allowedGroups`

`cacheKeyTtl`

`changeset`

`changesetIsObject`

`changesetObject`

`confirmationMessage`

`data`

`enableCaching`

`enableErrorTransformer`

`enableTransformer`

`error`

`errorTransformer`

`events`

`event`

`method`

`type`

`finished`

`importedQueryInputs`

`isFetching`

`isImported`

`lastReceivedFromResourceAt`

`metadata`

`headers`

`cache-control`

`connection`

`content-encoding`

`content-length`

`content-type`

`date`

`server`

`request`

`body`

`headers`

`headers`

`User-Agent`

`X-Retool-Forwarded-For`

`ot-baggage-requestId`

`traceparent`

`tracestate`

`method`

`url`

`status`

`statusText`

`notificationDuration`

`offlineOptimisticResponse`

`offlineQueryType`

`offlineUserQueryInputs`

`overrideOrgCacheForUserCache`

`playgroundQueryId`

`playgroundQuerySaveId`

`playgroundQueryUuid`

`privateParams`

`query`

`queryDisabled`

`queryDisabledMessage`

`queryFailureConditions`

`condition`

`message`

`queryRefreshTime`

`queryRunOnSelectorUpdate`

`queryRunTime`

`queryThrottleTime`

`queryTimeout`

`queryTriggerDelay`

`rawData`

`requestSentTimestamp`

`requireConfirmation`

`resourceNameOverride`

`resourceTypeOverride`

`runWhenModelUpdates`

`runWhenPageLoads`

`runWhenPageLoadsDelay`

`servedFromCache`

`showFailureToaster`

`showLatestVersionUpdatedWarning`

`showSuccessToaster`

`showUpdateSetValueDynamicallyToggle`

`streamResponse`