Result metadata

result_metadata helps a renderer understand the result without knowing the warehouse query that produced it.

Shape#

{
  "roles": {
    "x": "day",
    "y": ["request_count", "error_count"],
    "series": "region"
  },
  "suggested_chart_types": ["stacked_bar", "combo_bar_line", "table"]
}

Roles#

The keys refer to result output names. A dimension alias replaces its source field name. Metrics use their aliases.

Suggested charts#

Suggestions come from the result shape:

• one metric and no dimension suggests number/table;
• a time bucket suggests line/area/bar/table;
• one category dimension suggests bar/pie/funnel/table;
• two dimensions suggest stacked/cohort shapes;
• clearly named latitude and longitude dimensions suggest map/table;
• multiple metrics can add combo and scatter suggestions.

Suggestions are guidance, not proof that every chart is semantically meaningful. Saved Analytics API visualization metadata should take priority when valid.

Core suggests map only for recognized coordinate output names such as latitude/longitude, lat/lon, or their location/geo-prefixed forms. It does not interpret an arbitrary pair of numeric dimensions as coordinates.

Renderer order#

1. Apply saved chart type and visualization metadata.
2. Resolve output keys from metadata roles.
3. Verify required columns and value types.
4. Use a compatible suggestion or deterministic heuristic.
5. Fall back to table/raw JSON when specialized rendering is unsafe.