Visualizations

Visualization settings describe how a compatible result should be rendered. They do not replace the analytics definition; dimensions and metrics still determine the data.

Supported chart types#

General metadata#

• x_key: preferred category or horizontal-axis output key;
• y_keys: numeric output keys;
• top_n: number of categories to keep;
• others_label: label for the grouped remainder;
• series_key: optional pivot/series output key;
• stack_mode: none, normal, or percent.

Always reference result aliases, not raw source fields, when an alias changes the output key.

Type-specific metadata#

Histogram uses binning.field with optional bin_count or bin_size. Funnel uses ordered funnel_steps. Cohort heatmap uses cohort, period, and value keys. Combo charts separate bar_keys from line_keys.

Map uses a provider-neutral map object. latitude_key and longitude_key are required. value_key controls bubble size, label_key supplies the point label, and category_key supplies the color group. Every key references an Analytics result output, not a warehouse column that was not selected.

{
  "x_key": "day",
  "y_keys": ["request_count"],
  "top_n": 12,
  "others_label": "Other"
}

{
  "map": {
    "latitude_key": "latitude",
    "longitude_key": "longitude",
    "value_key": "observation_count",
    "label_key": "station_name",
    "category_key": "pollutant"
  },
  "top_n": 500
}

Map portability and safety#

Latitude and longitude remain ordinary numeric dimensions. Optional bubble values remain ordinary metrics. Core therefore produces the same provider-neutral plan for BigQuery, ClickHouse, Snowflake, Elasticsearch, and OpenSearch; no vendor geographic function is required.

Renderers accept WGS84 decimal coordinates only: latitude from -90 to 90 and longitude from -180 to 180. Invalid rows are skipped, map results should use a bounded limit/top_n, and a renderer must fall back to the result table when it cannot draw valid points. The built-in point map does not contact an external tile provider.

Result metadata and fallback#

The runtime also returns suggested chart types based on the result shape. Renderers should prefer saved metadata, use result roles when available, and fall back to a table when a specialized chart cannot be drawn safely.

The same saved chart type and visualization metadata are used in Dashboard previews, Explorer, public Dataset charts, and Analytics Share links. Sharing changes the access surface, not the result shape or renderer contract.