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​

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​

number

The duration, in seconds, to cache query results.

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

data​

any[]

The source data.

Whether to cache query results.

Whether the query is transforming results.

error​

string

The error message if the action was unsuccessful.

events​

object[]

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

Properties

event​

enum

The event type.

Values
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 true.

false

A user sets the value to false.

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​

enum

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

The type of action to perform.

Values
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​

number

The UNIX timestamp for the most recent query run.

id​

string

The unique identifier.

isFetching​

boolean

Whether data is being fetched.

isImported​

boolean

Whether the query was imported from the Query Library.

lastReceivedFromResourceAt​

number

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​

number

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

pluginType​

string

The plugin type.

A list of parameters to exclude from audit logs.

query​

string

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

Whether input, interaction, selection, or triggering is disabled.

The message to display if queryDisabled is true.

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

Properties

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.

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 wait after being triggered before running.

rawData​

any

The initial query data before any transformation of results.

requestSentTimestamp​

number

The Unix timestamp the query request was sent.

runWhenModelUpdates​

boolean

Whether to automatically run the query when its parameters change.

Whether to automatically run the query when the app loads.

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

servedFromCache​

boolean

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

Whether to show a notification on query failure.

Whether to show a notification on query success.

The notification message to display on query success.

timestamp​

number

The Unix timestamp at which the query started to run.

transformer​

string

The JavaScript code for transforming results.

updateSetValueDynamically​

boolean

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.

await query.trigger(triggerOptions)
Parameters

triggerOptions​

object

Additional options to use.

Properties

additionalScope​

object

Data to pass to query.

onFailure​

function

Function to call if the query unsuccessfully runs.

onSuccess​

function

Function to call after the query successfully runs.

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.

success​

A query or action is completed successfully.