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

["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

["admin", "viewer"]

---

cacheKeyTtl

The duration, in seconds, to cache query results.

Type	number
Format	Integer
Configurability	Code editor
Default	null

Examples

3600

---

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

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

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

Examples

"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

true

---

enableErrorTransformer

Whether to enable the error transformer.

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

Examples

true

---

enableTransformer

Whether the query is transforming results.

Type	boolean
Format	True/False
Configurability	Code editor
Default	false

Examples

true

---

error

The error message if the action was unsuccessful.

Type	string
Format	Plain Text
Configurability	Read-only
Default	null

Examples

"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

1617024000000

---

importedQueryInputs

The inputs for imported queries.

Type	object
Format	object
Configurability	Read-only
Default	{}

Examples

[{"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

true

---

isImported

Whether the query was imported from the Query Library.

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

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

Examples

1634025600000

---

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

public, immutable, max-age=31556926

---

connection

The connection of the response.

Type	array
Array values	string
Configurability	Read-only
Default	null

Examples

"keep-alive"

---

content-encoding

The content encoding of the response.

Type	array
Array values	string
Configurability	Read-only
Default	null

Examples

["gzip"]

---

content-length

The content length of the response.

Type	array
Array values	string
Configurability	Read-only
Default	null

Examples

"1234"

---

content-type

The content type of the response.

Type	array
Array values	string
Configurability	Read-only
Default	null

Examples

["application/json"]

---

date

The date of the response.

Type	array
Array values	string
Configurability	Read-only
Default	null

Examples

"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

"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

{"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

"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

"12345"

---

traceparent

The trace parent.

Type	string
Configurability	Read-only
Default	undefined

Examples

"00-1234567890abcdef1234567890abcdef-1234567890abcdef-01"

---

tracestate

The trace state.

Type	string
Configurability	Read-only
Default	undefined

Examples

"congo=t61rcWkgMzE"

---

---

Examples

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

---

method

The HTTP method used.

Type	string
Configurability	Read-only
Default	null

Examples

GET

POST

---

url

The URL of the request.

Type	string
Configurability	Read-only
Default	null

Examples

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

---

---

status

The HTTP status code.

Type	number
Format	Integer
Configurability	Read-only
Default	null

Examples

200

---

statusText

The HTTP status text.

Type	string
Configurability	Read-only
Default	null

Examples

OK

---

---

notificationDuration

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

Type	number
Format	Float
Configurability	Read-only
Default	null

Examples

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

true

---

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

123e4567-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

SELECT * FROM users

https://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

true

---

queryDisabledMessage

The message to display if queryDisabled is true.

Type	string
Format	Plain Text
Configurability	Code editor
Default	null

Examples

This 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

1000

---

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

1617024000000

---

requireConfirmation

Whether to require confirmation.

Type	boolean
Format	True/False
Configurability	Code editor
Default	null

Examples

true

---

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

true

---

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

true

---

streamResponse

Whether to stream the response.

Type	boolean
Format	True/False
Configurability	Code editor
Default	null

Examples

true

---

successMessage

The notification message to display on query success.

Type	string
Format	Plain Text
Configurability	Code editor
Default	null

Examples

Query succeeded!

---

timestamp

The timestamp at which the query started to run.

Type	number
Format	Timestamp
Configurability	Read-only
Default	null

Examples

1617024000000

---

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

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