Query properties and JavaScript API methods for interacting with queries.
Properties
View a query's properties in the State tab in the left panel or anywhere you access the query. Additional query properties may be present, depending on the query type and settings.
data any
The query results.
error string
The query's error message.
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.
enableCaching boolean
Whether to cache query results.
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 name to identify the query.
isFetching boolean
Whether the query is in the process of retrieving results.
isImported boolean
Whether the query is 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.
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.
privateParams object
Parameters to exclude from Audit Logs.
queryDisabled boolean
Whether the query is disabled.
queryDisabledMessage string
The message to display when a disabled query is triggered.
queryFailureConditions object[]
An list of objects, each containing condition and message fields, which represent the conditions in which to mark the query as failed and optionally show a notification.
queryRefreshTime number
The frequency, in milliseconds, to run the query if the query 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 message for the notification to show on query success.
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.
pluginType string
The type of the query.
Methods
Use query methods to control when and how queries run.
query.invalidateCache()
Declares the cached results of the query invalid. The next time the query is triggered, it will return fresh results.
Syntax
query.invalidateCache()
Return value
None.
Example
Invalidate the cache for the getUsers query.
getUsers.invalidateCache();
query.reset()
Clears the data and error properties of the query.
Syntax
query.reset()
Return value
None.
Example
Clear the data and error properties of the getUsers query.
getUsers.reset();
query.trigger()
Runs the query.
Syntax
query.trigger(options)
options optional
An object to pass to the query and to control behavior after the query returns.
| Parameter | Type | Description |
|---|---|---|
additionalScope | object (optional) | Additional context to pass to query. |
onSuccess | function (optional) | Function to call after query successfully returns. |
onFailure | function (optional) | Function to call on query failure. |
Return value
Returns a Promise that resolves to the query's data property.
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");
},
});
console.log("User ID passed", userId);