The Problem Async Solves#

Let’s imagine for a moment that you are building a customer dashboard. When the user opens it, you need to load:

• The last ten orders
• Outstanding balance
• Recent support tickets
• A summary of product returns in the last 90 days

Four queries. In the classic synchronous model, you fire them one at a time, and each one blocks the client until it returns. If each query takes 200 milliseconds, your dashboard takes the better part of a second to load. Your users see a spinner. Your application feels sluggish. The database is idle three out of every four queries because only one is running at a time.

This is the exact shape of problem async APIs were designed for. Independent queries that do not need each other’s results can run in parallel. Eight hundred milliseconds of sequential loading becomes 200 milliseconds of parallel loading. The database does the same amount of work, but the client waits four times less.

Make sense? Let’s look at how to do it.

What Changed in Servoy#

The timeline is short and matters:

• Servoy 2025.06 brought async Promise APIs to the database layer: databaseManager.getDataSetByQueryAsync(), plugins.rawSQL.executeAsyncSQL(), and plugins.rawSQL.executeAsyncStoredProcedure(). The HTTP plugin had already introduced Promise-returning async APIs before this; 2025.06 extended the same pattern to the data plugins.
• Servoy 2025.12 completed what Servoy calls the “all async plugins” rollout. Every async plugin (HTTP, HeadlessClient, RawSQL, databaseManager, and the new AI Runtime Plugin) supports both Promise return types and callback variants. Headless Client and REST Client also gained the ability to handle Promise results returned from solution methods.
• Servoy 2026.03 added JSDoc generic notation for Promise return types, which means the script editor correctly infers the resolved type inside .then() callbacks.

Everything in this tutorial targets 2025.06 or later at minimum. The Promise generic JSDoc examples need 2026.03 for full editor support, but the code itself runs fine on 2025.06.

One thing to keep in mind on the naming. The database side uses the suffix style: getDataSetByQueryAsync. The rawSQL plugin uses the prefix style: executeAsyncSQL. Same idea, different conventions. The HTTP plugin sits in between with executeAsyncRequest. I wish it were uniform. It is not. Copy the names exactly.

The Two Shapes of Async API#

Servoy’s async APIs come in two forms. Both exist on purpose. Pick based on the job.

1
databaseManager.getDataSetByQueryAsync(query, 1000)
2
    .then(function(dsResult) {
3
        // handle result
4
    })
5
    .catch(function(oError) {
6
        // handle error
7
    });

1
plugins.http.createNewHttpClient()
2
    .createGetRequest(sUrl)
3
    .executeAsyncRequest(
4
        function(oResponse) { /* success */ },
5
        function(sErrorMessage) { /* error */ }
6
    );

Your First Async Query#

Here is a classic synchronous query, written the way Servoy has always been written:

1
/**
2
 * Loads the ten most recent orders for a customer.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sCustomerId the customer id
8
 * @return {JSDataSet} the recent orders
9
 */
10
function loadRecentOrdersSync(sCustomerId) {
11
        /**@type {QBSelect<db:/myserver/crm_order>}*/
12
    const qbOrders = datasources.db.myserver.crm_order.createSelect();
13
    qbOrders.result.add(qbOrders.columns.ordh_document_number);
14
    qbOrders.result.add(qbOrders.columns.ordh_order_date);
15
    qbOrders.result.add(qbOrders.columns.ordh_total);
16
    qbOrders.where.add(qbOrders.columns.org_id.eq(globals.org_id));
17
    qbOrders.where.add(qbOrders.columns.cust_id.eq(sCustomerId));
18
    qbOrders.sort.add(qbOrders.columns.ordh_order_date.desc);
19

20
        /**@type {JSDataSet}*/
21
    const dsOrders = databaseManager.getDataSetByQuery(qbOrders, 10);
22
    return dsOrders;
23
}

The call site is simple:

1
    /**@type {JSDataSet}*/
2
const dsOrders = loadRecentOrdersSync(sCustomerId);
3
application.output('Found ' + dsOrders.getMaxRowIndex() + ' orders');

Nothing wrong with this. It is clear, it works, it returns in whatever time the database takes. When you only have one query to run, this is the right form.

Here is the same thing using the async API:

1
/**
2
 * Loads the ten most recent orders for a customer, async.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sCustomerId the customer id
8
 * @return {Promise<JSDataSet>} resolves with the recent orders
9
 */
