Entities & queries

Creating entities

Construct an entity from its fully-qualified class name. The entity starts empty; you populate it with the methods below and then persist it.

var order = PSEntity("com.domain.commerce.Order");
order.identifier("ORD-2024-001");

Create a new, unsaved entity of the given class.

Set a stable business identifier — the key you later pass to data$.load.

var idn = "PROCESS_CATEGORY_BUSINESS";
var model = data$.load(idn);
if (model == null) {
    model = PSEntity("com.paradicshift.platform.automation.process.Category");
    model.identifier(idn);
}
model.text("name", "en", "Business");
data$.persist(model);

Fields & values

Set a scalar field (string, number, bool, …). value is an alias of val.

Read a field back; returns null if unset.

order.val("total", 149.99);
order.val("currency", "USD");
order.val("hidden", false);

context$.log("total = {}", order.val("total"));   // 149.99

Removes a field from the entity.

Store a named map on the entity. The value must be a PSScript map and is persisted in ArcadeDB as a queryable MAP, separately from scalar val fields.

Read a named entity map; returns the complete map, or null when the name is unset. Members are read with normal map indexing.

var shipping = {};
shipping["country"] = "TR";
shipping["priority"] = true;
order.map("shipping", shipping);

var savedShipping = order.map("shipping");
context$.log("country = {}", savedShipping["country"]);

Store a secret string. Secret values are encrypted at rest and must be used for credentials, tokens and other sensitive scalar data instead of val or map.

Read a secret string inside the running script; returns null when the secret is unset.

Multilingual text

Text fields are stored per locale, so a record can carry its name or description in many languages at once.

Set the localized text of a field. The field name and locale are auto-detected by order, so ("name", "en", …) and ("en", "name", …) both work.

Read a localized value back. Reading a locale that was never set is a runtime error, so guard or set it first.

component.text("name", "en", "Execute access");
component.text("name", "fa", "دسترسی اجرا");

GIS geometry

Entities can hold geospatial fields expressed as WKT strings. The geometry is parsed and validated when you set it.

Attach a geometry to a field from a WKT string. gisWkt is an alias.

Supported WKT geometry types include points, lines, polygons and their multi-variants:

e.gis("location", "POINT(%f %f)".formatted(lon, lat));
e.gis("area_1",   "POLYGON((%f %f, %f %f, %f %f, %f %f, %f %f))"
                  .formatted(lon, lat, lon2, lat, lon2, lat2, lon, lat2, lon, lat));
e.gis("path",     "LINESTRING(%f %f, %f %f, %f %f)"
                  .formatted(lon, lat, lon2, lat2, lon3, lat3));

Reads a geometry field back as a WKT string.

Reads a geometry field back as a GeoData object, ready for the gis$ helpers.

Access control

Grant open access to the entity — useful for shared platform data such as categories and model properties.

Open a specific kind of access (for example "list") without granting everything.

Persisting & linking

Saving, deleting and relating entities is done through data$ (see System objects). An entity also exposes a convenience delete.

data$.persist(subCat);
data$.link(subCat, model, "IN_PARENT_CATEGORY");

PSEntityQuery

Build a read query against a base class, chaining select clauses (what to return), filter clauses (which rows) and traversal clauses (follow relations). Pass the finished query to data$.query().

var q = PSEntityQuery("com.domain.commerce.Order")
            .selectId()
            .selectVal("total")
            .selectMapValue("shipping", "country")
            .filterVal("currency", "equals", "USD")
            .filterVal("total", "greater_than", 100)
            .filterMap("shipping", "priority", "equals", true);

var rows = data$.query(q);

Select clauses

Filter clauses

Traversal

Filter operators

The comparison operator in a filter is given as a string:

Published queries

A query designed and published in the Designer is run by uid instead of being built in code. Pass its parameters as a map, or add them one at a time; the result is read with data$.query exactly like a PSEntityQuery.

Sets one parameter and returns the query, so calls can be chained.

Adds a parameter without replacing the ones already set.

Replaces every parameter with the given map.

var params = {};
params["email"]   = "[email protected]";
params["_locale"] = context$.getLocale();
params["_limit"]  = 100;

var query = PSEntityQueryModel("QUERY_BY_EMAIL", params);
query = query.param("active", true);
var rows = data$.query(query);

Feeding an iteration

Converts query result rows into the map shape workflow$.iterate expects, taking the item id from one column and its label from another.

var rows  = data$.query(PSEntityQueryModel("ACTIVE_CASES", {}));
var items = data$.toIterationMap(rows, "id", "name");
var current = workflow$.iterate(items);

context$.log("processing {}", param$["iterationItem"]);