Creating an array column#

Here is the thing about array columns in Servoy: they do not exist as a type you select in the table editor. The standard Servoy column type abstraction covers DATETIME, INTEGER, MEDIA, NUMBER, TEXT, and UUID. There is no “Array” selector in that list. Array columns are a PostgreSQL-level feature, and Servoy surfaces them by reading the table metadata after you create the column via DDL.

Support for array columns shipped in Servoy 2025.06 (ticket SVY-20207), available in PostgreSQL and HSQLDB [1]. For production use, PostgreSQL is the one you care about. HSQLDB support exists but the release notes do not provide HSQLDB-specific syntax, so this article focuses on PostgreSQL.

You define the column in a migration script or directly in the PostgreSQL console:

1
CREATE TABLE crm_product (
2
    prod_id   SERIAL PRIMARY KEY,
3
    prod_name TEXT NOT NULL,
4
    tags      TEXT[],
5
    org_id    INTEGER NOT NULL
6
);

The TEXT[] syntax is standard PostgreSQL array notation. The Servoy release notes document INTEGER[] and TEXT[] as the confirmed element types [1]. Other PostgreSQL-native array types (BOOLEAN[], NUMERIC[], DATE[]) follow standard PostgreSQL array conventions, but only INTEGER[] and TEXT[] appear in the official examples, so hedge if you go beyond those two.

Once the DDL is applied, Servoy picks up the tags column automatically when it reads table metadata. No Servoy Developer configuration is needed beyond that.

Reading and writing as JavaScript arrays#

The ORM handles PostgreSQL array serialization transparently. From the foundset side, reading and writing an array column looks exactly like any other dataprovider:

1
/**
2
 * Set the initial tags for the current product record.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @return {void}
7
 */
8
function setInitialTags() {
9
    try {
10
        /**@type {Array<String>}*/
11
        const aInitialTags = ['featured', 'new-arrival'];
12
        foundset.tags = aInitialTags;
13

14
        /**@type {Boolean}*/
15
        const bSaved = databaseManager.saveData();
16
        if (!bSaved) {
17
            databaseManager.rollbackEditedRecords();
18
            application.output('saveData() failed in setInitialTags', LOGGINGLEVEL.ERROR);
19
            plugins.dialogs.showErrorDialog('Save Error', 'Could not save product tags. Please try again.', 'OK');
20
        }
21
    } catch (oError) {
22
        application.output('Error in setInitialTags: ' + oError.message, LOGGINGLEVEL.ERROR);
23
        plugins.dialogs.showErrorDialog('Error', 'An unexpected error occurred while setting tags.', 'OK');
24
    }
25
}

Reading is equally direct:

1
/**
2
 * Get the tags for the current product record.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @return {Array<String>}
7
 */
8
function getProductTags() {
9
    /**@type {Array<String>}*/
10
    const aTags = foundset.tags ?? [];
11
    return aTags;
12
}

The ?? [] guard handles the case where tags is null on a new record before any tags have been set. That’s it. No JSON parsing, no split-on-delimiter, no special plugin call. The foundset dataprovider returns a JavaScript array and accepts one back.

The sealed-array quirk#

Here is where things get interesting, and where you need to pay attention if you are upgrading an existing application.

When Servoy returns an array from a record dataprovider, that array is sealed [1]. The release notes are explicit about why:

“Because of the Database Array support the arrays that are stored in the record are sealed now. This is because changing the contents of an array that is stored in the record is not supported. If you want to change the contents of an array, you need to make a copy (slice(0)) and then alter that and set the array back” [1].

What this means in practice: if you do foundset.tags.push('sale'), Servoy will throw an error. The sealed array cannot be mutated in place. The correct idiom is slice-copy-and-reassign:

1
/**
2
 * Add a tag to the current product record.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @param {String} sTag The tag to add.
7
 * @return {void}
8
 */