10
function loadRecentOrdersAsync(sCustomerId) {
11
        /**@type {QBSelect<db:/myserver/crm_order>}*/
12
    const qbOrders = datasources.db.myserver.crm_order.createSelect();
13
    qbOrders.result.add(qbOrders.columns.ordh_document_number);
14
    qbOrders.result.add(qbOrders.columns.ordh_order_date);
15
    qbOrders.result.add(qbOrders.columns.ordh_total);
16
    qbOrders.where.add(qbOrders.columns.org_id.eq(globals.org_id));
17
    qbOrders.where.add(qbOrders.columns.cust_id.eq(sCustomerId));
18
    qbOrders.sort.add(qbOrders.columns.ordh_order_date.desc);
19

20
    return databaseManager.getDataSetByQueryAsync(qbOrders, 10);
21
}

Three differences worth pointing out:

• The return type is Promise<JSDataSet> in the JSDoc. On 2026.03, the editor uses that generic to type the value inside any .then() callback that consumes this function. Without the generic, the editor sees “Promise” and does not know what it wraps.
• databaseManager.getDataSetByQueryAsync(...) replaces getDataSetByQuery(...). The arguments are identical.
• No intermediate const dsOrders variable. There is nothing to assign yet. The Promise represents future work.

The call site changes more:

1
loadRecentOrdersAsync(sCustomerId)
2
    .then(function(dsOrders) {
3
        application.output('Found ' + dsOrders.getMaxRowIndex() + ' orders');
4
    })
5
    .catch(function(oError) {
6
        application.output('Load failed: ' + oError.message, LOGGINGLEVEL.ERROR);
7
    });

The .then() callback gets the resolved value. The .catch() handles any failure in the chain. On 2026.03, the editor knows dsOrders is a JSDataSet because of the Promise generic annotation.

If you only ever ran one query, the async version would be strictly worse. More syntax, same performance. The payoff shows up when you have multiple independent queries.

Parallel Queries with Promise.all()#

Back to the dashboard. Four independent queries. None of them needs the result of any of the others. In the synchronous version, they run back-to-back. In the async version, they run at the same time.

Here is the sync version for reference:

1
/**
2
 * Loads dashboard data for a customer, synchronously.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sCustomerId the customer id
8
 * @return {Object} dashboard data
9
 */
10
function loadDashboardSync(sCustomerId) {
11
        /**@type {JSDataSet}*/
12
    const dsOrders = _queryRecentOrders(sCustomerId);
13
        /**@type {JSDataSet}*/
14
    const dsBalance = _queryOutstandingBalance(sCustomerId);
15
        /**@type {JSDataSet}*/
16
    const dsTickets = _queryRecentTickets(sCustomerId);
17
        /**@type {JSDataSet}*/
18
    const dsReturns = _queryRecentReturns(sCustomerId);
19

20
    return {
21
        orders: dsOrders,
22
        balance: dsBalance,
23
        tickets: dsTickets,
24
        returns: dsReturns
25
    };
26
}

Four queries, four round-trips to the database, one after another. If each takes 200 milliseconds, the function returns after 800 milliseconds.

Here is the async version using Promise.all():

1
/**
2
 * Loads dashboard data for a customer in parallel.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sCustomerId the customer id
8
 * @return {Promise<Object>} resolves with the dashboard data
9
 */
10
function loadDashboardAsync(sCustomerId) {
11
    return Promise.all([
12
        _queryRecentOrdersAsync(sCustomerId),
13
        _queryOutstandingBalanceAsync(sCustomerId),
14
        _queryRecentTicketsAsync(sCustomerId),
15
        _queryRecentReturnsAsync(sCustomerId)
16
    ]).then(function(aResults) {
17
            /**@type {Array<JSDataSet>}*/
18
        const [dsOrders, dsBalance, dsTickets, dsReturns] = aResults;
19
        return {
20
            orders: dsOrders,
21
            balance: dsBalance,
22
            tickets: dsTickets,
23
            returns: dsReturns
24
        };
25
    });
26
}

All four queries fire at the same time. The function returns after the slowest one finishes. If the slowest takes 200 milliseconds, the whole thing takes 200 milliseconds. You just got a 4x speedup with a structural change, not a query optimization.

A few things to notice:

