Chart Templates¶

Charts are worksheet configurations. Primitive charts use shelves, marks, and encodings directly. Template charts use a high-level companion object so agents can ask for a Tableau idiom without knowing the generated shelf and XML shape.

Template Dispatch¶

Most template marks require a same-named object on the worksheet. When a template owns the generated shelves, leave rows and cols empty or omitted as shown by the fixture for that template.

Worksheet `mark`	Companion field	Required?	Notes
`bar`, `line`, `area`, `text`, `circle`, `square`, `shape`	none	No	Use `rows`, `cols`, and `encodings` directly.
`stacked_bar`	none	No	Uses ordinary shelves plus a Color encoding.
`pie`	none	No	Primitive mark; requires `encodings.wedge_size`.
`gantt`	none	No	Primitive mark; requires `encodings.duration`.
`treemap`	none	No	Primitive mark; requires `encodings.tile_size` or the historical `treemap` template surface in older fixtures.
`histogram`	`histogram`	Yes	Generates bins and histogram shelves.
`packed_bubble`	`packed_bubble`	Yes	Generates packed bubble fields and label/color defaults.
`box_plot`	`box_plot`	Yes	Generates box plot from a dimension and measure.
`combo`	`combo`	Yes	Generates a two-layer bar/line dual-axis view.
`bullet_graph`	`bullet_graph`	Yes	Generates a measure plus target comparison.
`sparkline`	`sparkline`	Yes	Generates a compact time-series line.
`pareto`	`pareto`	Yes	Generates ordered bars plus running percent line.
`slope`	`slope`	Yes	Generates endpoint comparison by series.
`population_pyramid`	`population_pyramid`	Yes	Generates mirrored bars by side/category.
`bump`	`bump`	Yes	Generates rank-over-time lines.
`control_chart`	`control_chart`	Yes	Generates center, upper, and lower reference lines.
`waterfall`	`waterfall`	Yes	Generates running bars for incremental contribution.
`donut`	`donut`	Yes	Generates a donut-style pie view.
`candlestick`	`candlestick`	Yes	Generates OHLC marks from date/open/high/low/close measures.

Common Field Shapes¶

Shape	Fields	Values
Field reference	string	`[Datasource].[Field]`
Date item	`field`, `date_part`	`date_part`: `month`, `quarter`, `year`, `month_trunc`, `week_trunc`, `year_trunc`
Aggregate item	`field`, `aggregation`	General aggregations: `avg`, `count`, `count_distinct`, `max`, `min`, `sum`
Template measure	`field`, `aggregation`	Template-specific aggregation allowlist below.

Template Measures¶

Template field	Allowed `aggregation` values
`combo.measure`, `bullet_graph.measure`, `bullet_graph.target`, `bump.measure`, `control_chart.measure`, `control_chart.limits.*`, `waterfall.measure`, `donut.measure`	`avg`, `sum`
`pareto.measure`, `slope.measure`	`avg`, `count`, `count_distinct`, `sum`
`population_pyramid.measure`	`sum`
`candlestick.open`, `candlestick.high`, `candlestick.low`, `candlestick.close`	`avg`, `max`, `min`, `sum`
`histogram.bin_size`	Positive number, not an aggregate object
`packed_bubble.size`, `box_plot.measure`, `sparkline.measure`	General aggregate item

Primitive Examples¶

[
  {
    "name": "Sales Bars",
    "datasource": "Orders",
    "rows": ["[Orders].[Category]"],
    "cols": [
      {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      }
    ],
    "mark": "bar"
  },
  {
    "name": "Monthly Sales",
    "datasource": "Orders",
    "cols": [
      {
        "field": "[Orders].[Order Date]",
        "date_part": "month_trunc"
      },
      {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      }
    ],
    "mark": "line"
  },
  {
    "name": "Sales Share",
    "datasource": "Orders",
    "mark": "pie",
    "encodings": {
      "color": "[Orders].[Category]",
      "wedge_size": {
        "field": "[Orders].[Sales]",
        "aggregation": "sum"
      }
    }
  }
]

Histogram¶

Field	Type	Required	Values	Description
`field`	string	Yes	Numeric field ref	Source measure to bin.
`bin_size`	number	Yes	`> 0`	Bin width.

{
  "name": "Sales Histogram",
  "datasource": "Orders",
  "mark": "histogram",
  "histogram": {
    "field": "[Orders].[Sales]",
    "bin_size": 100
  }
}