9
function addTag(sTag) {
10
    try {
11
        /**@type {Array<String>}*/
12
        const aCurrent = foundset.tags ? foundset.tags.slice(0) : [];
13

14
        if (aCurrent.indexOf(sTag) === -1) {
15
            aCurrent.push(sTag);
16
            foundset.tags = aCurrent;
17

18
            /**@type {Boolean}*/
19
            const bSaved = databaseManager.saveData();
20
            if (!bSaved) {
21
                databaseManager.rollbackEditedRecords();
22
                application.output('saveData() failed in addTag', LOGGINGLEVEL.ERROR);
23
                plugins.dialogs.showErrorDialog('Save Error', 'Could not save the tag. Please try again.', 'OK');
24
            }
25
        }
26
    } catch (oError) {
27
        application.output('Error in addTag: ' + oError.message, LOGGINGLEVEL.ERROR);
28
        plugins.dialogs.showErrorDialog('Error', 'An unexpected error occurred while adding the tag.', 'OK');
29
    }
30
}

The three steps are: slice(0) to copy, mutate the copy, then assign the copy back to the dataprovider.

Removing a tag follows the same pattern:

1
/**
2
 * Remove a tag from the current product record.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @param {String} sTag The tag to remove.
7
 * @return {void}
8
 */
9
function removeTag(sTag) {
10
    try {
11
        /**@type {Array<String>}*/
12
        const aCurrent = foundset.tags ? foundset.tags.slice(0) : [];
13
        /**@type {Number}*/
14
        const nIndex = aCurrent.indexOf(sTag);
15

16
        if (nIndex !== -1) {
17
            aCurrent.splice(nIndex, 1);
18
            foundset.tags = aCurrent;
19

20
            /**@type {Boolean}*/
21
            const bSaved = databaseManager.saveData();
22
            if (!bSaved) {
23
                databaseManager.rollbackEditedRecords();
24
                application.output('saveData() failed in removeTag', LOGGINGLEVEL.ERROR);
25
                plugins.dialogs.showErrorDialog('Save Error', 'Could not remove the tag. Please try again.', 'OK');
26
            }
27
        }
28
    } catch (oError) {
29
        application.output('Error in removeTag: ' + oError.message, LOGGINGLEVEL.ERROR);
30
        plugins.dialogs.showErrorDialog('Error', 'An unexpected error occurred while removing the tag.', 'OK');
31
    }
32
}

One more thing: the sealed-array rule also applies to JSON arrays stored in string columns via StringSerializer. If your application uses StringSerializer to persist arrays as JSON strings in a TEXT column, those returned arrays are now sealed too [1]. The same slice(0) idiom applies. This is the part of the breaking change that is easy to miss on upgrade.

Query limitations: exact match only#

This is the part where the feature shows its current limits.

As of 2026.03, QBSelect can only match an array column against a whole array exactly [1]. That means you can query for records where tags = ['featured', 'new-arrival'] as a whole-array equality check, but you cannot query for records where tags contains the value 'featured'. There is no QBArrayColumn subclass in the typed Query Builder, and there is no element-level operator exposed through QBSelect.

The 2025.06 release notes are direct about this:

“Currently, arrays must match exactly for querying purposes. Potential future enhancements could allow searching individual array values” [1].

If you need to search within array elements, the workaround is plugins.rawSQL with native PostgreSQL array operators:

1
/**
2
 * Load all products that include the given tag, using a raw SQL element search.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @param {String} sTag The tag to search for.
7
 * @return {void}
8
 */
9
function loadProductsByTag(sTag) {
10
    try {
11
        /**@type {String}*/
12
        const sSQL = 'SELECT prod_id FROM crm_product WHERE ? = ANY(tags) AND org_id = ?';
13

14
        /**@type {JSDataSet}*/
15
        const dsPks = databaseManager.getDataSetByQuery('myserver', sSQL,
16
            [sTag, globals.org_id], -1); // -1 returns all matching rows
17

18
        // dsPks has a single PK column (prod_id), which is exactly what loadRecords expects.
19
        foundset.loadRecords(dsPks);
20
    } catch (oError) {
21
        application.output('Error in loadProductsByTag: ' + oError.message, LOGGINGLEVEL.ERROR);
22
        plugins.dialogs.showErrorDialog('Error', 'Could not search products by tag.', 'OK');
23
    }
24
}

