When a custom app fits better: A managed AI/BI dashboard is the right tool for read-only KPIs, charts, and filters over governed tables. If the user instead needs a custom-code interactive app — write-back / data entry, bespoke UI or interactions beyond the dashboard grid, embedded or auth-gated workflows, or a conversational Genie/chat assistant as the primary surface — build a Databricks App instead with the

databricks-apps

skill (which brings in

databricks-app-design

for the data-screen UX). Linking an "Ask Genie" space to this dashboard stays here (see Linking a Genie Space below).

databricks warehouses list

databricks experimental aitools tools query --warehouse WH "SHOW TABLES IN catalog.schema"

databricks experimental aitools tools discover-schema catalog.schema.table1 catalog.schema.table2

databricks experimental aitools tools query --warehouse WH "SELECT..."

databricks lakeview create --display-name "X" --warehouse-id "WH" --dataset-catalog CATALOG --dataset-schema SCHEMA --serialized-dashboard "$(cat file.json)" --json '{"parent_path": "/Workspace/Users/<you>/path"}'

--dataset-catalog

--dataset-schema

--json

parent_path

databricks lakeview update DASHBOARD_ID --dataset-catalog CATALOG --dataset-schema SCHEMA --serialized-dashboard "$(cat file.json)"

--dataset-catalog

--dataset-schema

databricks lakeview publish DASHBOARD_ID --warehouse-id WH

databricks lakeview trash DASHBOARD_ID

--warehouse

flag: if

databricks experimental aitools tools query --warehouse WH "..."

fails with

unknown flag: --warehouse

on your CLI version, set

DATABRICKS_WAREHOUSE_ID=WH

in the environment instead and drop the flag — the command auto-picks it from there.

Wrong version = broken widget! This is the #1 cause of dashboard errors.

counter

table

bar

line

pie

symbol-map

area

scatter

combo

choropleth-map

forecast-line

AI_FORECAST

pivot

histogram

bin(col, binWidth=N)

sankey

heatmap

funnel

box

waterfall

filter-single-select

filter-multi-select

filter-date-range-picker

range-slider

custom-vega-viz

Cohort retention charts are built as a

pivot

with a color-scale cell style — there is no

cohort

widget type. See pivot in 2-advanced-widget-specifications.md.

discover-schema

query "SHOW TABLES IN ..."

databricks experimental aitools tools discover-schema catalog.schema.orders catalog.schema.customers

databricks experimental aitools tools query --warehouse <WH> "..."

• Cardinality of candidate grouping columns → decides chart color-group vs. table (≤8 distinct values for charts, see Cardinality & Readability below).
• Top categorical values → populates filter options and chart legends meaningfully.
• Numeric distribution (min/max/avg/percentiles) → decides KPI with delta vs. trend chart (flat metrics shouldn't be line charts, see Data Variance Considerations below).
• Trend viability at daily/weekly/monthly grain → picks the right trend granularity.
• Story confirmation — run the aggregations you plan to put in the dashboard and check they're not flat, empty, or uninteresting. Fix the query or adjust the story before moving on.

--file

--concurrency 8

DATABRICKS_WAREHOUSE_ID=<WH> databricks experimental aitools tools query --output json \
  "SELECT COUNT(*) FROM catalog.schema.orders" \
  "SELECT region, COUNT(*) FROM catalog.schema.orders GROUP BY region ORDER BY 2 DESC LIMIT 10" \
  "SELECT MIN(ts), MAX(ts) FROM catalog.schema.orders"

• --output json

  is mandatory in multi-query mode. Returns one object per statement:

  {sql, state, rows, error}

  ; failures are per-statement (

  state: "FAILED"

  ), others still succeed.
• ⚠️ Don't trust the exit code (a failed statement can still exit

  0

  ) — gate on each object's

  state != "SUCCEEDED"

  .

Dashboard queries are different — inside the dashboard JSON, the

FROM

clause must reference ONLY the table name, with no catalog or schema prefix:

• ✅ Correct:

  FROM trips

• ❌ Wrong:

  FROM nyctaxi.trips

• ❌ Wrong:

  FROM samples.nyctaxi.trips

The catalog and schema are supplied separately via the

--dataset-catalog

and

--dataset-schema

flags when you run

databricks lakeview create

. These flags do NOT rewrite the query — they only fill in the catalog/schema when the query omits them. If you hardcode a catalog or schema in the

FROM

clause, the flags are ignored for that query and the dashboard won't be portable across environments.

1. You must know the expected specific JSON structure. For this, Read reference files: 1-widget-specifications.md, 3-filters.md.

