Skip to main content

Query Object

This page describes how to use the Query object to run queries and access the data from the response.

run()​

Calling a query's run() function executes that query. run() is asynchronous and returns a promise, so you can use it with async syntax like .then() chains and async/await. It can't be used in synchronous fields.

Signature​

run(params: Object): Promise
ArgumentDescription
paramsAn object containing key-value pairs to pass into the query. Accessed with {{ this.params.key }}.

This function returns a JavaScript promise, which can be used to handle async actions in sequence. Use .then() and .catch() to write code to be executed when the query returns successfully or in error, respectively. Or, use async/await syntax.

// Using promise syntax to chain actions in sequence
{{
    Query1.run(params)
        .then(() => {...}) // run after the query is successful
        .catch(() => {...}) // run if the query encounters any errors
}}

To learn more about chaining actions to create complex workflows, see complex workflows.

Pass parameters to run()​

Most queries read values directly from entities as global variables. In some cases, like running a query inside a loop, parameters may need to be passed to the query with values contextual to the execution.

For this, use the params argument to pass an object of key-value pairs into your query. You can access these values within the query using {{ this.params.key }}.

Example​

Imagine you need to fetch specific users from a database based on their id value. In this example, you'll see how to configure a query and a helper function to take an array of ids and run the query for each of them.

Setup

On the canvas, you should have a Table widget and a Button widget.

Use Appsmith's mock Postgres user database to create a query called GetUserById. Add the following SQL statement to the query:

SELECT * FROM users WHERE id = {{ this.params.id }};

This statement expects a parameter to be passed in from the run() function to use as the id value.

Create a JS Object and name it utils. This is where you write your helper function that calls the query and handles its responses. The following code snippet runs the query once for each id in its ids array, waits for the database's response, and stores the resulting table records in the Appsmith store.

// function in the utils JS Object
getByIds: async (ids) => {
    const queries = ids.map(id => {
        return GetUserById.run({"id": id})
    })
    
    Promise.allSettled(queries)
        .then(queryResponses => queryResponses.map(res => res.value[0]))
        .then(records => storeValue("records", records))
}

Now when the utils.getByIds() function is run with an array of ids, you'll have your resulting records available in the Appsmith store. Bind this value to the Table Data property of your Table widget:

// Table Data property of the Table widget
{{ appsmith.store.records }}

Finally, to execute the query, set the Button widget's onClick event to execute your helper function:

// Button widget's onClick
{{ utils.getByIds([1, 4, 8, 34, 16])}}

When you click the button, it runs your helper function that queries the database for each of your desired users.

Properties​

These properties are used to reference and control data related to your query.

PropertyDescription
dataContains the response body from the last successful execution of this query. If this property is referenced in a widget's property field, the query is automatically run on page load.
responseMetaContains metadata from the last response to this query's execution.
clear()Empties all data from the query's data property.
run()Executes the query when called. Can't be called in sync fields; see sync vs. async fields.

Further reading​