Use Runtime Variables

Some advanced use cases require options that are not yet exposed in the UI but are available through the Qualytics API. Runtime variable assignment is one of them.

Runtime Variable Assignment

It is possible to reference a variable in a check definition (declared in double curly braces) and then assign that variable a value when a Scan operation is initiated. Variables are supported within any Spark SQL expression and are most commonly used in a check filter.

If a Scan is meant to assert a check with a variable, a value for that variable must be supplied as part of the Scan operation's check_variables property.

When using a variable inside a filter, the filter must be a valid Spark SQL WHERE expression.

For example, a check might include a filter:

transaction_date = {{ checked_date }}

For the Scan operation payload, users must apply explicit casting inside the check_variables section. Since variables may represent different data types (integer, string, timestamp, etc.), each variable must be cast to the correct type to avoid parsing or evaluation errors.

In this case, that value would be assigned by passing the following payload when calling /api/operations/run:

{
    "type": "scan",
    "datastore_id": 42,
    "container_names": ["my_container"],
    "incremental": true,
    "remediation": "none",
    "max_records_analyzed_per_partition": 0,
    "check_variables": {
        "checked_date": "TIMESTAMP '2026-05-15'"
    },
    "high_count_rollup_threshold": 10
}

For the full payload reference, see API.