1. Think: What widgets? Map each visualization to a dataset:

   Widget	Type	Dataset	Has filter field?
   Revenue KPI	counter	ds_sales	✓ date, region
   Trend Chart	line	ds_sales	✓ date, region
   Top Products	table	ds_products	✗ no date
   ...

2. What filters? For each filter, verify ALL datasets you want filtered contain the filter field.

   Filters only affect datasets that have the filter field. A pre-aggregated table without dates WON'T be date-filtered.

3. Build the dashboard JSON as a local working file (intermediate step, not the deliverable).

update

publish

DASHBOARD_ID

create

• Don't

  create

  /import to update. That mints a new dashboard id + URL and breaks any link you've already shared;

  create

  is for brand-new dashboards only.

• update

  changes only the draft. The

  /published

  link viewers see stays on the last snapshot until you

  publish

  again — so always

  publish

  after

  update

  .

serialized_dashboard

\n

queryLines

{
  "datasets": [
    {
      "name": "ds_x",
      "displayName": "Dataset X",
      "queryLines": ["SELECT col1, col2 ", "FROM my_table"]
    }
  ],
  "pages": [
    {
      "name": "main",
      "displayName": "Main",
      "pageType": "PAGE_TYPE_CANVAS",
      "layout": [
        {"widget": {/* INLINE widget definition */}, "position": {"x":0,"y":0,"width":2,"height":3}}
      ]
    }
  ]
}

• queryLines

  : Array of strings, NOT

  "query": "string"

  . Elements are joined verbatim with no separator — end each line with
  or

  \n

  (or strip

  -- comments

  ). A line ending in

  -- comment

  with no newline swallows the next line.
• Widgets: INLINE in

  layout[].widget

  , NOT a separate

  "widgets"

  array

• pageType

  : Required on every page (

  PAGE_TYPE_CANVAS

  or

  PAGE_TYPE_GLOBAL_FILTERS

  )
• Query binding:

  query.fields[].name

  must exactly match

  encodings.*.fieldName

uiSettings.theme

widgetBorderColor = widgetBackgroundColor

fontColor

visualizationColors

selectionColor

#2272B4

{
  "datasets": [...],
  "pages": [...],
  "uiSettings": {
    "theme": {
      "canvasBackgroundColor": {"light": "#FCFCFC", "dark": "#1F272D"},
      "widgetBackgroundColor": {"light": "#FFFFFF", "dark": "#11171C"},
      "fontColor":             {"light": "#11171C", "dark": "#E8ECF0"},
      "selectionColor":        {"light": "#2272B4", "dark": "#8ACAFF"},
      "visualizationColors": [
        "#FFA600", "#FF7054", "#DE5582", "#995495",
        "#4E5185", "#1D425C", "#99DDB4"
      ],
      "widgetHeaderAlignment": "LEFT"
    }
  }
}

• visualizationColors

  : ordered palette every chart series and category mapping cycles through. Positions are 0-indexed:

  position: 0

  = first color (

  #FFA600

  above),

  position: 6

  = seventh (

  #99DDB4

  ). Length 5–8 is typical.
• Background / font / selection colors take

  light

  +

  dark

  pairs; the dashboard auto-selects based on viewer mode.

• widgetHeaderAlignment

  :

  "LEFT"

  (default),

  "CENTER"

  , or

  "RIGHT"

  . Optional top-level:

  fontFamily

  (e.g.

  "Space Grotesk"

  ,

  "Inter"

  — sans-serif keeps dense data readable; don't override per widget) and

  widgetCornerRadius

  (integer px, e.g.

  12

  for rounded corners;

  0

  or omit = square).
• Per-widget color references:

  {"themeColorType": "visualizationColors", "position": N}

  (0-indexed) to pin to a palette slot, or

  {"hex": "#FF0000"}

  for an exact color outside the palette.

1. One coherent color family per dashboard, distinct across the suite. Walk across hues (e.g., amber → coral → pink → purple → navy), not one color faded toward white — a single-hue lightness ramp reads as one color and the viewer can't tell categories apart. Adjacent stops must be visually distinct: if you squint and two blur into one, push them further apart. Single-hue ramps are for quantitative widgets only (

   colorRamp.mode: "custom-sequential"

   ), never for

   visualizationColors

   .
2. Pin semantic colors as literal hex, outside the palette. "Bad" = a warm coral (e.g.

   #FF7E5C

   ), "good" = a calm teal/green. Use

   color.scale.mappings

   with a bare hex string —

   {"value": "Critical", "color": "#FF7E5C"}

   — not

   {"hex": "..."}

   or

   themeColorType: position

   (both are silently dropped on chart widgets). Reuse the good-teal that's already in the palette so it never clashes.
