Skip to main content

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