• Promise.all() takes an array of Promises and returns a single Promise that resolves to an array of the results, in the same order as the input array.
• Array destructuring on the results. const [dsOrders, dsBalance, dsTickets, dsReturns] = aResults; unpacks the four results by position. This is much easier to read than aResults[0], aResults[1], and so on. The destructuring tutorial in this series covers this pattern in more detail.
• The Hungarian prefix still matches what each element is. The destructured locals use the ds prefix because they are datasets.
• The @type annotation on the destructuring line covers all four destructured variables. The array is typed as Array<JSDataSet>, and every element inside is a JSDataSet.

1
loadDashboardAsync(sCustomerId)
2
    .then(function(oDashboard) {
3
        _renderDashboard(oDashboard);
4
    })
5
    .catch(function(oError) {
6
        application.output('Dashboard load failed: ' + oError.message, LOGGINGLEVEL.ERROR);
7
        plugins.dialogs.showErrorDialog('Error', 'Could not load dashboard.', 'OK');
8
    });

Error Handling#

Error handling in async code is one of the places where it is easy to build bugs if you are not careful. Here is the pattern I use everywhere.

1
/**
2
 * Button click handler that loads data asynchronously.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {JSEvent} event the event
8
 */
9
function onLoadData(event) {
10
    try {
11
        loadDashboardAsync(foundset.cust_id)
12
            .then(function(oDashboard) {
13
                _renderDashboard(oDashboard);
14
            })
15
            .catch(function(oError) {
16
                application.output('Async load failed: ' + oError.message, LOGGINGLEVEL.ERROR);
17
                plugins.dialogs.showErrorDialog('Error', 'Could not load dashboard: ' + oError.message, 'OK');
18
            });
19
    } catch (e) {
20
        application.output('Error in onLoadData: ' + e.message, LOGGINGLEVEL.ERROR);
21
        plugins.dialogs.showErrorDialog('Error', 'An error occurred: ' + e.message, 'OK');
22
    }
23
}

1
// Wrong: silent failure
2
loadDashboardAsync(sCustomerId)
3
    .then(function(oDashboard) {
4
        _renderDashboard(oDashboard);
5
    });

Using the Callback Form#

There are times when callbacks are the simpler choice. Here is the HTTP plugin using the callback form:

1
/**
2
 * Fires off a webhook notification without blocking.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sPayload the JSON payload to send
8
 */
9
function fireWebhook(sPayload) {
10
    try {
11
            /**@type {Object}*/
12
        const oClient = plugins.http.createNewHttpClient();
13
            /**@type {Object}*/
14
        const oRequest = oClient.createPostRequest('https://hooks.example.com/notify');
15
        oRequest.setBodyContent(sPayload, 'application/json');
16

17
        oRequest.executeAsyncRequest(
18
            function(oResponse) {
19
                application.output('Webhook status: ' + oResponse.getStatusCode());
20
            },
21
            function(sErrorMessage) {
22
                application.output('Webhook failed: ' + sErrorMessage, LOGGINGLEVEL.ERROR);
23
            }
24
        );
25
    } catch (e) {
26
        application.output('Error in fireWebhook: ' + e.message, LOGGINGLEVEL.ERROR);
27
    }
28
}

A few things worth pointing out. The success callback receives a Response object you can interrogate with getStatusCode(), getResponseBody(), and friends. The error callback receives the error message as a String directly. That is why sErrorMessage here is annotated as a string rather than an object with a .message property. Get the shape wrong and you will end up logging “Webhook failed: undefined.”

No composition. No chaining. Just “fire this off, log whichever way it lands.” The callback form reads the same as the synchronous version with the flow inverted. If you are writing a one-off integration where all you want is success or failure, callbacks are fine. If you are composing this webhook call with three other async operations, use the Promise form instead.

Note that the HTTP plugin also gives you a Promise form via executeAsyncRequest() without arguments. The same underlying operation, two callable shapes. Same for rawSQL.executeAsyncSQL() and the AI plugin’s chat() method. Pick based on what the rest of the code in that function is doing.

A small caveat on Response objects from HTTP. A status code other than 200 is still a successful Promise resolution. The error callback (or .catch()) only fires when the request itself errors out (network failure, DNS issue, timeout). A 500 from the server is a “successful” call that returned a 500. Always check oResponse.getStatusCode() in your success path before assuming the call worked.

The @return {Promise<T>} Generic#

On 2026.03, the script editor understands generic notation on Promise return types. This matters more than it sounds like it should, because without it, every .then() callback is typed as Object and you lose autocomplete on the resolved value.

1
/**
2
 * Loads the recent orders for a customer.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sCustomerId the customer id
8
 * @return {Promise<JSDataSet>} resolves with the orders dataset
9
 */