3. Color non-categorical widgets explicitly so they join the family. Maps & heatmaps:

   colorRamp.mode: "custom-sequential"

   with

   {start, end}

   from the family (if directional:

   start

   = bad color,

   end

   = good color). Forecast / multi-series: pin per-series via

   color.scale.mappings

   keyed on

   displayName

   (actual = solid family color, forecast = contrast/alert, threshold = muted tone). Sparkline counters: set

   value.color

   to a family color, not grey.
4. "Lighter / more pastel" tweak: nudge all stops up in lightness together; don't recolor individual ones. Re-sync the pinned semantic hex values; keep enough contrast on the alert color that it still reads as a warning.

#094074  #3C6997  #5ADBFF  #FFDD4A  #FE9000
#003F5C  #594E90  #BC4C96  #FF5F66  #FFA600
#4A8CC7  #F59770  #FFD84A  #F0E09E  #6DD980
#440154  #3B528B  #21918C  #5EC962  #FDE725
#4E79A7  #F28E2C  #E15759  #76B7B2  #59A14F
#0072B2  #E69F00  #009E73  #CC79A7  #D55E00
#0D0887  #7E03A8  #CC4778  #F89441  #F0F921
#6929C4  #1192E8  #005D5D  #9F1853  #FA4D56

colorbrewer2.org

uiSettings.genieSpace

theme

"uiSettings": {
  "theme": { /* ... */ },
  "genieSpace": {
    "isEnabled": true,
    "overrideId": "your-genie-space-id-here",
    "enablementMode": "ENABLED"
  }
}

Genie is NOT a widget. Link via

uiSettings.genieSpace

only. There is no

"widgetType": "assistant"

.

• Global date filter: When data has temporal columns, add a date range filter. Most dashboards need time-based filtering.
• KPI time bounds: Use time-bounded metrics that enable period comparison (MoM, YoY). Unbounded "all-time" totals are less actionable.
• Value formatting: Format values based on their meaning — currency with symbol, percentages with %, large numbers compacted (K/M/B).
• Chart selection: Match cardinality to chart type. Few distinct values → bar with color grouping (or pie if you really want a snapshot); many values → table.

Before generating any dashboard JSON, read 4-examples.md first. It's a complete reference dashboard exercising every construct (dataset measures +

MEASURE()

, sparkline counters, forecast-line with annotations, pivot with conditional cells, symbol-map, histogram, range-slider filter, theme). Use it to learn the JSON shape; then adapt to the user's data and demo story — keep the structure, swap the tables, metrics, palette, and narrative for the case you're building.