Packed Bubble¶

Field	Type	Required	Values	Description
`dimension`	string	Yes	Dimension field ref	Bubble category.
`size`	object	Yes	Aggregate item	Bubble size.

{
  "name": "Category Bubbles",
  "datasource": "Orders",
  "mark": "packed_bubble",
  "packed_bubble": {
    "dimension": "[Orders].[Sub-Category]",
    "size": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Box Plot¶

Field	Type	Required	Values	Description
`dimension`	string	Yes	Dimension field ref	Grouping dimension.
`measure`	object	Yes	Aggregate item	Distribution measure.

{
  "name": "Profit Box Plot",
  "datasource": "Orders",
  "mark": "box_plot",
  "box_plot": {
    "dimension": "[Orders].[Segment]",
    "measure": {
      "field": "[Orders].[Profit]",
      "aggregation": "sum"
    }
  }
}

Combo / Dual Axis¶

Field	Type	Required	Values	Description
`axis`	string	Yes	`cols`	Axis where the shared dimension is placed.
`dimension`	string or date item	Yes	Field ref or date item	Shared axis dimension.
`layers`	array	Yes	Exactly two items: one `bar`, one `line`	Generated dual-axis layers. Either order is allowed.
`synchronized_axis`	boolean	No	`true`, `false`	Emits synchronized dual-axis metadata.
`axis_titles`	object	No	`primary`, `secondary`	Optional axis title strings. At least one key is required when provided.

Layer object:

Field	Type	Required	Values	Description
`mark`	string	Yes	`bar`, `line`	Layer mark.
`measure`	object	Yes	Template measure	Measure drawn by the layer.
`encodings`	object	No	`size`, `tooltip`	Optional layer-specific aggregate encodings.

{
  "name": "Sales Profit Combo",
  "datasource": "Orders",
  "mark": "combo",
  "combo": {
    "axis": "cols",
    "dimension": {
      "field": "[Orders].[Order Date]",
      "date_part": "year_trunc"
    },
    "synchronized_axis": true,
    "axis_titles": {
      "primary": "Profit",
      "secondary": "Sales"
    },
    "layers": [
      {
        "mark": "bar",
        "measure": {
          "field": "[Orders].[Profit]",
          "aggregation": "sum"
        }
      },
      {
        "mark": "line",
        "measure": {
          "field": "[Orders].[Sales]",
          "aggregation": "sum"
        },
        "encodings": {
          "tooltip": {
            "field": "[Orders].[Quantity]",
            "aggregation": "sum"
          }
        }
      }
    ]
  }
}

Bullet Graph¶

Field	Type	Required	Values	Description
`dimension`	string	Yes	Dimension field ref	Row/category dimension.
`measure`	object	Yes	`avg` or `sum`	Actual measure.
`target`	object	Yes	`avg` or `sum`	Target measure.
`label`	string	No	Display text	Optional label text.

{
  "name": "Sales Bullet",
  "datasource": "Orders",
  "mark": "bullet_graph",
  "bullet_graph": {
    "dimension": "[Orders].[Category]",
    "measure": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    },
    "target": {
      "field": "[Orders].[Target]",
      "aggregation": "sum"
    }
  }
}

Sparkline¶

Field	Type	Required	Values	Description
`time`	string or date item	Yes	Field ref or date item	Time axis.
`measure`	object	Yes	Aggregate item	Line measure.
`partition`	string	No	Dimension field ref	Creates small multiples/partitioning.

{
  "name": "Category Sparklines",
  "datasource": "Orders",
  "mark": "sparkline",
  "sparkline": {
    "time": {
      "field": "[Orders].[Order Date]",
      "date_part": "month_trunc"
    },
    "measure": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    },
    "partition": "[Orders].[Category]"
  }
}

Pareto¶

Field	Type	Required	Values	Description
`dimension`	string	Yes	Dimension field ref	Ordered contribution dimension.
`measure`	object	Yes	`avg`, `count`, `count_distinct`, `sum`	Contribution measure.