10
function loadRecentOrdersAsync(sCustomerId) {
11
        /**@type {QBSelect<db:/myserver/crm_order>}*/
12
    const qbOrders = datasources.db.myserver.crm_order.createSelect();
13
    qbOrders.result.add(qbOrders.columns.ordh_document_number);
14
    qbOrders.where.add(qbOrders.columns.org_id.eq(globals.org_id));
15
    qbOrders.where.add(qbOrders.columns.cust_id.eq(sCustomerId));
16
    return databaseManager.getDataSetByQueryAsync(qbOrders, 10);
17
}
18

19
// Call site: editor knows dsOrders is a JSDataSet
20
loadRecentOrdersAsync(sCustomerId).then(function(dsOrders) {
21
    application.output(dsOrders.getMaxRowIndex());  // autocomplete works
22
});

Without the generic, you would need an explicit annotation inside the callback to get autocomplete:

1
// Without the generic on the declaration, annotate at the call site
2
loadRecentOrdersAsync(sCustomerId).then(function(dsOrders) {
3
        /**@type {JSDataSet}*/
4
    const dsTyped = dsOrders;
5
    application.output(dsTyped.getMaxRowIndex());
6
});

That is annoying, and annoyance leads to skipped annotations, and skipped annotations lead to typos. Add the generic on the function that returns the Promise. The editor takes care of the rest.

When Async Is the Wrong Choice#

Async is not a universal upgrade. Here are the cases where the synchronous version is the right answer.

One query, in sequence. If the function only runs one query, and the rest of the logic depends on its result, the async version adds syntax without removing any wait. Use the synchronous call.

Transactions that span multiple queries. Servoy transactions are tied to the current thread. Mixing sync and async inside a transaction is a recipe for “transaction timed out” errors and inconsistent state. When you are inside a databaseManager.startTransaction() block, stick with synchronous calls.

Simple CRUD inside form event handlers. The user clicks Save. You save one record. You show a confirmation. Making that async buys you nothing and complicates the flow. Save the record synchronously.

Small datasets loaded on form show. If the form’s onShow handler loads a single small foundset and renders it, the sync call is simpler and the user will never notice the difference.

The rule of thumb: reach for async when you have multiple independent operations whose results are all needed together, or when you are calling out to something slow (an HTTP endpoint, an LLM, a big SQL aggregate against millions of rows) and the client can do other useful work while waiting. Otherwise, stay sync.

The House-Style Position#

Applying the conventions from this series to async code:

Keep:

• Hungarian notation on every variable, including inside .then() callbacks
• @type JSDoc annotations on every variable, including destructured ones
• Full JSDoc headers on every function
• try/catch at invocation boundaries
• Named function declarations at scope level, arrow functions for inline callbacks only
• org_id tenant isolation in every query

Adopt for async:

• @return {Promise<T>} generics on every Promise-returning function (full editor support on 2026.03)
• Promise.all() with destructured results for parallel independent queries
• .catch() at the end of every Promise chain (never leave a chain un-terminated)
• Promise form by default, callback form when the flow is trivially linear
• Promise.allSettled() when you genuinely want all results regardless of failures (rare)

The async features improve throughput on the specific shape of problem they were designed for. They do not replace synchronous code. They complement it. Your goal is to use each where it actually helps, not to rewrite the entire codebase because you can.

What Comes Next#

This tutorial covered the language mechanics of Promises and the three core data APIs: databaseManager.getDataSetByQueryAsync(), plugins.rawSQL.executeAsyncSQL(), and plugins.http.executeAsyncRequest(). There is more in the pipeline:

• The AI Runtime Plugin uses Promises for every chat completion and embedding call. The .chat() method returns a Promise resolving to a ChatResponse. Streaming responses use the callback form instead. The four-part AI Runtime Plugin series already published earlier in this site uses these exact patterns end to end.
• The typed Query Builder covers the typed QBColumn subclasses that shipped in 2025.09 and pair well with async query patterns.
• Batch processing patterns covers how to parallelize large data jobs with Promise.all() while keeping memory usage under control.

Each of these builds on the Promise patterns you have now. Once you have the habit of returning Promises from async-capable functions, handling errors with .catch(), and composing parallel work with Promise.all(), the rest of the Servoy async ecosystem reads like a natural extension of the same playbook.

That concludes this Servoy tutorial on Promises and async. I hope you enjoyed it, and I look forward to bringing you more Servoy tutorials in the future.