Analytics¶

Analytics includes calculated fields, formula table calculations, LOD metadata, semantic z-scores, worksheet forecasts, trend lines, reference lines, reference distributions, and shelf-level quick table calculations. Keep these definitions semantic and reusable; Superstore-shaped analytics should still compile for arbitrary datasets with equivalent fields.

Calculated Field Object¶

Calculated fields are declared as datasource columns with calculation.

{
  "name": "Profit Ratio",
  "role": "measure",
  "type": "quantitative",
  "datatype": "real",
  "calculation": {
    "formula": "SUM([Profit]) / SUM([Sales])",
    "references": ["Profit", "Sales"]
  }
}

Field	Type	Required	Values	Description
`formula`	string	Formula calculations	Tableau formula text	Normal calculated field formula.
`references`	array	Formula calculations	Field refs or parameter refs	Explicit dependencies used by the formula. Use `[]` only for literal-only formulas.
`table_calculation`	object	Formula table calculations	Table calculation metadata	Required when `formula` uses supported table-calculation functions. Mutually exclusive with `lod`.
`lod`	object	LOD calculations	LOD object	Required metadata for Desktop-backed LOD formulas. Mutually exclusive with `table_calculation`.
`z_score`	object	Z-score helper	Z-score object	Semantic helper form. Mutually exclusive with `formula`, `references`, `table_calculation`, and `lod`.

Calculation columns still need normal column metadata: name, role, type, and datatype. For z-scores, the calculated column must be a real quantitative measure.

Formula References¶

Reference form	Use
`Profit`	Same-datasource leaf name.
`[Profit]`	Same-datasource bracketed leaf name.
`[Orders].[Profit]`	Same-datasource qualified name.
`[Targets].[Sales Target]`	Cross-datasource qualified name. Worksheets using the calculation must list `Targets` in `secondary_datasources`.
`[Parameters].[Sales Target]`, `Sales Target`, `[Sales Target]`	Declared workbook parameter references.

Cross-datasource calculations are limited to normal formula fields. LOD metadata, z-score helpers, and table-calculation ordering_field references remain same-datasource only.

{
  "name": "Target Gap",
  "role": "measure",
  "type": "quantitative",
  "datatype": "real",
  "calculation": {
    "formula": "SUM([Sales]) - SUM([Targets].[Sales Target])",
    "references": ["Sales", "[Targets].[Sales Target]"]
  }
}

Worksheet using a cross-datasource calculation:

{
  "name": "Target Gap",
  "datasource": "Orders",
  "secondary_datasources": ["Targets"],
  "rows": ["[Orders].[Category]"],
  "cols": ["[Orders].[Target Gap]"],
  "mark": "bar"
}

Formula Table Calculation Metadata¶

Field	Type	Required	Values	Description
`compute_using`	string	Yes	`table_across`, `table_down`, `field`	Addressing direction. `field` requires `ordering_field`.
`ordering_field`	string	With `compute_using: "field"`	Same-datasource physical dimension field	Specific-dimension addressing field.

Supported formula tokens are intentionally narrow:

Function token	Use
`INDEX()`	Index table calculation.
`RUNNING_SUM(...)`	Running total.
`LOOKUP(...)`	Difference or percent-difference from another row.
`WINDOW_AVG(...)`	Moving average.
`WINDOW_STDEV(...)`	Z-score style formulas.
`WINDOW_SUM(...)`	Cumulative percent, including Pareto support.

{
  "name": "Running Sales",
  "role": "measure",
  "type": "quantitative",
  "datatype": "real",
  "calculation": {
    "formula": "RUNNING_SUM(SUM([Sales]))",
    "references": ["Sales"],
    "table_calculation": {
      "compute_using": "table_across"
    }
  }
}

Specific-dimension addressing:

{
  "formula": "RUNNING_SUM(SUM([Sales]))",
  "references": ["Sales"],
  "table_calculation": {
    "compute_using": "field",
    "ordering_field": "[Orders].[Category]"
  }
}

LOD Metadata¶

lod.kind must match the Tableau formula keyword.

Field	Type	Required	Values	Description
`kind`	string	Yes	`fixed`, `include`, `exclude`	LOD calculation kind.

{
  "name": "Order Profitable?",
  "role": "dimension",
  "type": "nominal",
  "datatype": "boolean",
  "calculation": {
    "formula": "{ FIXED [Order ID] : SUM([Profit]) } > 0",
    "references": ["Order ID", "Profit"],
    "lod": {
      "kind": "fixed"
    }
  }
}

{
  "name": "Segment Profit Positive?",
  "role": "dimension",
  "type": "nominal",
  "datatype": "boolean",
  "calculation": {
    "formula": "{ EXCLUDE [Segment] : SUM([Profit]) } > 0",
    "references": ["Segment", "Profit"],
    "lod": {
      "kind": "exclude"
    }
  }
}

Cross-datasource LOD expressions and formulas with multiple LOD brace expressions are out of scope.

Z-Score Helper¶

Field	Type	Required	Values	Description
`field`	string	Yes	Physical numeric measure name/ref	Source measure.
`aggregation`	string	Yes	`avg`, `sum`	Source aggregation.
`compute_using`	string	Yes	`table_across`, `table_down`, `field`	Table calculation addressing.
`ordering_field`	string	With `compute_using: "field"`	Same-datasource dimension field ref	Specific-dimension addressing field.

{
  "name": "Sales Z-Score",
  "caption": "Sales Z-Score",
  "role": "measure",
  "type": "quantitative",
  "datatype": "real",
  "calculation": {
    "z_score": {
      "field": "Sales",
      "aggregation": "sum",
      "compute_using": "field",
      "ordering_field": "[Orders].[Category]"
    }
  }
}