{
  "name": "Sales Pareto",
  "datasource": "Orders",
  "mark": "pareto",
  "pareto": {
    "dimension": "[Orders].[Sub-Category]",
    "measure": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Slope And Bump¶

Slope object:

Field	Type	Required	Values	Description
`endpoint`	string or date item	Yes	Field ref or date item	Start/end axis field.
`measure`	object	Yes	`avg`, `count`, `count_distinct`, `sum`	Value compared at endpoints.
`series`	string	Yes	Dimension field ref	Line grouping field.

Bump object:

Field	Type	Required	Values	Description
`time`	string or date item	Yes	Field ref or date item	Time axis.
`measure`	object	Yes	`avg`, `sum`	Ranking measure.
`series`	string	Yes	Dimension field ref	Ranked line grouping field.

{
  "name": "Category Rank Bump",
  "datasource": "Orders",
  "mark": "bump",
  "bump": {
    "time": {
      "field": "[Orders].[Order Date]",
      "date_part": "year"
    },
    "series": "[Orders].[Category]",
    "measure": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Population Pyramid¶

Field	Type	Required	Values	Description
`category`	string	Yes	Dimension field ref	Vertical category, such as age band.
`side`	string	Yes	Dimension field ref	Side/group field, such as gender.
`left_values`	array	Yes	One or more literal members	Members from `side` rendered on the left. Values cannot contain quotes or backslashes.
`measure`	object	Yes	`sum` only	Bar length measure.

{
  "name": "Customer Pyramid",
  "datasource": "Orders",
  "mark": "population_pyramid",
  "population_pyramid": {
    "category": "[Orders].[Age Band]",
    "side": "[Orders].[Gender]",
    "left_values": ["Female"],
    "measure": {
      "field": "[Orders].[Customers]",
      "aggregation": "sum"
    }
  }
}

Control Chart¶

Field	Type	Required	Values	Description
`time`	string or date item	Yes	Field ref or date item	Time axis.
`measure`	object	Yes	`avg`, `sum`	Observed measure.
`series`	string	No	Dimension field ref	Optional partition field.
`limits`	object	Yes	`center`, `upper`, `lower`	Control limit measure objects.

Limit object:

Field	Type	Required	Values	Description
`field`	string	Yes	Field ref	Limit measure field.
`aggregation`	string	Yes	`avg`, `sum`	Limit aggregation.
`label`	string	No	Display text	Reference-line label.

{
  "name": "Defect Rate Control Chart",
  "datasource": "Orders",
  "mark": "control_chart",
  "control_chart": {
    "time": {
      "field": "[Orders].[Period]",
      "date_part": "month_trunc"
    },
    "measure": {
      "field": "[Orders].[Defect Rate]",
      "aggregation": "avg"
    },
    "limits": {
      "center": {
        "field": "[Orders].[Center]",
        "aggregation": "avg"
      },
      "upper": {
        "field": "[Orders].[UCL]",
        "aggregation": "avg",
        "label": "UCL <Value>"
      },
      "lower": {
        "field": "[Orders].[LCL]",
        "aggregation": "avg",
        "label": "LCL <Value>"
      }
    }
  }
}

Waterfall And Donut¶

Waterfall object:

Field	Type	Required	Values	Description
`dimension`	string	Yes	Dimension field ref	Ordered contribution dimension.
`measure`	object	Yes	`avg`, `sum`	Contribution measure.

Donut object:

Field	Type	Required	Values	Description
`dimension`	string	Yes	Dimension field ref	Slice field.
`measure`	object	Yes	`avg`, `sum`	Slice size measure.

{
  "name": "Sales Donut",
  "datasource": "Orders",
  "mark": "donut",
  "donut": {
    "dimension": "[Orders].[Category]",
    "measure": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Candlestick¶

Field	Type	Required	Values	Description
`date`	string or date item	Yes	Field ref or date item	Date axis.
`open`	object	Yes	`avg`, `max`, `min`, `sum`	Opening value.
`high`	object	Yes	`avg`, `max`, `min`, `sum`	High value.
`low`	object	Yes	`avg`, `max`, `min`, `sum`	Low value.
`close`	object	Yes	`avg`, `max`, `min`, `sum`	Closing value.

{
  "name": "Price Candlestick",
  "datasource": "Orders",
  "mark": "candlestick",
  "candlestick": {
    "date": "[Orders].[Trade Date]",
    "open": {
      "field": "[Orders].[Open]",
      "aggregation": "avg"
    },
    "high": {
      "field": "[Orders].[High]",
      "aggregation": "max"
    },
    "low": {
      "field": "[Orders].[Low]",
      "aggregation": "min"
    },
    "close": {
      "field": "[Orders].[Close]",
      "aggregation": "avg"
    }
  }
}