Formula¶

The "formula" transform uses an expression to calculate and add a new field to each row.

Parameters¶

expr Required

Type: string

An expression string

as Required

Type: string

The (new) field where the computed value is written to

debounce

Type: number

Trailing-edge delay in milliseconds before requesting dataflow replay after a reactive expression dependency changes. Repeated changes restart the delay.

Parameter updates and incoming data are not delayed. Incoming batches use current parameter values, and a completed batch satisfies any pending reactive replay. The delay does not wait for independently scheduled lazy data loads.

Default value: no delay

description

Type: string

A description of the transform step. Can be used for documentation and agent context.

Example¶

Given the following data:

x	y
1	2
3	4

... and configuration:

{
  "type": "formula",
  "expr": "datum.x + datum.y",
  "as": "z"
}

A new field is added:

x	y	z
1	2	3
3	4	7

Using with Parameters¶

As expressions have access to parameters, they can be used to create dynamic visualizations. The following example uses a formula to calculate the sum of two sine waves with different wave lengths. The wave lengths are controlled by the a and b parameters.

Under the hood, when any of the parameters change, the formula transform finds the closest collector or data source in the data pipeline and triggers a re-propagation of the data, resulting in a re-evaluation of the formula expression.

Use debounce to delay this reactive replay until the dependencies have stopped changing for the specified number of milliseconds. It delays only dependency-triggered replay: parameter updates and new input data remain immediate. If an input batch completes during the delay, it uses current parameter values and makes the pending replay unnecessary. The delay does not wait for an independently scheduled lazy load. Place a collect transform before an expensive reactive formula to cache the rows used for replay.

{
  "description": "Formula transform example with parameters.",

  "params": [
    {
      "name": "a",
      "value": 200,
      "bind": { "input": "range", "min": 10, "max": 2000, "step": 1 }
    },
    {
      "name": "b",
      "value": 270,
      "bind": { "input": "range", "min": 10, "max": 2000, "step": 1 }
    }
  ],

  "data": {
    "sequence": { "start": 0, "stop": 1000, "as": "x" }
  },

  "transform": [
    {
      "type": "formula",
      "expr": "sin(datum.x * 2 * PI / a) + sin(datum.x * 2 * PI / b)",
      "as": "y"
    }
  ],

  "mark": "point",

  "encoding": {
    "size": { "value": 4 },
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "y", "type": "quantitative" }
  }
}