Shelf Quick Table Calculations¶

These are shelf item objects used in rows[], cols[], or supported mark detail encodings.

Field	Type	Required	Values	Description
`table_calculation.type`	string	Yes	`rank`, `percent_total`	Quick table calculation kind.
`table_calculation.compute_using`	string	Yes	`table_across`, `table_down`, `field`	Addressing. `field` is supported for percent total and requires `ordering_field`.
`table_calculation.ordering_field`	string	With `compute_using: "field"`	Primary datasource field ref	Specific-dimension addressing field.
`table_calculation.source`	object	Yes	Aggregate shelf item	Source aggregate.

{
  "table_calculation": {
    "type": "rank",
    "compute_using": "table_down",
    "source": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

{
  "table_calculation": {
    "type": "percent_total",
    "compute_using": "field",
    "ordering_field": "[Orders].[Customer Name]",
    "source": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Forecast Object¶

Forecasts live on worksheets[].forecast.

Field	Type	Required	Values	Description
`range`	object	Yes	Forecast range object	Date range to forecast through.
`confidence_level`	number	No	`> 0` and `< 100`	Prediction confidence level.
`fill`	string	No	`missing`, `zero`	Missing-data fill behavior.
`ignore_last`	integer	No	`>= 0`	Number of trailing periods to ignore.
`prediction_bands`	boolean	No	`true`, `false`	Show prediction bands.
`season`	string	No	`additive`, `multiplicative`, `none`	Seasonality model.
`trend`	string	No	`additive`, `multiplicative`, `none`	Trend model.

Forecast range:

Field	Type	Required	Values	Description
`max`	string	Yes	ISO date	Forecast end.
`min`	string	No	ISO date	Forecast start.

{
  "forecast": {
    "confidence_level": 95,
    "fill": "missing",
    "ignore_last": 0,
    "prediction_bands": true,
    "range": {
      "max": "2026-12-31"
    },
    "season": "additive",
    "trend": "additive"
  }
}

Trend Line Object¶

Trend lines live on worksheets[].trend_line.

Field	Type	Required	Values	Description
`fit`	string	No	`linear`	Trend model.
`exclude_intercept`	boolean	No	`true`, `false`	Excludes intercept.
`confidence_bands`	boolean	No	`true`, `false`	Shows confidence bands.
`exclude_color`	boolean	No	`true`, `false`	Excludes Color partitions.
`instant_analytics`	boolean	No	`true`, `false`	Tableau instant analytics flag.
`tooltips`	boolean	No	`true`, `false`	Trend line tooltips.
`style`	object	No	Trend line style object	Stroke and visibility styling.

Trend line style:

Field	Type	Values
`stroke_size`	integer	`> 0`
`line_pattern`	string	`solid`, `dashed`, `dotted`
`stroke_color`	string	`#RRGGBB`
`line_visibility`	string	`on`, `off`

{
  "trend_line": {
    "fit": "linear",
    "confidence_bands": true,
    "tooltips": true,
    "style": {
      "stroke_size": 2,
      "line_pattern": "solid",
      "stroke_color": "#4E79A7",
      "line_visibility": "on"
    }
  }
}

Reference Lines¶

Reference lines live on worksheets[].reference_lines[]. The axis aggregate must already be present on rows or cols.

Field	Type	Required	Values	Description
`axis`	object	Yes	Aggregate shelf item	Axis to annotate.
`value`	object	One of `value` or `value_parameter`	Aggregate shelf item	Measure used for reference value.
`value_parameter`	string	One of `value` or `value_parameter`	Quantitative parameter name	Parameter-backed reference value.
`formula`	string	Yes	`average`, `max`, `median`, `min`	Reference formula.
`scope`	string	Yes	`per_cell`, `per_pane`, `per_table`	Reference scope.
`label`	string	No	Non-empty	Custom label.
`percentage_bands`	array	No	Percentages `> 0` and `<= 100`	Adds percentage bands around the line.

{
  "reference_lines": [
    {
      "axis": {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      },
      "value_parameter": "Sales Target",
      "formula": "average",
      "scope": "per_table",
      "label": "Target <Value>",
      "percentage_bands": [50, 75, 100]
    }
  ]
}

Reference Distributions¶

Reference distributions live on worksheets[].reference_distributions[].

Field	Type	Required	Values	Description
`axis`	object	Yes	Aggregate shelf item	Axis to annotate.
`value`	object	One of `value` or `value_parameter`	Aggregate shelf item	Measure used for distribution value.
`value_parameter`	string	One of `value` or `value_parameter`	Quantitative parameter name	Parameter-backed value.
`formula`	string	Yes	`average`	Distribution formula.
`scope`	string	Yes	`per_cell`, `per_pane`, `per_table`	Distribution scope.
`percentages`	array	Yes	Percentages `> 0` and `<= 100`	Distribution cutoffs.

{
  "reference_distributions": [
    {
      "axis": {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      },
      "value": {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      },
      "formula": "average",
      "scope": "per_cell",
      "percentages": [60, 80]
    }
  ]
}

Full Analytics Worksheet Example¶

{
  "name": "Sales Analytics",
  "datasource": "Orders",
  "rows": ["[Orders].[Category]"],
  "cols": [
    {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  ],
  "mark": "bar",
  "reference_lines": [
    {
      "axis": {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      },
      "value": {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      },
      "formula": "average",
      "scope": "per_table",
      "label": "Average <Value>"
    }
  ],
  "trend_line": {
    "fit": "linear",
    "confidence_bands": true
  }
}