Skip to main content

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​

data
any

The query results.

error
string

The error message if the query was unsuccessful.

cacheKeyTtl
number

The duration, in seconds, to cache query results.

confirmationMessage
string

The message to display in the confirmation modal before running the query, if query.requireConfirmation is true.

enableTransformer
boolean

Whether a transformer is enabled.

events
object

Event handlers to trigger in response to query success or failure.

finished
number

The UNIX timestamp specifying when the query finished executing.

id
string

The query name.

enableCaching
boolean

Whether to cache query results.

isFetching
boolean

Whether the query is in the process of retrieving results.

isImported
boolean

Whether the query was imported from the Query Library.

lastReceivedFromResourceAt
number

The UNIX timestamp the query was last received from the resource. If the query is cached, this is used with cacheKeyTtl to determine whether to return results from the cache the next time the query runs.

notificationDuration
number

The duration, in seconds, to display notifications on query success or failure.

pluginType
string

The query type.

privateParams
object

A list of parameters to exclude from audit logs.

query
string

The raw query string. For JavaScript and database queries, this is the entire query body. For REST API queries, this is the endpoint string.

queryDisabled
boolean

Whether the query is disabled.

queryDisabledMessage
string

The message to display when a disabled query is triggered.

queryFailureConditions
object[]

A list of conditions that determine if the query has failed.

condition
string

The condition that determines if the query has failed.

message
string

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

queryRefreshTime
number

The frequency, in milliseconds, to run the query if it is set to run periodically.

queryRunTime
number

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

queryTimeout
number

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
number

The duration, in milliseconds, to delay before running event handlers on query success or failure.

rawData
any

The data returned from the query before any transformers are applied.

requestSentTimestamp
number

The Unix timestamp the query request was sent.

runWhenModelUpdates
boolean

Whether to automatically run the query when its parameters change.

runWhenPageLoads
boolean

Whether to automatically run the query when the app loads.

runWhenPageLoadsDelay
number

The amount of time, in milliseconds, to delay running the query on page load.

servedFromCache
boolean

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

showFailureToaster
boolean

Whether to show a notification on query failure.

showSuccessToaster
boolean

Whether to show a notification on query success.

successMessage
string

The notification message to display on query success.

timestamp
number

The Unix timestamp the query began to run.

transformer
string

The contents of the query's transformer code.

updateSetValueDynamically
boolean

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

Methods​

Methods for interacting with queries. You can write JavaScript almost anywhere in Retool and use methods to manipulate data or components.

invalidateCache()​

Declares the cached results of the query invalid. The next time the query is triggered, it will return fresh results.

Example​

Invalidate the cache for the getUsers query.

getUsers.invalidateCache();

reset()​

Clear the data and error properties of the query.

Example​

Clear the data and error properties of the getUsers query. Returns a Promise that resolves to the query's data property.

getUsers.reset();

trigger()​

Run the query.

options
object

Optional settings to use when triggering a query.

additionalScope
object

Additional context to pass to query.

onSuccess
function

Function to call after the query successfully returns.

onFailure
function

Function to call after the query unsuccessfully returns.

Example​

Trigger getUserById with additional scope, and call different functions if the query succeeds or fails.

const user = { id: 1, name: "test" };
await getUserById.trigger({
  additionalScope: { userId: user.id },
  onSuccess: function (data) {
    console.log(data);
  },
  onFailure: function (error) {
    console.log("Error");
  },
});