dash

dash, keyword

The dash keyword marks assignments evaluated during the interactive phase. Dash variables exist only in the browser, and are recomputed when the user changes inputs.

Examples

read upload "values" as Submitted with
  Id : text
  Value : number

table T[id] = with
  [| as id, as Min, as Max |]
  [| "A", 1, 5 |]
  [| "B", 0, 10 |]

mutable T.Value = single(Submitted.Value) by Submitted.Id at T.id default 0

dash T.IsValid = T.Min <= T.Value and T.Value <= T.Max
dash T.Color = if T.IsValid then "default" else "red"

show table "Values" editable: "values" with
  T.id { columnReadOnly: true }
  T.Value mutable { cellBackground: #[T.Color] }
  T.Min { columnReadOnly: true }
  T.Max { columnReadOnly: true }

Scalar aggregations can update totals as the viewer edits a table:

read upload "orders" as Submitted with
  Item : text
  Proposed : number

table Orders dash 5k = with
  [| as Item, as Qty |]
  [| "Shirt", 10 |]
  [| "Hat", 30 |]

mutable Orders.Proposed = single(Submitted.Proposed) by Submitted.Item at Orders.Item default Orders.Qty
dash total = sum(Orders.Proposed)
dash average = avg(Orders.Proposed)

show table "Order quantities" a1d3 editable:"orders" with
  Orders.Item { columnReadOnly: true }
  Orders.Proposed mutable

show scalar "Total quantity" a4b4 with total
show scalar "Average quantity" c4d4 with average

Initially, the total is 40 and the average is 20. Editing a quantity updates both values in the browser without starting another run.

Scalar aggregations

Dash expressions support sum, avg, count, any, and all over a dash-sized table when the result is a scalar. Numeric quantities can be summed or averaged; Boolean vectors can be counted or reduced with any and all. count counts true values, not all rows of a Boolean vector.

The when option filters contributing rows, and default specifies the result for an empty group, including default fail. These browser-side aggregations do not support grouped results on another table or scan. The source must satisfy the dash-sized table limit described below.

Dash-sized tables

A vector-valued dash expression can broadcast from one table to another when the source and destination tables are declared as dash-sized. Put dash and a maximum size after the table name:

read upload "values" as T dash 5k with
  Label : text
  Count : number
  Enabled : boolean

table Details dash 5k = extend.range(T.Count)

mutable T.IsEnabled = T.Enabled
dash Details.Color = if T.IsEnabled then "green" else "red"

show table "Details" with
  Details.N { cellBackground: #[Details.Color] }
  T.Label

The maximum size of a dash-sized table is 5,000 lines. Declaring dash without a compatible maximum fails when the inferred table maximum is larger. Scalar dash values can broadcast to a dash-sized table without a dash-sized source table.

The in operator can check a mutable value against all values in a dash-sized table. For example, dash Items.IsValid = Items.Value in ValidValues.Value updates the check when the user edits Items.Value. The result can drive conditional cell styling, as in the example above.

The right-hand table must fit within the 5,000-line limit so that the full set is available in the browser. Declare it with dash 5k, or use a table whose inferred maximum already satisfies that limit, such as a short comprehension. This interactive form compares individual values, not tuples.

Remarks

Dash expressions can use number, boolean, text, date, week, month, markdown, any enum, and tuples of those types. They support comparisons, arithmetic, boolean logic, if then else, match, in, interpolation, broadcasting, and pure functions marked as dash.

A dash assignment cannot depend on itself, directly or indirectly. This also applies when the expression is evaluated over slices.

Dash variables are rejected in non-dash contexts such as write, where, and non-dash assignments, except for system-defined tiny tables.

Dash expressions can be displayed by browser-evaluated tiles such as gauge. Tiles that still use server-side matrix evaluation reject dash expressions in their with columns. The current rejecting tile types are assert, histogram, menu, plot, scatter, slicepicker, slicetree, treemap, and upload.

When a tile rejects such an expression, compilation fails with a message of the form:

'dash' expressions are not supported as columns in 'show upload'.