Use Runtime Variables

Runtime variables let a quality check reference a value that is supplied when the scan runs, instead of hard-coding it in the check. A common use is a check filter that targets a reporting date or a business unit that changes from one scan to the next.

Related pages: Scan Settings · Scan API · Scan FAQ

How Variables Work

Write a variable in a check as a name inside double curly braces, for example {{ checked_date }}. When a scan runs, Qualytics replaces each variable with its value and then evaluates the check.

Variables are supported in:

• The check's Filter Clause.
• Rule properties that hold an expression, a filter, or a pattern, such as the expression of a Satisfies Expression check or the reference filter of an Aggregation Comparison check.
• Lists of text values, such as the list of an Expected Values check on a text field. Lists of numbers or of true/false values do not accept variables.

In the check editor, fields that accept variables highlight them as you type.

A check filter that uses a variable must still be a valid Spark SQL WHERE expression once the value is in place. For example:

transaction_date = {{ checked_date }}

Where Values Come From

A variable can get its value from two places. When the same variable is defined in both, the scan value wins:

Qualytics also provides built-in variables. A value you define with the same name as a built-in variable replaces it, so do not start your own variable names with _qualytics_.

Set Default Values on a Container

Step 1: Open the container's settings: click the vertical ellipsis next to the container in the datastore's list and select Settings. For a Computed Table, Computed File, or Computed Join, you can also use its add or edit form. See General Settings.

Step 2: In Additional Metadata, click the plus icon and add one row per variable. The key is the variable name (without the curly braces) and the value is what replaces it.

Step 3: Save. Every scan that includes this container now uses these values unless the scan supplies its own.

Supply Values for a Scan

Step 1: Open the Scan operation modal and continue to Scan Settings.

Step 2: Toggle Advanced Options on.

Step 3: In Scan Variables, add one row per variable you want to set or override for this scan.

Step 4: Run the scan, or save it as a schedule. Scheduled scans keep their Scan Variables and use them on every run.

Supply Values Through the API

Pass the values in the check_variables field 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
}

Scan schedules accept the same check_variables field. For the full payload reference, see API.

Write Values with Explicit Types

A value is inserted into the check exactly as you type it, so it must be valid SQL in that position. Include quotes and casts yourself:

You can also keep the quotes in the check itself, for example business_unit = '{{ unit }}', and supply the value without quotes (EMEA).

Built-in Variables

These variables are always available and do not need a value:

For an example that uses {{ _qualytics_self }}, see Satisfies Expression: How It Works.