The ANY() operator is PostgreSQL native and does the element search the typed query builder cannot. Two API details matter here. First, retrieving rows with raw SQL uses databaseManager.getDataSetByQuery(server, sql, args, maxRows), which returns a JSDataSet. Do not reach for plugins.rawSQL.executeSQL to fetch rows: that method returns a Boolean and is only for writes and DDL (INSERT/UPDATE/DELETE). Second, when the SELECT returns the table’s primary key, you can hand the resulting dataset straight to foundset.loadRecords(dsPks); there is no need to loop the rows or convert anything by hand. The tradeoff of the raw SQL route is that it runs outside the typed-query layer, so it is harder to refactor and loses the type safety the QBSelect typed columns give you.

A realistic scenario: tags on a product#

Let’s put this into context with something concrete. You are building a product catalog in a CRM. Each product can have multiple tags: 'featured', 'sale', 'new-arrival', 'clearance'. You need to store these tags and display them in the UI.

1
CREATE TABLE crm_product_tag (
2
    tag_id   SERIAL PRIMARY KEY,
3
    prod_id  INTEGER NOT NULL REFERENCES crm_product(prod_id),
4
    tag_name TEXT NOT NULL,
5
    org_id   INTEGER NOT NULL
6
);

1
/**
2
 * Load all featured products via the child-table relation.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @return {void}
7
 */
8
function loadFeaturedProducts() {
9
    try {
10
        /**@type {QBSelect<db:/myserver/crm_product>}*/
11
        const query = datasources.db.myserver.crm_product.createSelect();
12

13
        query.result.addPk();
14

15
        /**@type {QBJoin<db:/myserver/crm_product_tag>}*/
16
        const joinTag = query.joins.add('db:/myserver/crm_product_tag', QBJoin.INNER_JOIN, 'tag');
17
        joinTag.on.add(joinTag.columns.prod_id.eq(query.columns.prod_id));
18

19
        query.where.add(joinTag.columns.tag_name.eq('featured'));
20
        query.where.add(query.columns.org_id.eq(globals.org_id));
21

22
        foundset.loadRecords(query);
23
    } catch (oError) {
24
        application.output('Error in loadFeaturedProducts: ' + oError.message, LOGGINGLEVEL.ERROR);
25
        plugins.dialogs.showErrorDialog('Error', 'Could not load featured products.', 'OK');
26
    }
27
}

1
/**
2
 * Initialize default tags for a new product record.
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @return {void}
7
 */
8
function initProductTags() {
9
    try {
10
        /**@type {Array<String>}*/
11
        const aDefaultTags = ['new-arrival'];
12
        foundset.tags = aDefaultTags;
13

14
        /**@type {Boolean}*/
15
        const bSaved = databaseManager.saveData();
16
        if (!bSaved) {
17
            databaseManager.rollbackEditedRecords();
18
            application.output('saveData() failed in initProductTags', LOGGINGLEVEL.ERROR);
19
            plugins.dialogs.showErrorDialog('Save Error', 'Could not save product tags.', 'OK');
20
        }
21
    } catch (oError) {
22
        application.output('Error in initProductTags: ' + oError.message, LOGGINGLEVEL.ERROR);
23
        plugins.dialogs.showErrorDialog('Error', 'An unexpected error occurred.', 'OK');
24
    }
25
}

1
/**
2
 * Check if the current product has the 'featured' tag (in-memory check).
3
 * @author Gary Dotzlaw
4
 * @since 2026-06-11
5
 * @public
6
 * @return {Boolean}
7
 */
8
function isFeatured() {
9
    /**@type {Array<String>}*/
10
    const aTags = foundset.tags ?? [];
11
    return aTags.indexOf('featured') !== -1;
12
}

When to use array columns#

