Datasets

Declarative data integration system mapping Cloud spreadsheets and tables directly into Engine Operator properties.
Published: 7/10/2026

Aircada Cloud Datasets represent dynamic external data tables (such as parts catalogs, colorways, or localized copy). Engine Operators bind to these datasets declaratively using the @DatasetMapping decorator, allowing automatic row fetching and property mapping without manual API scripts.

Pattern 1: Option Sets (Configurators)#

Preferred pattern for product configurators using the auto-generated OptionsRegistry.

The Engine automatically derives the correct datasetId and listens to the correct Twin-Proxy Vault state changes.

The @Property decorator on the trigger key is optional; use it only if you want the Row ID to be visible in the Visual Studio panel.

typescript
import { DatasetMapping, Operator, StringProperty } from "@aircada/spec";
import { OptionsRegistry } from "../registry/options.generated";

@Operator({ name: "Material Controller" })
export class MaterialController {
    // 1. TARGET PROPERTY (Receives the data)
    @StringProperty
    carColor: string = "#ffffff";

    // 2. TRIGGER PROPERTY (The Binding)
    @DatasetMapping({
        optionSet: OptionsRegistry.BALL_O_STEEL.sets.SIMPLECOLORS,
        mapping: {
            carColor: "color" // Class Property : Dataset Column
        }
    })
    @StringProperty
    activeColorId: string = "";
}

Pattern 2: Standard Datasets & Custom Events#

Ideal for e-commerce logic such as dynamic pricing, product specifications, or localized marketing content driven by external catalogs.

Use explicit datasetId and onEvent bindings. When the specified event fires with a Row ID payload, the Engine fetches the row and maps the data.

The trigger property only requires a decorator if you want to expose the last applied Row ID string in the Studio UI.

typescript
import { DatasetMapping, Operator, FloatProperty, StringProperty } from "@aircada/spec";

@Operator({ name: "Product Info Controller" })
export class ProductInfoController {
    @FloatProperty
    price: number = 0.00;

    @DatasetMapping({
        datasetId: "E_COMMERCE_CATALOG",
        onEvent: "PRODUCT_SELECTED",
        mapping: { price: "price" }
    })
    activeProductId: string = "";
}