• Fewer datasets is better — aim for one dataset that backs as many widgets as possible. Clicking a value on a chart (e.g., a bar, a slice) acts as a filter on that dataset, and every other widget sharing the same dataset re-renders with the click applied. Splitting widgets across many narrow datasets breaks this cross-filtering and forces users to set explicit filter widgets for what should "just work". Prefer one wide dataset per domain (orders, cases, customers); only split when a widget genuinely needs different grain, pre-aggregation, or a parameter the others can't tolerate.
• Two ways to define a dataset:
  • SQL query:

    {"name": "ds_x", "displayName": "...", "queryLines": ["SELECT ...", "FROM table"]}

    — full control, can include

    WITH

    /

    JOIN

    /

    AI_FORECAST

    / etc.
  • UC asset shorthand:

    {"name": "ds_x", "asset_name": "catalog.schema.table_or_view"}

    — no SQL needed. Works for tables, views, and metric views. You can still stack

    columns

    (measures + derived dimensions) on top:

    {"name": "ds_x", "asset_name": "...", "columns": [{"displayName": "Total Revenue", "expression": "SUM(\

    amount_usd`)"}]}

    — same

    MEASURE()` pattern.
• Exactly ONE valid SQL query per dataset when using

  queryLines

  (no multiple queries separated by

  ;

  )
• Queries must use bare table names only — no catalog, no schema prefix. Example:

  FROM orders

  , never

  FROM gold.orders

  or

  FROM main.gold.orders

  . The catalog and schema come from the

  --dataset-catalog

  and

  --dataset-schema

  flags at creation time. These flags only fill in missing parts — they do NOT override any catalog/schema written in the query.
• SELECT must include all dimensions needed by widgets and all derived columns via

  AS

  aliases
• Put ALL business logic (CASE/WHEN, COALESCE, ratios) into the dataset SELECT with explicit aliases
• Contract rule: Every widget

  fieldName

  must exactly match a dataset column or alias
• Add ORDER BY when visualization depends on data order:
  • Time series:

    ORDER BY date

    for chronological display
  • Rankings/Top-N:

    ORDER BY metric DESC LIMIT 10

    for "Top 10" charts
  • Categorical charts:

    ORDER BY metric DESC

    to show largest values first

{"name": "sum(x)", "expression": "SUM(\

1. Dashboard-level

   columns

   (works on any dataset — SQL query or

   asset_name

   ):
   json

   {
     "name": "ds_support",
     "queryLines": ["SELECT * FROM support_cases"],
     "columns": [
       {"displayName": "Total Cases",     "description": "Count of cases",
        "expression": "COUNT(`case_id`)"},
       {"displayName": "Reopen Rate %",   "description": "% of reopened cases",
        "expression": "SUM(CASE WHEN `reopened_flag` THEN 1 ELSE 0 END) * 100.0 / COUNT(`case_id`)"},
       {"displayName": "Priority Level",  "description": "Sorted priority label",
        "expression": "CASE WHEN `priority`='Critical' THEN '1-Critical' ELSE '4-Low' END"}
     ]
   }

2. Metric-view source — if the dataset's

   asset_name

   (or

   FROM

   clause) is a UC metric view, its YAML-defined measures are already queryable. Do not redeclare them in

   columns

   . See databricks-metric-views.

"fields": [{"name": "measure(Total Cases)", "expression": "MEASURE(`Total Cases`)"}],
"encodings": {"value": {"fieldName": "measure(Total Cases)", "displayName": "Total Cases"}}

MEASURE(\

CRITICAL: Field Name Matching Rule The

name

in

query.fields

MUST exactly match the

fieldName

in

encodings

. If they don't match, the widget shows "no selected fields to visualize" error!

// In query.fields:
{"name": "sum(spend)", "expression": "SUM(`spend`)"}

// In encodings (must match!):
{"fieldName": "sum(spend)", "displayName": "Total Spend"}

// In query.fields:
{"name": "spend", "expression": "SUM(`spend`)"}  // name is "spend"

// In encodings:
{"fieldName": "sum(spend)", ...}  // ERROR: "sum(spend)" ≠ "spend"

{"name": "(sum|avg|count|countdistinct|min|max)(col)", "expression": "(SUM|AVG|COUNT|COUNT(DISTINCT)|MIN|MAX)(`col`)"}
{"name": "(daily|weekly|monthly)(date)", "expression": "DATE_TRUNC(\"(DAY|WEEK|MONTH)\", `date`)"}
{"name": "field", "expression": "`field`"}

• Date math:

  date_sub(current_date(), N)

  for days,

  add_months(current_date(), -N)

  for months
• Date truncation:

  DATE_TRUNC('DAY'|'WEEK'|'MONTH'|'QUARTER'|'YEAR', column)

• AVOID

  INTERVAL

  syntax - use functions instead

1. Check column cardinality via discover-schema or a COUNT DISTINCT query
2. If >10 distinct values, aggregate to higher level OR use TOP-N + "Other" bucket
3. For high-cardinality dimensions, use a table widget instead of a chart

1. All widget names use only alphanumeric + hyphens + underscores
2. Every page has

   "layoutVersion": "GRID_V1"

3. All rows sum to width=12 with no gaps
4. KPIs use height 3-4, charts use height 5-6
5. Chart dimensions have reasonable cardinality (≤8 for colors/groups)
6. All widget fieldNames match dataset columns exactly
7. Field

   name

   in query.fields matches

   fieldName

   in encodings exactly (e.g., both

   "sum(spend)"

   )
8. Counter datasets: use

   disaggregated: true

   for 1-row datasets,

   disaggregated: false

   with aggregation for multi-row
9. Percent values must be 0-1 for

   number-percent

   format (0.865 displays as "86.5%", don't forget to set the format). If data is 0-100, either divide by 100 in SQL or use

   number

   format instead.
10. SQL uses Spark syntax (date_sub, not INTERVAL)
11. All SQL queries tested via CLI and return expected data
12. Every dataset you want filtered MUST contain the filter field — filters only affect datasets with that column in their query

SELECT MIN(metric), MAX(metric), MAX(metric) - MIN(metric) as range FROM dataset

• Showing as KPI with delta/comparison instead of chart
• Using a table to display exact values
• Adjusting the visualization to focus on the variance

• databricks-apps - when the user needs a custom-code interactive app (write-back, bespoke UI, in-app chat / Genie) instead of a managed dashboard
• databricks-unity-catalog - for querying the underlying data and system tables
• databricks-pipelines - for building the data pipelines that feed dashboards
• databricks-jobs - for scheduling dashboard data refreshes