Use array columns when these conditions all hold:

• The list is bounded and small (under 50 elements is a reasonable guide).
• You do not need to query by element across records in everyday application queries. In-memory checks like isFeatured() are fine; cross-record searches in batch reports are not.
• The elements do not reference other entities. Tags like 'featured' and 'sale' are freeform strings. If the values were product category IDs pointing to a crm_category table, you need a child table for referential integrity.
• Write churn is low to moderate. The slice(0) copy-and-reassign overhead is negligible for occasional tag updates but is worth considering for batch operations that update tags on thousands of records.

The bottom-line: array columns are excellent for bounded, freeform, read-mostly sets that you display or check in-memory, with no search requirement. Permission arrays per user (['admin', 'reports', 'billing']), product status flags, and multi-category labels all fit this profile.

When to use a child table#

Use a child table when any of the following apply:

• You need to search by element. “Show me all products tagged ‘featured’” is a query you want to write in QBSelect, not in raw SQL. If this is a common application query, use a child table.
• Cardinality is unbounded. A product can have 3-5 tags. A knowledge base article can have 50. A mailing list member can have 300 audience segments. At some point the array pattern stops being a simplification.
• Elements reference other entities. If each tag is actually a link to a managed crm_tag record with its own display name, colour, and visibility rules, you need a child table with a foreign key.
• High-churn writes. If your batch processor adds and removes elements from these arrays continuously for large record sets, the overhead of loading, copying, mutating, and saving each array individually will hurt throughput.
• Reporting. SQL reporting tools that query the database directly work well with normalized child tables and struggle with array columns unless the reporting tool supports PostgreSQL array syntax.

Binding to a multi-select UI component (2025.12)#

If you are on Servoy 2025.12 or later, there is a bonus worth knowing about. Servoy 2025.12 (ticket SVY-20565) introduced a multiselect property on certain UI components that lets you bind the component directly to an array dataprovider [2]:

“For certain UI components we introduced a multiselect property. It allows these components to be bound directly to an Array data-provider (columns and variables)” [2]. “This means that developers no longer need to bind to a string and split on a delimiter (i.e. \n) as before, but can directly connect the component to the Array column/variable” [2].

Before 2025.12, if you wanted a multi-select dropdown for a tag field, you had to bind it to a string column and parse the delimiter on read and write. That meant choosing a delimiter that would never appear in your values, handling edge cases, and keeping the string representation in sync with whatever display component the user interacted with. Not pretty.

With 2025.12+, you set the component’s multiselect property and bind it directly to the tags column, so you no longer manage the string-splitting or the array assignment yourself. The version gate here is important: the multiselect property is not available on 2025.06, where array columns first landed. Plan accordingly if your deployment targets an earlier version.

What comes next#

Array columns and vector columns are both database-level features that landed in the 2025 release wave and work together in AI-enabled applications. An array column holding a list of category tags is exactly the kind of structured metadata you combine with a semantic embedding search to build a hybrid retrieval system. If that sounds interesting, my Embedding Data with Servoy AI [4] and Hybrid Queries in Servoy AI [5] tutorials walk through the embedding storage and query patterns that sit alongside this one.

Conclusion#

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

References#

[1] Servoy, “2025.06 Release Notes,” docs.servoy.com, June 2025. https://docs.servoy.com/release-notes/release-notes/2025.06

[2] Servoy, “2025.12 Release Notes,” docs.servoy.com, January 2026. https://docs.servoy.com/release-notes/release-notes/2025.12

[3] G. Dotzlaw, “Modern JavaScript in Servoy (Tutorial #17),” dotzlaw.com. /insights/servoy-tutorial-17-modern-javascript/

[4] G. Dotzlaw, “Embedding Data with Servoy AI (Tutorial #3),” dotzlaw.com. /insights/servoy-tutorial-03-embedding-data/

[5] G. Dotzlaw, “Hybrid Queries in Servoy AI (Tutorial #4),” dotzlaw.com. /insights/servoy-tutorial-04-hybrid-queries/