visualization-settings

Visualization: pick the chart, then set it

Two fields, set through question_write and mergeable per dashcard via dashboard_write's patch_dashcard:

• display — table, bar, line, area, row, pie, scalar, smartscalar, combo, pivot, funnel, map, scatter, waterfall, progress, gauge, sankey. Nothing else: an unknown value (bargraph, histogram, number) is accepted and renders nothing; scalar is the Number viz.
• visualization_settings — a map keyed per display (graph.*, pie.*, table.*, …). Nothing validates it: unknown or wrong-display keys are stored and ignored; a wrong binding renders blank or falls back to a table. Feedback is read-back, not errors.

Step 1 — display by data shape

• Single number → scalar; smartscalar for change vs previous period (needs a time breakout); gauge/progress for value vs target.
• Measure across categories → bar; row (horizontal) for long or many labels.
• Trend → line; area for stacked composition over time; combo for two related measures on unlike scales (never unrelated ones). Never scalar/pie for a trend.
• Part-to-whole → pie, ≤5 slices only; beyond that a sorted bar/row.
• Distribution → bar histogram (bin the field — learn("query-dialect"), binning).
• Correlation → scatter (third measure → bubble size).
• Contributions to a total → waterfall; stage drop-off → funnel; flow between nodes → sankey.
• Geographic → map (region/choropleth, or pin/grid from lat+long).
• Precise values, many columns, nothing fits → table; pivot for a two-dimension cross-tab.

Step 2 — bind output columns

Every binding key takes output column-name strings, never field ids — the names the query produces: a count aggregation is count, a breakout its field's name, a named aggregation its name option, a second sum in a stage sum_2. Empty {} is valid for a simple aggregate (auto-bound); set keys to pin or override:

{"display": "bar",
 "visualization_settings": {"graph.dimensions": ["CATEGORY"], "graph.metrics": ["count"]}}

• bar/line/area/combo/row/scatter: graph.dimensions (x; a 2nd entry = series breakout), graph.metrics (y). Stacked: "stackable.stack_type": "stacked" ("normalized" = 100%).
• pie: {"pie.dimension": "CATEGORY", "pie.metric": "count"}
• scalar: {"scalar.field": "count"} (only with >1 column)
• funnel: {"funnel.dimension": "STAGE", "funnel.metric": "count"}
• map region: {"map.type": "region", "map.region": "us_states", "map.dimension": "STATE", "map.metric": "count"}. map.region: "us_states" (dimension values = 2-letter state codes or state names, "CA"/"California"), "world_countries" (2-letter ISO codes or country names, "US"/"United States"), or an admin-added custom-GeoJSON key. Pin/grid: "map.type": "pin" + map.latitude_column + map.longitude_column.
• sankey: {"sankey.source": "FROM", "sankey.target": "TO", "sankey.value": "count"}
• waterfall: exactly one dimension + one metric.
• table: always renders; table.columns ([{"name": …, "enabled": …}]) orders and hides columns.

column_settings: JSON-string keys

Per-column formatting keys are JSON-encoded arrays passed as strings, inner quotes escaped — never an object key:

"visualization_settings": {
  "column_settings": {
    "[\"name\",\"TOTAL\"]": {"number_style": "currency", "currency": "USD", "decimals": 2},
    "[\"name\",\"CREATED_AT\"]": {"date_style": "MMMM D, YYYY"}}}

Always author ["name", "<output column>"]. A ["ref", ["field", id, opts]] key appears in read-back — don't author it; when editing such a card keep those keys verbatim.

Escape hatch and catalog

For anything intricate — combo charts, conditional formatting, pivot splits, click behavior — read a UI-built card with the look you want (get_content {"items": [{"type": "question", "id": <id>}], "include": ["visualization_settings"]}) and reuse its visualization_settings verbatim; the server produced it, so it's valid for that display. Every key with values and defaults, series_settings, conditional formatting, pivot splits, dashcard click behavior: learn("visualization-settings", "settings").

Don't

• Don't invent display values — accepted, renders nothing.
• Don't put field ids in graph.dimensions / pie.metric / scalar.field — output column names only, or the chart renders blank.
• Don't write a column_settings key as an object, or author the ["ref", …] form — ignored.
• Don't pick pie for >5 slices, combo for unrelated metrics, or scalar/pie for a trend — renders, misleads.
• Don't report a chart as rendering from the write response — its visualization_settings echo is what got stored, not proof anything draws.

To confirm

get_content {"items": [{"type": "question", "id": <id>}], "include": ["visualization_settings"]} returns visualization_settings as stored (alongside display, which every question read carries) — proof the settings saved, not that the chart renders. question_write also echoes visualization_settings in its response, so a write you just made needs no second call. fields: ["visualization_settings"] reads the blob alone; a card with nothing stored returns {}. Rendering (a region whose values don't match, a binding to a missing column) has no API check: call it unverified unless the user has viewed the card.