Data - Expression

Type identifier: data:expression Category: Data Operations

Description

Evaluates a mathematical or logical expression with variables. Supports arithmetic, string manipulation, date/time operations, similarity functions, and array operations. Use this node for calculations, transformations, and complex data logic.

Input Handles

Input Handle Details

Variable Handles

Input handles are dynamically generated based on the variables configuration. Each variable creates a corresponding input handle using the variable's name as the handle ID.

• Type: Defined by each variable's schema configuration

• Notes:

  • Only variables referenced in the expression need to be connected
  • Unconnected required variables will cause errors
  • Variable names must match [a-zA-Z0-9_] pattern

Output Handles

Output Handle Details

result

• Type: Defined by the result schema configuration

• Notes:

  • Result is validated against the configured result schema when the schema is coercible
  • Loosely-typed result schemas (for example: duration, empty object schemas, and arrays of empty object schemas) keep the raw evaluated value

Configuration Options

Configuration Details

variables

• Type: Array of variable definitions

• Notes:

  • Each variable defines an input handle
  • Variable name must be alphanumeric with underscores
  • Variable name is used in the expression and as handle ID

expression

• Type: string

• Notes:

  • In expression mode (default), uses expr-eval syntax
  • In js mode, uses standard JavaScript evaluated inside a secure sandbox (see JavaScript Mode)
  • Supports extended functions for dates, strings, and vectors
  • Variables are referenced by their name

JavaScript Mode

When mode is set to "js", the expression is evaluated as a standard JavaScript expression inside an isolated sandbox.

Available Bindings

• All declared variables are exposed as global identifiers using their name.
• The same shared helper functions described under Supported Functions (such as dateParse, format, addDuration, cosineSimilarity, jsonParse, or levenshtein) are available as global functions.
• A Temporal global provides the deterministic date/time API described below.

Temporal API

The following static APIs are available:

The following instance APIs are available:

Standard scalar properties are available for each supported type. These include date and time fields, ISO calendar fields such as dayOfWeek, weekOfYear, and daysInMonth, timezone fields such as offset and timeZoneId, epochMilliseconds, and duration fields such as hours, sign, and blank. ZonedDateTime.epochSeconds is also available as a convenience.

from, with, arithmetic, difference, rounding, conversion, and string formatting methods accept their standard Temporal string, field object, and options object forms unless listed under Temporal Limitations.

const date = Temporal.PlainDate.from("2024-03-15");
const delivery = date.toZonedDateTime({
  timeZone: "Australia/Melbourne",
  plainTime: "14:30",
});

delivery.add({ days: 2 }).toInstant();

Temporal Limitations

• Temporal.PlainYearMonth and Temporal.PlainMonthDay are not supported result types. Their constructors and conversion methods are not available.
• JavaScript constructors such as new Temporal.Instant(...) are not available. Use static from methods.
• epochNanoseconds and Temporal.Instant.fromEpochNanoseconds are not available. Use epochMilliseconds and fromEpochMilliseconds.
• toLocaleString is not available.
• toJSON is not available.
• valueOf() returns an ISO 8601 string. Native Temporal valueOf() throws instead.
• When Instant.until, Instant.since, ZonedDateTime.until, or ZonedDateTime.since is called without options, the default largestUnit is "hour". Pass an options object to select another unit.
• Temporal objects use the ISO 8601 calendar in normal Flow data. Calendar conversion methods are exposed for compatibility, but non-ISO Temporal values may not pass the configured date result schema.
• Temporal.add(...) is not a Temporal API and is not exposed. Call instant.add(...), date.add(...), or another instance method.

Resource Limits

Each JavaScript evaluation is constrained to:

When a limit is exceeded the node triggers the error handle with a DATA_EXPRESSION_EVALUATION_ERROR whose message describes the failure mode (such as interrupt, out of memory, or stack overflow).

Example

{
  "type": "data:expression",
  "data": {
    "label": "JS - Total With Tax",
    "mode": "js",
    "variables": [
      { "name": "price", "type": "number" },
      { "name": "taxRate", "type": "number" }
    ],
    "result": { "name": "total", "type": "number" },
    "expression": "price * (1 + taxRate)"
  }
}

Supported Functions

Arithmetic

String Functions

String Similarity

levenshtein and longestCommonSubstring accept inputs of at most 2,500 characters each and throw an error for longer strings.

Date/Time Functions

Duration units: years, months, weeks, days, hours, minutes, seconds, milliseconds

dateParse(...) first attempts strict Temporal parsing and then falls back to natural-language parsing for phrases such as "1 week from now". When timeZone is provided, the parsed value is normalised to that timezone and returned as a zoned date-time value.

format(...) accepts an optional timeZone argument. When provided, the input is formatted using that timezone's wall-clock time, which is useful for DST-aware display such as format(appointmentUtc, "hh:mm aaa cccc do MMMM, yyyy", "Australia/Melbourne").

Array Functions

Vector Functions

JSON Functions

Example with dynamic keys:

get(get(get(get(get(jsonParse(result), "calendars"), calendarId), "busy"), 0), "start")

Comparison

Behaviour

Execution Flow

1. Validates all referenced variables are declared
2. Validates all referenced variables have connected edges
3. Evaluates the expression with the connected variable values
4. Validates/coerces result against the configured result schema when supported
5. Returns result or triggers error

Error Handling

Examples

Simple Arithmetic

{
  "type": "data:expression",
  "data": {
    "label": "Calculate Total",
    "variables": [
      { "name": "price", "type": "number" },
      { "name": "quantity", "type": "number" }
    ],
    "result": { "name": "total", "type": "number" },
    "expression": "price * quantity"
  }
}

String Comparison

{
  "type": "data:expression",
  "data": {
    "label": "Check Similarity",
    "variables": [
      { "name": "input", "type": "string" },
      { "name": "reference", "type": "string" }
    ],
    "result": { "name": "similarity", "type": "number" },
    "expression": "levenshtein(input, reference, true)"
  }
}

Date Calculation

{
  "type": "data:expression",
  "data": {
    "label": "Add 7 Days",
    "variables": [{ "name": "startDate", "type": "date" }],
    "result": { "name": "endDate", "type": "date" },
    "expression": "addDuration(startDate, 7, 'days')"
  }
}

Date From String

{
  "type": "data:expression",
  "data": {
    "label": "Parse Date String",
    "variables": [{ "name": "startedAt", "type": "string" }],
    "result": { "name": "parsedDate", "type": "date", "includeTime": true },
    "expression": "dateParse(startedAt)"
  }
}

Date From String With Timezone

{
  "type": "data:expression",
  "data": {
    "label": "Parse Date String In Timezone",
    "variables": [
      { "name": "startedAt", "type": "string" },
      { "name": "timeZone", "type": "string" }
    ],
    "result": { "name": "parsedDate", "type": "date", "includeTime": true },
    "expression": "dateParse(startedAt, timeZone)"
  }
}

Date From Natural Language

{
  "type": "data:expression",
  "data": {
    "label": "Natural Language Date",
    "variables": [{ "name": "startedAt", "type": "string" }],
    "result": { "name": "parsedDate", "type": "date", "includeTime": true },
    "expression": "dateParse(startedAt)"
  }
}

Example input value for startedAt: "1 week from now"

Conditional Logic

{
  "type": "data:expression",
  "data": {
    "label": "Discount Price",
    "variables": [
      { "name": "price", "type": "number" },
      { "name": "isPremium", "type": "boolean" }
    ],
    "result": { "name": "finalPrice", "type": "number" },
    "expression": "isPremium ? price * 0.8 : price"
  }
}