databricks-aibi-dashboards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI/BI Dashboard Skill

AI/BI仪表板开发技能

Create Databricks AI/BI dashboards (formerly Lakeview dashboards). Follow these guidelines strictly.

创建Databricks AI/BI仪表板（原Lakeview仪表板）。请严格遵循以下指南。

CRITICAL: MANDATORY VALIDATION WORKFLOW

重要提示：强制验证工作流

You MUST follow this workflow exactly. Skipping validation causes broken dashboards.

┌─────────────────────────────────────────────────────────────────────┐
│  STEP 1: Get table schemas via get_table_details(catalog, schema)  │
├─────────────────────────────────────────────────────────────────────┤
│  STEP 2: Write SQL queries for each dataset                        │
├─────────────────────────────────────────────────────────────────────┤
│  STEP 3: TEST EVERY QUERY via execute_sql() ← DO NOT SKIP!         │
│          - If query fails, FIX IT before proceeding                │
│          - Verify column names match what widgets will reference   │
│          - Verify data types are correct (dates, numbers, strings) │
├─────────────────────────────────────────────────────────────────────┤
│  STEP 4: Build dashboard JSON using ONLY verified queries          │
├─────────────────────────────────────────────────────────────────────┤
│  STEP 5: Deploy via create_or_update_dashboard()                   │
└─────────────────────────────────────────────────────────────────────┘

WARNING: If you deploy without testing queries, widgets WILL show "Invalid widget definition" errors!

您必须严格遵循此工作流。跳过验证会导致仪表板故障。

┌─────────────────────────────────────────────────────────────────────┐
│  步骤1：通过get_table_details(catalog, schema)获取表结构          │
├─────────────────────────────────────────────────────────────────────┤
│  步骤2：为每个数据集编写SQL查询                                    │
├─────────────────────────────────────────────────────────────────────┤
│  步骤3：通过execute_sql()测试所有查询 ← 请勿跳过！                 │
│          - 如果查询失败，修复后再继续                              │
│          - 验证列名称与小部件引用的名称一致                        │
│          - 验证数据类型正确（日期、数字、字符串）                  │
├─────────────────────────────────────────────────────────────────────┤
│  步骤4：仅使用已验证的查询构建仪表板JSON                          │
├─────────────────────────────────────────────────────────────────────┤
│  步骤5：通过create_or_update_dashboard()部署                      │
└─────────────────────────────────────────────────────────────────────┘

警告：如果不测试查询就部署，小部件将显示“无效小部件定义”错误！

Available MCP Tools

可用的MCP工具

Tool	Description
`get_table_details`	STEP 1: Get table schemas for designing queries
`execute_sql`	STEP 3: Test SQL queries - MANDATORY before deployment!
`get_best_warehouse`	Get available warehouse ID
`create_or_update_dashboard`	STEP 5: Deploy dashboard JSON (only after validation!)
`get_dashboard`	Get dashboard details by ID
`list_dashboards`	List dashboards in workspace
`trash_dashboard`	Move dashboard to trash
`publish_dashboard`	Publish dashboard for viewers
`unpublish_dashboard`	Unpublish a dashboard

工具	说明
`get_table_details`	步骤1：获取表结构以设计查询
`execute_sql`	步骤3：测试SQL查询 - 部署前必须执行！
`get_best_warehouse`	获取可用的仓库ID
`create_or_update_dashboard`	步骤5：部署仪表板JSON（仅在验证后执行！）
`get_dashboard`	通过ID获取仪表板详情
`list_dashboards`	列出工作区中的仪表板
`trash_dashboard`	将仪表板移至回收站
`publish_dashboard`	发布仪表板供查看者访问
`unpublish_dashboard`	取消发布仪表板

Implementation Guidelines

实施指南

1) DATASET ARCHITECTURE (STRICT)

1) 数据集架构（严格要求）

One dataset per domain (e.g., orders, customers, products)
Exactly ONE valid SQL query per dataset (no multiple queries separated by
```
;
```
)
Always use fully-qualified table names:
```
catalog.schema.table_name
```
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

每个领域对应一个数据集（例如：订单、客户、产品）
每个数据集只能有一个有效的SQL查询（不允许用
```
;
```
分隔多个查询）
始终使用完全限定的表名：
```
catalog.schema.table_name
```
SELECT语句必须包含小部件所需的所有维度，以及通过
```
AS
```
别名定义的所有派生列
将所有业务逻辑（CASE/WHEN、COALESCE、比率）放入数据集的SELECT语句中，并使用明确的别名
规则约束：每个小部件的
```
fieldName
```
必须与数据集的列或别名完全匹配

2) WIDGET FIELD EXPRESSIONS

2) 小部件字段表达式

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!

Correct pattern for aggregations:

json

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

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

WRONG - names don't match:

json

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

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

Allowed expressions in widget queries (you CANNOT use CAST or other SQL in expressions):

For numbers:

json

{"name": "sum(revenue)", "expression": "SUM(`revenue`)"}
{"name": "avg(price)", "expression": "AVG(`price`)"}
{"name": "count(orders)", "expression": "COUNT(`order_id`)"}
{"name": "countdistinct(customers)", "expression": "COUNT(DISTINCT `customer_id`)"}
{"name": "min(date)", "expression": "MIN(`order_date`)"}
{"name": "max(date)", "expression": "MAX(`order_date`)"}

For dates (use daily for timeseries, weekly/monthly for grouped comparisons):

json

{"name": "daily(date)", "expression": "DATE_TRUNC(\"DAY\", `date`)"}
{"name": "weekly(date)", "expression": "DATE_TRUNC(\"WEEK\", `date`)"}
{"name": "monthly(date)", "expression": "DATE_TRUNC(\"MONTH\", `date`)"}

Simple field reference (for pre-aggregated data):

json

{"name": "category", "expression": "`category`"}

If you need conditional logic or multi-field formulas, compute a derived column in the dataset SQL first.

重要提示：字段名称匹配规则
query.fields
中的
name
必须与
encodings
中的
fieldName
完全匹配。如果不匹配，小部件将显示“没有选定的可视化字段”错误！

聚合的正确写法：

json

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

// 在encodings中（必须匹配！）：
{"fieldName": "sum(spend)", "displayName": "总支出"}

错误示例 - 名称不匹配：

json

// 在query.fields中：
{"name": "spend", "expression": "SUM(`spend`)"}  // 名称是"spend"

// 在encodings中：
{"fieldName": "sum(spend)", ...}  // 错误："sum(spend)" ≠ "spend"

小部件查询中允许使用的表达式（不能在表达式中使用CAST或其他SQL语句）：

针对数字：

json

{"name": "sum(revenue)", "expression": "SUM(`revenue`)"}
{"name": "avg(price)", "expression": "AVG(`price`)"}
{"name": "count(orders)", "expression": "COUNT(`order_id`)"}
{"name": "countdistinct(customers)", "expression": "COUNT(DISTINCT `customer_id`)"}
{"name": "min(date)", "expression": "MIN(`order_date`)"}
{"name": "max(date)", "expression": "MAX(`order_date`)"}

针对日期（时间序列使用日粒度，分组对比使用周/月粒度）：

json

{"name": "daily(date)", "expression": "DATE_TRUNC(\"DAY\", `date`)"}
{"name": "weekly(date)", "expression": "DATE_TRUNC(\"WEEK\", `date`)"}
{"name": "monthly(date)", "expression": "DATE_TRUNC(\"MONTH\", `date`)"}

简单字段引用（针对预聚合数据）：

json

{"name": "category", "expression": "`category`"}

如果需要条件逻辑或多字段公式，请先在数据集的SQL中计算派生列。

3) SPARK SQL PATTERNS

3) Spark SQL 写法

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

日期计算：使用

date_sub(current_date(), N)

计算天数，使用

add_months(current_date(), -N)

计算月数

日期截断：

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

避免使用
```
INTERVAL
```
语法 - 改用函数

4) LAYOUT (6-Column Grid, NO GAPS)

4) 布局（6列网格，无间隙）

Each widget has a position:

{"x": 0, "y": 0, "width": 2, "height": 4}

CRITICAL: Each row must fill width=6 exactly. No gaps allowed.

Recommended widget sizes:

Widget Type	Width	Height	Notes
Text header	6	1	Full width; use SEPARATE widgets for title and subtitle
Counter/KPI	2	3-4	NEVER height=2 - too cramped!
Line/Bar chart	3	5-6	Pair side-by-side to fill row
Pie chart	3	5-6	Needs space for legend
Full-width chart	6	5-7	For detailed time series
Table	6	5-8	Full width for readability

Standard dashboard structure:

text

y=0:  Title (w=6, h=1) - Dashboard title (use separate widget!)
y=1:  Subtitle (w=6, h=1) - Description (use separate widget!)
y=2:  KPIs (w=2 each, h=3) - 3 key metrics side-by-side
y=5:  Section header (w=6, h=1) - "Trends" or similar
y=6:  Charts (w=3 each, h=5) - Two charts side-by-side
y=11: Section header (w=6, h=1) - "Details"
y=12: Table (w=6, h=6) - Detailed data

每个小部件都有位置：

{"x": 0, "y": 0, "width": 2, "height": 4}

重要提示：每行的总宽度必须恰好为6。不允许有间隙。

推荐的小部件尺寸：

小部件类型	宽度	高度	说明
文本标题	6	1	全屏宽度；标题和副标题使用单独的小部件
计数器/KPI	2	3-4	绝对不要用高度=2 - 太拥挤！
折线图/柱状图	3	5-6	并排摆放以填满整行
饼图	3	5-6	需要预留图例空间
全屏宽度图表	6	5-7	用于详细的时间序列
表格	6	5-8	全屏宽度以提升可读性

标准仪表板结构：

text

y=0: 标题（w=6, h=1）- 仪表板标题（使用单独的小部件！）
y=1: 副标题（w=6, h=1）- 描述（使用单独的小部件！）
y=2: KPIs（每个w=2, h=3）- 3个关键指标并排显示
y=5: 章节标题（w=6, h=1）- 如“趋势”等
y=6: 图表（每个w=3, h=5）- 两个图表并排显示
y=11: 章节标题（w=6, h=1）- 如“详情”
y=12: 表格（w=6, h=6）- 详细数据

5) CARDINALITY & READABILITY (CRITICAL)

5) 基数与可读性（重要提示）

Dashboard readability depends on limiting distinct values:

Dimension Type	Max Values	Examples
Chart color/groups	3-8	4 regions, 5 product lines, 3 tiers
Filters	4-10	8 countries, 5 channels
High cardinality	Table only	customer_id, order_id, SKU

Before creating any chart with color/grouping:

Check column cardinality (use
```
get_table_details
```
to see distinct values)
If >10 distinct values, aggregate to higher level OR use TOP-N + "Other" bucket
For high-cardinality dimensions, use a table widget instead of a chart

仪表板的可读性取决于限制不同值的数量：

维度类型	最大值	示例
图表颜色/分组	3-8	4个地区、5个产品线、3个层级
过滤器	4-10	8个国家、5个渠道
高基数	仅用于表格	customer_id、order_id、SKU

创建任何带颜色/分组的图表之前：

检查列的基数（使用
```
get_table_details
```
查看不同值的数量）
如果不同值超过10个，聚合到更高层级或使用TOP-N + “其他”分组
对于高基数维度，使用表格小部件而非图表

6) WIDGET SPECIFICATIONS

6) 小部件规范

Widget Naming Convention (CRITICAL):

```
widget.name
```
: alphanumeric + hyphens + underscores ONLY (no spaces, parentheses, colons)
```
frame.title
```
: human-readable name (any characters allowed)
```
widget.queries[0].name
```
: always use
```
"main_query"
```

CRITICAL VERSION REQUIREMENTS:

Widget Type	Version
counter	2
table	2
filter-multi-select	2
filter-single-select	2
filter-date-range-picker	2
bar	3
line	3
pie	3
text	N/A (no spec block)

Text (Headers/Descriptions):

CRITICAL: Text widgets do NOT use a spec block!
Use
```
multilineTextboxSpec
```
directly on the widget
Supports markdown:
```
#
```
,
```
##
```
,
```
###
```
,
```
**bold**
```
,
```
*italic*
```
CRITICAL: Multiple items in the
lines
array are concatenated on a single line, NOT displayed as separate lines!
For title + subtitle, use separate text widgets at different y positions

json

// CORRECT: Separate widgets for title and subtitle
{
  "widget": {
    "name": "title",
    "multilineTextboxSpec": {
      "lines": ["## Dashboard Title"]
    }
  },
  "position": {"x": 0, "y": 0, "width": 6, "height": 1}
},
{
  "widget": {
    "name": "subtitle",
    "multilineTextboxSpec": {
      "lines": ["Description text here"]
    }
  },
  "position": {"x": 0, "y": 1, "width": 6, "height": 1}
}

// WRONG: Multiple lines concatenate into one line!
{
  "widget": {
    "name": "title-widget",
    "multilineTextboxSpec": {
      "lines": ["## Dashboard Title", "Description text here"]  // Becomes "## Dashboard TitleDescription text here"
    }
  },
  "position": {"x": 0, "y": 0, "width": 6, "height": 2}
}

Counter (KPI):

```
version
```
: 2 (NOT 3!)
```
widgetType
```
: "counter"
Percent values must be 0-1 in the data (not 0-100)

Two patterns for counters:

Pattern 1: Pre-aggregated dataset (1 row, no filters)

Dataset returns exactly 1 row
Use
```
"disaggregated": true
```
and simple field reference
Field
```
name
```
matches dataset column directly

json

{
  "widget": {
    "name": "total-revenue",
    "queries": [{
      "name": "main_query",
      "query": {
        "datasetName": "summary_ds",
        "fields": [{"name": "revenue", "expression": "`revenue`"}],
        "disaggregated": true
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "counter",
      "encodings": {
        "value": {"fieldName": "revenue", "displayName": "Total Revenue"}
      },
      "frame": {"showTitle": true, "title": "Total Revenue"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 2, "height": 3}
}

Pattern 2: Aggregating widget (multi-row dataset, supports filters)

Dataset returns multiple rows (e.g., grouped by a filter dimension)
Use
```
"disaggregated": false
```
and aggregation expression
CRITICAL: Field
```
name
```
MUST match
```
fieldName
```
exactly (e.g.,
```
"sum(spend)"
```
)

json

{
  "widget": {
    "name": "total-spend",
    "queries": [{
      "name": "main_query",
      "query": {
        "datasetName": "by_category",
        "fields": [{"name": "sum(spend)", "expression": "SUM(`spend`)"}],
        "disaggregated": false
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "counter",
      "encodings": {
        "value": {"fieldName": "sum(spend)", "displayName": "Total Spend"}
      },
      "frame": {"showTitle": true, "title": "Total Spend"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 2, "height": 3}
}

Table:

```
version
```
: 2 (NOT 1 or 3!)
```
widgetType
```
: "table"
Columns only need
fieldName
and
displayName
- no other properties!
Use
```
"disaggregated": true
```
for raw rows

json

{
  "widget": {
    "name": "details-table",
    "queries": [{
      "name": "main_query",
      "query": {
        "datasetName": "details_ds",
        "fields": [
          {"name": "name", "expression": "`name`"},
          {"name": "value", "expression": "`value`"}
        ],
        "disaggregated": true
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "table",
      "encodings": {
        "columns": [
          {"fieldName": "name", "displayName": "Name"},
          {"fieldName": "value", "displayName": "Value"}
        ]
      },
      "frame": {"showTitle": true, "title": "Details"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 6, "height": 6}
}

Line / Bar Charts:

```
version
```
: 3
```
widgetType
```
: "line" or "bar"
Use
```
x
```
,
```
y
```
, optional
```
color
```
encodings

scale.type

"temporal"

(dates),

"quantitative"

(numbers),

"categorical"

(strings)

Use
```
"disaggregated": true
```
with pre-aggregated dataset data

Multiple Lines - Two Approaches:

Multi-Y Fields (different metrics on same chart):

json

"y": {
  "scale": {"type": "quantitative"},
  "fields": [
    {"fieldName": "sum(orders)", "displayName": "Orders"},
    {"fieldName": "sum(returns)", "displayName": "Returns"}
  ]
}

Color Grouping (same metric split by dimension):

json

"y": {"fieldName": "sum(revenue)", "scale": {"type": "quantitative"}},
"color": {"fieldName": "region", "scale": {"type": "categorical"}, "displayName": "Region"}

Bar Chart Modes:

Stacked (default): No
```
mark
```
field - bars stack on top of each other
Grouped: Add
```
"mark": {"layout": "group"}
```
- bars side-by-side for comparison

Pie Chart:

```
version
```
: 3
```
widgetType
```
: "pie"
```
angle
```
: quantitative aggregate
```
color
```
: categorical dimension
Limit to 3-8 categories for readability

小部件命名规范（重要提示）：

```
widget.name
```
：只能使用字母数字、连字符和下划线（不能有空格、括号、冒号）
```
frame.title
```
：人类可读的名称（允许使用任何字符）
```
widget.queries[0].name
```
：始终使用
```
"main_query"
```

重要版本要求：

小部件类型	版本
counter	2
table	2
filter-multi-select	2
filter-single-select	2
filter-date-range-picker	2
bar	3
line	3
pie	3
text	无（不需要spec块）

文本（标题/描述）：

重要提示：文本小部件不需要spec块！
直接在小部件上使用
```
multilineTextboxSpec
```
支持Markdown：
```
#
```
、
```
##
```
、
```
###
```
、
```
**粗体**
```
、
```
*斜体*
```
重要提示：
lines
数组中的多个项会被拼接成一行，而不是显示为单独的行！
标题和副标题请使用单独的文本小部件，放在不同的y位置

json

// 正确示例：标题和副标题使用单独的小部件
{
  "widget": {
    "name": "title",
    "multilineTextboxSpec": {
      "lines": ["## 仪表板标题"]
    }
  },
  "position": {"x": 0, "y": 0, "width": 6, "height": 1}
},
{
  "widget": {
    "name": "subtitle",
    "multilineTextboxSpec": {
      "lines": ["描述文本"]
    }
  },
  "position": {"x": 0, "y": 1, "width": 6, "height": 1}
}

// 错误示例：多行文本会被拼接成一行！
{
  "widget": {
    "name": "title-widget",
    "multilineTextboxSpec": {
      "lines": ["## 仪表板标题", "描述文本"]  // 会变成"## 仪表板标题描述文本"
    }
  },
  "position": {"x": 0, "y": 0, "width": 6, "height": 2}
}

计数器（KPI）：

```
version
```
：2（不是3！）
```
widgetType
```
："counter"
百分比值在数据中必须是0-1（不是0-100）

计数器的两种写法：

写法1：预聚合数据集（1行，无过滤器）

数据集返回恰好1行
使用
```
"disaggregated": true
```
和简单字段引用
字段
```
name
```
直接匹配数据集的列

json

{
  "widget": {
    "name": "total-revenue",
    "queries": [{
      "name": "main_query",
      "query": {
        "datasetName": "summary_ds",
        "fields": [{"name": "revenue", "expression": "`revenue`"}],
        "disaggregated": true
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "counter",
      "encodings": {
        "value": {"fieldName": "revenue", "displayName": "总收入"}
      },
      "frame": {"showTitle": true, "title": "总收入"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 2, "height": 3}
}

写法2：聚合小部件（多行数据集，支持过滤器）

数据集返回多行（例如：按过滤器维度分组）
使用
```
"disaggregated": false
```
和聚合表达式
重要提示：字段
```
name
```
必须与
```
fieldName
```
完全匹配（例如：
```
"sum(spend)"
```
）

json

{
  "widget": {
    "name": "total-spend",
    "queries": [{
      "name": "main_query",
      "query": {
        "datasetName": "by_category",
        "fields": [{"name": "sum(spend)", "expression": "SUM(`spend`)"}],
        "disaggregated": false
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "counter",
      "encodings": {
        "value": {"fieldName": "sum(spend)", "displayName": "总支出"}
      },
      "frame": {"showTitle": true, "title": "总支出"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 2, "height": 3}
}

表格：

```
version
```
：2（不是1或3！）
```
widgetType
```
："table"
列只需要
fieldName
和
displayName
- 不需要其他属性！
对于原始行数据，使用
```
"disaggregated": true
```

json

{
  "widget": {
    "name": "details-table",
    "queries": [{
      "name": "main_query",
      "query": {
        "datasetName": "details_ds",
        "fields": [
          {"name": "name", "expression": "`name`"},
          {"name": "value", "expression": "`value`"}
        ],
        "disaggregated": true
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "table",
      "encodings": {
        "columns": [
          {"fieldName": "name", "displayName": "名称"},
          {"fieldName": "value", "displayName": "值"}
        ]
      },
      "frame": {"showTitle": true, "title": "详情"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 6, "height": 6}
}

折线图 / 柱状图：

```
version
```
：3
```
widgetType
```
："line"或"bar"
使用
```
x
```
、
```
y
```
、可选的
```
color
```
编码
```
scale.type
```
：
```
"temporal"
```
（日期）、
```
"quantitative"
```
（数字）、
```
"categorical"
```
（字符串）
对于预聚合数据集，使用
```
"disaggregated": true
```

多折线图的两种实现方式：

多Y字段（同一图表显示不同指标）：

json

"y": {
  "scale": {"type": "quantitative"},
  "fields": [
    {"fieldName": "sum(orders)", "displayName": "订单数"},
    {"fieldName": "sum(returns)", "displayName": "退货数"}
  ]
}

颜色分组（同一指标按维度拆分）：

json

"y": {"fieldName": "sum(revenue)", "scale": {"type": "quantitative"}},
"color": {"fieldName": "region", "scale": {"type": "categorical"}, "displayName": "地区"}

柱状图模式：

堆叠（默认）：不设置
```
mark
```
字段 - 柱状图堆叠显示
分组：添加
```
"mark": {"layout": "group"}
```
- 柱状图并排显示以便对比

饼图：

```
version
```
：3
```
widgetType
```
："pie"
```
angle
```
：数值型聚合
```
color
```
：分类维度
为了可读性，限制为3-8个类别

7) FILTERS (Global vs Page-Level)

7) 过滤器（全局 vs 页面级）

CRITICAL: Filter widgets use DIFFERENT widget types than charts!
Valid types:
filter-multi-select
,
filter-single-select
,
filter-date-range-picker
DO NOT use
widgetType: "filter"
- this does not exist and will cause errors
Filters use
spec.version: 2
ALWAYS include
frame
with
showTitle: true
for filter widgets

Filter widget types:

```
filter-date-range-picker
```
: for DATE/TIMESTAMP fields
```
filter-single-select
```
: categorical with single selection
```
filter-multi-select
```
: categorical with multiple selections

重要提示：过滤器小部件使用的类型与图表不同！
有效类型：
filter-multi-select
、
filter-single-select
、
filter-date-range-picker
不要使用
widgetType: "filter"
- 该类型不存在，会导致错误
过滤器使用
spec.version: 2
始终为过滤器小部件添加带
showTitle: true
的
frame

过滤器小部件类型：

```
filter-date-range-picker
```
：用于DATE/TIMESTAMP字段
```
filter-single-select
```
：单选分类过滤器
```
filter-multi-select
```
：多选分类过滤器

Global Filters vs Page-Level Filters

全局过滤器 vs 页面级过滤器

Type	Placement	Scope	Use Case
Global Filter	Dedicated page with `"pageType": "PAGE_TYPE_GLOBAL_FILTERS"`	Affects ALL pages that have datasets with the filter field	Cross-dashboard filtering (e.g., date range, campaign)
Page-Level Filter	Regular page with `"pageType": "PAGE_TYPE_CANVAS"`	Affects ONLY widgets on that same page	Page-specific filtering (e.g., platform filter on breakdown page only)

Key Insight: A filter only affects datasets that contain the filter field. To have a filter affect only specific pages:

Include the filter dimension in datasets for pages that should be filtered
Exclude the filter dimension from datasets for pages that should NOT be filtered

类型	位置	范围	使用场景
全局过滤器	专用页面，设置 `"pageType": "PAGE_TYPE_GLOBAL_FILTERS"`	影响所有包含该过滤器字段的数据集的页面	跨仪表板过滤（例如：日期范围、活动）
页面级过滤器	普通页面，设置 `"pageType": "PAGE_TYPE_CANVAS"`	仅影响同一页面上的小部件	页面专属过滤（例如：仅在细分页面上使用平台过滤器）

关键要点：过滤器仅影响包含该过滤器字段的数据集。要让过滤器仅影响特定页面：

在需要被过滤的页面的数据集中包含过滤器维度
在不需要被过滤的页面的数据集中排除过滤器维度

Filter Widget Structure

过滤器小部件结构

CRITICAL: Do NOT use
associative_filter_predicate_group
- it causes SQL errors! Use a simple field expression instead.

json

{
  "widget": {
    "name": "filter_region",
    "queries": [{
      "name": "ds_data_region",
      "query": {
        "datasetName": "ds_data",
        "fields": [
          {"name": "region", "expression": "`region`"}
        ],
        "disaggregated": false
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "filter-multi-select",
      "encodings": {
        "fields": [{
          "fieldName": "region",
          "displayName": "Region",
          "queryName": "ds_data_region"
        }]
      },
      "frame": {"showTitle": true, "title": "Region"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 2, "height": 2}
}

重要提示：不要使用
associative_filter_predicate_group
- 会导致SQL错误！改用简单的字段表达式。

json

{
  "widget": {
    "name": "filter_region",
    "queries": [{
      "name": "ds_data_region",
      "query": {
        "datasetName": "ds_data",
        "fields": [
          {"name": "region", "expression": "`region`"}
        ],
        "disaggregated": false
      }
    }],
    "spec": {
      "version": 2,
      "widgetType": "filter-multi-select",
      "encodings": {
        "fields": [{
          "fieldName": "region",
          "displayName": "地区",
          "queryName": "ds_data_region"
        }]
      },
      "frame": {"showTitle": true, "title": "地区"}
    }
  },
  "position": {"x": 0, "y": 0, "width": 2, "height": 2}
}

Global Filter Example

全局过滤器示例

Place on a dedicated filter page:

json

{
  "name": "filters",
  "displayName": "Filters",
  "pageType": "PAGE_TYPE_GLOBAL_FILTERS",
  "layout": [
    {
      "widget": {
        "name": "filter_campaign",
        "queries": [{
          "name": "ds_campaign",
          "query": {
            "datasetName": "overview",
            "fields": [{"name": "campaign_name", "expression": "`campaign_name`"}],
            "disaggregated": false
          }
        }],
        "spec": {
          "version": 2,
          "widgetType": "filter-multi-select",
          "encodings": {
            "fields": [{
              "fieldName": "campaign_name",
              "displayName": "Campaign",
              "queryName": "ds_campaign"
            }]
          },
          "frame": {"showTitle": true, "title": "Campaign"}
        }
      },
      "position": {"x": 0, "y": 0, "width": 2, "height": 2}
    }
  ]
}

放置在专用的过滤器页面：

json

{
  "name": "filters",
  "displayName": "过滤器",
  "pageType": "PAGE_TYPE_GLOBAL_FILTERS",
  "layout": [
    {
      "widget": {
        "name": "filter_campaign",
        "queries": [{
          "name": "ds_campaign",
          "query": {
            "datasetName": "overview",
            "fields": [{"name": "campaign_name", "expression": "`campaign_name`"}],
            "disaggregated": false
          }
        }],
        "spec": {
          "version": 2,
          "widgetType": "filter-multi-select",
          "encodings": {
            "fields": [{
              "fieldName": "campaign_name",
              "displayName": "营销活动",
              "queryName": "ds_campaign"
            }]
          },
          "frame": {"showTitle": true, "title": "营销活动"}
        }
      },
      "position": {"x": 0, "y": 0, "width": 2, "height": 2}
    }
  ]
}

Page-Level Filter Example

页面级过滤器示例

Place directly on a canvas page (affects only that page):

json

{
  "name": "platform_breakdown",
  "displayName": "Platform Breakdown",
  "pageType": "PAGE_TYPE_CANVAS",
  "layout": [
    {
      "widget": {
        "name": "page-title",
        "multilineTextboxSpec": {"lines": ["## Platform Breakdown"]}
      },
      "position": {"x": 0, "y": 0, "width": 4, "height": 1}
    },
    {
      "widget": {
        "name": "filter_platform",
        "queries": [{
          "name": "ds_platform",
          "query": {
            "datasetName": "platform_data",
            "fields": [{"name": "platform", "expression": "`platform`"}],
            "disaggregated": false
          }
        }],
        "spec": {
          "version": 2,
          "widgetType": "filter-multi-select",
          "encodings": {
            "fields": [{
              "fieldName": "platform",
              "displayName": "Platform",
              "queryName": "ds_platform"
            }]
          },
          "frame": {"showTitle": true, "title": "Platform"}
        }
      },
      "position": {"x": 4, "y": 0, "width": 2, "height": 2}
    }
    // ... other widgets on this page
  ]
}

Filter Layout Guidelines:

Global filters: Position on dedicated filter page, stack vertically at
```
x=0
```
Page-level filters: Position in header area of page (e.g., top-right corner)
Typical sizing:
```
width: 2, height: 2
```

直接放置在画布页面（仅影响该页面）：

json

{
  "name": "platform_breakdown",
  "displayName": "平台细分",
  "pageType": "PAGE_TYPE_CANVAS",
  "layout": [
    {
      "widget": {
        "name": "page-title",
        "multilineTextboxSpec": {"lines": ["## 平台细分"]}
      },
      "position": {"x": 0, "y": 0, "width": 4, "height": 1}
    },
    {
      "widget": {
        "name": "filter_platform",
        "queries": [{
          "name": "ds_platform",
          "query": {
            "datasetName": "platform_data",
            "fields": [{"name": "platform", "expression": "`platform`"}],
            "disaggregated": false
          }
        }],
        "spec": {
          "version": 2,
          "widgetType": "filter-multi-select",
          "encodings": {
            "fields": [{
              "fieldName": "platform",
              "displayName": "平台",
              "queryName": "ds_platform"
            }]
          },
          "frame": {"showTitle": true, "title": "平台"}
        }
      },
      "position": {"x": 4, "y": 0, "width": 2, "height": 2}
    }
    // ... 该页面上的其他小部件
  ]
}

过滤器布局指南：

全局过滤器：放置在专用过滤器页面，垂直堆叠在
```
x=0
```
位置
页面级过滤器：放置在页面的标题区域（例如：右上角）
典型尺寸：
```
width: 2, height: 2
```

8) QUALITY CHECKLIST

8) 质量检查清单

Before deploying, verify:

All widget names use only alphanumeric + hyphens + underscores
All rows sum to width=6 with no gaps
KPIs use height 3-4, charts use height 5-6
Chart dimensions have ≤8 distinct values
All widget fieldNames match dataset columns exactly
Field
name
in query.fields matches
fieldName
in encodings exactly (e.g., both
```
"sum(spend)"
```
)
Counter datasets: use
```
disaggregated: true
```
for 1-row datasets,
```
disaggregated: false
```
with aggregation for multi-row
Percent values are 0-1 (not 0-100)
SQL uses Spark syntax (date_sub, not INTERVAL)
All SQL queries tested via
execute_sql
and return expected data

部署前，请验证：

所有小部件名称仅使用字母数字、连字符和下划线
每行的总宽度为6，无间隙
KPI使用高度3-4，图表使用高度5-6
图表维度的不同值≤8个
所有小部件的fieldName与数据集列完全匹配
query.fields中的字段
name
与encodings中的
fieldName
完全匹配（例如：均为
```
"sum(spend)"
```
）
计数器数据集：1行数据集使用
```
disaggregated: true
```
，多行数据集使用
```
disaggregated: false
```
并配合聚合
百分比值为0-1（不是0-100）
SQL使用Spark语法（date_sub，而非INTERVAL）
所有SQL查询已通过
execute_sql
测试并返回预期数据

Complete Example

完整示例

python

import json

python

import json

Step 1: Check table schema

步骤1：检查表结构

table_info = get_table_details(catalog="samples", schema="nyctaxi")

Step 2: Test queries

步骤2：测试查询

execute_sql("SELECT COUNT() as trips, AVG(fare_amount) as avg_fare, AVG(trip_distance) as avg_distance FROM samples.nyctaxi.trips") execute_sql(""" SELECT pickup_zip, COUNT() as trip_count FROM samples.nyctaxi.trips GROUP BY pickup_zip ORDER BY trip_count DESC LIMIT 10 """)

Step 3: Build dashboard JSON

步骤3：构建仪表板JSON

dashboard = { "datasets": [ { "name": "summary", "displayName": "Summary Stats", "queryLines": [ "SELECT COUNT() as trips, AVG(fare_amount) as avg_fare, ", "AVG(trip_distance) as avg_distance ", "FROM samples.nyctaxi.trips " ] }, { "name": "by_zip", "displayName": "Trips by ZIP", "queryLines": [ "SELECT pickup_zip, COUNT() as trip_count ", "FROM samples.nyctaxi.trips ", "GROUP BY pickup_zip ", "ORDER BY trip_count DESC ", "LIMIT 10 " ] } ], "pages": [{ "name": "overview", "displayName": "NYC Taxi Overview", "pageType": "PAGE_TYPE_CANVAS", "layout": [ # Text header - NO spec block! Use SEPARATE widgets for title and subtitle! { "widget": { "name": "title", "multilineTextboxSpec": { "lines": ["## NYC Taxi Dashboard"] } }, "position": {"x": 0, "y": 0, "width": 6, "height": 1} }, { "widget": { "name": "subtitle", "multilineTextboxSpec": { "lines": ["Trip statistics and analysis"] } }, "position": {"x": 0, "y": 1, "width": 6, "height": 1} }, # Counter - version 2, width 2! { "widget": { "name": "total-trips", "queries": [{ "name": "main_query", "query": { "datasetName": "summary", "fields": [{"name": "trips", "expression": "

trips

"}], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "counter", "encodings": { "value": {"fieldName": "trips", "displayName": "Total Trips"} }, "frame": {"title": "Total Trips", "showTitle": True} } }, "position": {"x": 0, "y": 2, "width": 2, "height": 3} }, { "widget": { "name": "avg-fare", "queries": [{ "name": "main_query", "query": { "datasetName": "summary", "fields": [{"name": "avg_fare", "expression": "

avg_fare

"}], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "counter", "encodings": { "value": {"fieldName": "avg_fare", "displayName": "Avg Fare"} }, "frame": {"title": "Average Fare", "showTitle": True} } }, "position": {"x": 2, "y": 2, "width": 2, "height": 3} }, { "widget": { "name": "total-distance", "queries": [{ "name": "main_query", "query": { "datasetName": "summary", "fields": [{"name": "avg_distance", "expression": "

avg_distance

"}], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "counter", "encodings": { "value": {"fieldName": "avg_distance", "displayName": "Avg Distance"} }, "frame": {"title": "Average Distance", "showTitle": True} } }, "position": {"x": 4, "y": 2, "width": 2, "height": 3} }, # Bar chart - version 3 { "widget": { "name": "trips-by-zip", "queries": [{ "name": "main_query", "query": { "datasetName": "by_zip", "fields": [ {"name": "pickup_zip", "expression": "

pickup_zip

"}, {"name": "trip_count", "expression": "

trip_count

"} ], "disaggregated": True } }], "spec": { "version": 3, "widgetType": "bar", "encodings": { "x": {"fieldName": "pickup_zip", "scale": {"type": "categorical"}, "displayName": "ZIP"}, "y": {"fieldName": "trip_count", "scale": {"type": "quantitative"}, "displayName": "Trips"} }, "frame": {"title": "Trips by Pickup ZIP", "showTitle": True} } }, "position": {"x": 0, "y": 5, "width": 6, "height": 5} }, # Table - version 2, minimal column props! { "widget": { "name": "zip-table", "queries": [{ "name": "main_query", "query": { "datasetName": "by_zip", "fields": [ {"name": "pickup_zip", "expression": "

pickup_zip

"}, {"name": "trip_count", "expression": "

trip_count

"} ], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "table", "encodings": { "columns": [ {"fieldName": "pickup_zip", "displayName": "ZIP Code"}, {"fieldName": "trip_count", "displayName": "Trip Count"} ] }, "frame": {"title": "Top ZIP Codes", "showTitle": True} } }, "position": {"x": 0, "y": 10, "width": 6, "height": 5} } ] }] }

dashboard = { "datasets": [ { "name": "summary", "displayName": "汇总统计", "queryLines": [ "SELECT COUNT() as trips, AVG(fare_amount) as avg_fare, ", "AVG(trip_distance) as avg_distance ", "FROM samples.nyctaxi.trips " ] }, { "name": "by_zip", "displayName": "按ZIP码统计订单", "queryLines": [ "SELECT pickup_zip, COUNT() as trip_count ", "FROM samples.nyctaxi.trips ", "GROUP BY pickup_zip ", "ORDER BY trip_count DESC ", "LIMIT 10 " ] } ], "pages": [{ "name": "overview", "displayName": "纽约出租车概览", "pageType": "PAGE_TYPE_CANVAS", "layout": [ # 文本标题 - 不需要spec块！标题和副标题使用单独的小部件！ { "widget": { "name": "title", "multilineTextboxSpec": { "lines": ["## 纽约出租车仪表板"] } }, "position": {"x": 0, "y": 0, "width": 6, "height": 1} }, { "widget": { "name": "subtitle", "multilineTextboxSpec": { "lines": ["订单统计与分析"] } }, "position": {"x": 0, "y": 1, "width": 6, "height": 1} }, # 计数器 - 版本2，宽度2！ { "widget": { "name": "total-trips", "queries": [{ "name": "main_query", "query": { "datasetName": "summary", "fields": [{"name": "trips", "expression": "

trips

"}], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "counter", "encodings": { "value": {"fieldName": "trips", "displayName": "总订单数"} }, "frame": {"title": "总订单数", "showTitle": True} } }, "position": {"x": 0, "y": 2, "width": 2, "height": 3} }, { "widget": { "name": "avg-fare", "queries": [{ "name": "main_query", "query": { "datasetName": "summary", "fields": [{"name": "avg_fare", "expression": "

avg_fare

"}], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "counter", "encodings": { "value": {"fieldName": "avg_fare", "displayName": "平均费用"} }, "frame": {"title": "平均费用", "showTitle": True} } }, "position": {"x": 2, "y": 2, "width": 2, "height": 3} }, { "widget": { "name": "total-distance", "queries": [{ "name": "main_query", "query": { "datasetName": "summary", "fields": [{"name": "avg_distance", "expression": "

avg_distance

"}], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "counter", "encodings": { "value": {"fieldName": "avg_distance", "displayName": "平均距离"} }, "frame": {"title": "平均距离", "showTitle": True} } }, "position": {"x": 4, "y": 2, "width": 2, "height": 3} }, # 柱状图 - 版本3 { "widget": { "name": "trips-by-zip", "queries": [{ "name": "main_query", "query": { "datasetName": "by_zip", "fields": [ {"name": "pickup_zip", "expression": "

pickup_zip

"}, {"name": "trip_count", "expression": "

trip_count

"} ], "disaggregated": True } }], "spec": { "version": 3, "widgetType": "bar", "encodings": { "x": {"fieldName": "pickup_zip", "scale": {"type": "categorical"}, "displayName": "ZIP码"}, "y": {"fieldName": "trip_count", "scale": {"type": "quantitative"}, "displayName": "订单数"} }, "frame": {"title": "按上车ZIP码统计订单", "showTitle": True} } }, "position": {"x": 0, "y": 5, "width": 6, "height": 5} }, # 表格 - 版本2，仅保留必要的列属性！ { "widget": { "name": "zip-table", "queries": [{ "name": "main_query", "query": { "datasetName": "by_zip", "fields": [ {"name": "pickup_zip", "expression": "

pickup_zip

"}, {"name": "trip_count", "expression": "

trip_count

"} ], "disaggregated": True } }], "spec": { "version": 2, "widgetType": "table", "encodings": { "columns": [ {"fieldName": "pickup_zip", "displayName": "ZIP码"}, {"fieldName": "trip_count", "displayName": "订单数"} ] }, "frame": {"title": "热门ZIP码", "showTitle": True} } }, "position": {"x": 0, "y": 10, "width": 6, "height": 5} } ] }] }

Step 4: Deploy

步骤4：部署

result = create_or_update_dashboard( display_name="NYC Taxi Dashboard", parent_path="/Workspace/Users/me/dashboards", serialized_dashboard=json.dumps(dashboard), warehouse_id=get_best_warehouse(), ) print(result["url"])

undefined

result = create_or_update_dashboard( display_name="纽约出租车仪表板", parent_path="/Workspace/Users/me/dashboards", serialized_dashboard=json.dumps(dashboard), warehouse_id=get_best_warehouse(), ) print(result["url"])

undefined

Complete Example with Filters

带过滤器的完整示例

python

import json

python

import json

Dashboard with a global filter for region

带地区全局过滤器的仪表板

dashboard_with_filters = { "datasets": [ { "name": "sales", "displayName": "Sales Data", "queryLines": [ "SELECT region, SUM(revenue) as total_revenue ", "FROM catalog.schema.sales ", "GROUP BY region" ] } ], "pages": [ { "name": "overview", "displayName": "Sales Overview", "pageType": "PAGE_TYPE_CANVAS", "layout": [ { "widget": { "name": "total-revenue", "queries": [{ "name": "main_query", "query": { "datasetName": "sales", "fields": [{"name": "total_revenue", "expression": "

total_revenue

"}], "disaggregated": True } }], "spec": { "version": 2, # Version 2 for counters! "widgetType": "counter", "encodings": { "value": {"fieldName": "total_revenue", "displayName": "Total Revenue"} }, "frame": {"title": "Total Revenue", "showTitle": True} } }, "position": {"x": 0, "y": 0, "width": 6, "height": 3} } ] }, { "name": "filters", "displayName": "Filters", "pageType": "PAGE_TYPE_GLOBAL_FILTERS", # Required for global filter page! "layout": [ { "widget": { "name": "filter_region", "queries": [{ "name": "ds_sales_region", "query": { "datasetName": "sales", "fields": [ {"name": "region", "expression": "

region

"} # DO NOT use associative_filter_predicate_group - causes SQL errors! ], "disaggregated": False # False for filters! } }], "spec": { "version": 2, # Version 2 for filters! "widgetType": "filter-multi-select", # NOT "filter"! "encodings": { "fields": [{ "fieldName": "region", "displayName": "Region", "queryName": "ds_sales_region" # Must match query name! }] }, "frame": {"showTitle": True, "title": "Region"} # Always show title! } }, "position": {"x": 0, "y": 0, "width": 2, "height": 2} } ] } ] }

dashboard_with_filters = { "datasets": [ { "name": "sales", "displayName": "销售数据", "queryLines": [ "SELECT region, SUM(revenue) as total_revenue ", "FROM catalog.schema.sales ", "GROUP BY region" ] } ], "pages": [ { "name": "overview", "displayName": "销售概览", "pageType": "PAGE_TYPE_CANVAS", "layout": [ { "widget": { "name": "total-revenue", "queries": [{ "name": "main_query", "query": { "datasetName": "sales", "fields": [{"name": "total_revenue", "expression": "

total_revenue

"}], "disaggregated": True } }], "spec": { "version": 2, # 计数器使用版本2！ "widgetType": "counter", "encodings": { "value": {"fieldName": "total_revenue", "displayName": "总收入"} }, "frame": {"title": "总收入", "showTitle": True} } }, "position": {"x": 0, "y": 0, "width": 6, "height": 3} } ] }, { "name": "filters", "displayName": "过滤器", "pageType": "PAGE_TYPE_GLOBAL_FILTERS", # 全局过滤器页面必须设置此属性！ "layout": [ { "widget": { "name": "filter_region", "queries": [{ "name": "ds_sales_region", "query": { "datasetName": "sales", "fields": [ {"name": "region", "expression": "

region

"} # 不要使用associative_filter_predicate_group - 会导致SQL错误！ ], "disaggregated": False # 过滤器使用False！ } }], "spec": { "version": 2, # 过滤器使用版本2！ "widgetType": "filter-multi-select", # 不要使用"filter"！ "encodings": { "fields": [{ "fieldName": "region", "displayName": "地区", "queryName": "ds_sales_region" # 必须与查询名称匹配！ }] }, "frame": {"showTitle": true, "title": "地区"} # 始终显示标题！ } }, "position": {"x": 0, "y": 0, "width": 2, "height": 2} } ] } ] }

Deploy with filters

部署带过滤器的仪表板

result = create_or_update_dashboard( display_name="Sales Dashboard with Filters", parent_path="/Workspace/Users/me/dashboards", serialized_dashboard=json.dumps(dashboard_with_filters), warehouse_id=get_best_warehouse(), ) print(result["url"])

undefined

result = create_or_update_dashboard( display_name="带过滤器的销售仪表板", parent_path="/Workspace/Users/me/dashboards", serialized_dashboard=json.dumps(dashboard_with_filters), warehouse_id=get_best_warehouse(), ) print(result["url"])

undefined

Troubleshooting

故障排除

Widget shows "no selected fields to visualize"

小部件显示“没有选定的可视化字段”

This is a field name mismatch error. The

name

query.fields

must exactly match the

fieldName

encodings

Fix: Ensure names match exactly:

json

// WRONG - names don't match
"fields": [{"name": "spend", "expression": "SUM(`spend`)"}]
"encodings": {"value": {"fieldName": "sum(spend)", ...}}  // ERROR!

// CORRECT - names match
"fields": [{"name": "sum(spend)", "expression": "SUM(`spend`)"}]
"encodings": {"value": {"fieldName": "sum(spend)", ...}}  // OK!

这是字段名称不匹配错误。

query.fields

中的

name

必须与

encodings

中的

fieldName

完全匹配。

修复方法： 确保名称完全匹配：

json

// 错误示例 - 名称不匹配
"fields": [{"name": "spend", "expression": "SUM(`spend`)"}]
"encodings": {"value": {"fieldName": "sum(spend)", ...}}  // 错误！

// 正确示例 - 名称匹配
"fields": [{"name": "sum(spend)", "expression": "SUM(`spend`)"}]
"encodings": {"value": {"fieldName": "sum(spend)", ...}}  // 正确！

Widget shows "Invalid widget definition"

小部件显示“无效小部件定义”

Check version numbers:

Counters:
```
version: 2
```
Tables:
```
version: 2
```
Filters:
```
version: 2
```
Bar/Line/Pie charts:
```
version: 3
```

Text widget errors:

Text widgets must NOT have a
```
spec
```
block
Use
```
multilineTextboxSpec
```
directly on the widget object
Do NOT use
```
widgetType: "text"
```
- this is invalid

Table widget errors:

Use
```
version: 2
```
(NOT 1 or 3)
Column objects only need
```
fieldName
```
and
```
displayName
```
Do NOT add
```
type
```
,
```
numberFormat
```
, or other column properties

Counter widget errors:

Use
```
version: 2
```
(NOT 3)
Ensure dataset returns exactly 1 row

检查版本号：

计数器：
```
version: 2
```
表格：
```
version: 2
```
过滤器：
```
version: 2
```
柱状图/折线图/饼图：
```
version: 3
```

文本小部件错误：

文本小部件不能有
```
spec
```
块
直接在小部件对象上使用
```
multilineTextboxSpec
```
不要使用
```
widgetType: "text"
```
- 该类型无效

表格小部件错误：

使用
```
version: 2
```
（不是1或3）
列对象只需要
```
fieldName
```
和
```
displayName
```
不要添加
```
type
```
、
```
numberFormat
```
或其他列属性

计数器小部件错误：

使用
```
version: 2
```
（不是3）
确保数据集返回恰好1行

Dashboard shows empty widgets

仪表板显示空小部件

Run the dataset SQL query directly to check data exists
Verify column aliases match widget field expressions
Check
```
disaggregated
```
flag (should be
```
true
```
for pre-aggregated data)

直接运行数据集的SQL查询以确认数据存在
验证列别名与小部件字段表达式匹配
检查
```
disaggregated
```
标志（预聚合数据应设为
```
true
```
）

Layout has gaps

布局有间隙

Ensure each row sums to width=6
Check that y positions don't skip values

确保每行的总宽度为6
检查y位置是否有跳跃

Filter shows "Invalid widget definition"

过滤器显示“无效小部件定义”

Check

widgetType

is one of:

filter-multi-select

filter-single-select

filter-date-range-picker

DO NOT use
```
widgetType: "filter"
```
- this is invalid
Verify
```
spec.version
```
is
```
2
```
Ensure
```
queryName
```
in encodings matches the query
```
name
```
Confirm
```
disaggregated: false
```
in filter queries
Ensure
```
frame
```
with
```
showTitle: true
```
is included

检查

widgetType

是否为以下之一：

filter-multi-select

、

filter-single-select

、

filter-date-range-picker

不要使用
```
widgetType: "filter"
```
- 该类型无效
验证
```
spec.version
```
为
```
2
```
确保encodings中的
```
queryName
```
与查询的
```
name
```
匹配
确认过滤器查询中的
```
disaggregated: false
```
确保包含带
```
showTitle: true
```
的
```
frame
```

Filter not affecting expected pages

过滤器未影响预期页面

Global filters (on
```
PAGE_TYPE_GLOBAL_FILTERS
```
page) affect all datasets containing the filter field
Page-level filters (on
```
PAGE_TYPE_CANVAS
```
page) only affect widgets on that same page
A filter only works on datasets that include the filter dimension column

全局过滤器（在
```
PAGE_TYPE_GLOBAL_FILTERS
```
页面）影响所有包含该过滤器字段的数据集
页面级过滤器（在
```
PAGE_TYPE_CANVAS
```
页面）仅影响同一页面上的小部件
过滤器仅对包含该过滤器维度列的数据集有效

Filter shows "UNRESOLVED_COLUMN" error for

associative_filter_predicate_group

过滤器显示

associative_filter_predicate_group

的“UNRESOLVED_COLUMN”错误

DO NOT use
```
COUNT_IF(\
```
associative_filter_predicate_group`)` in filter queries
This internal expression causes SQL errors when the dashboard executes queries
Use a simple field expression instead:
```
{"name": "field", "expression": "\
```
field`"}`

不要在过滤器查询中使用
```
COUNT_IF(\
```
associative_filter_predicate_group`)`
该内部表达式会导致仪表板执行查询时出现SQL错误
改用简单的字段表达式：
```
{"name": "field", "expression": "\
```
field`"}`

Text widget shows title and description on same line

文本小部件的标题和描述显示在同一行

Multiple items in the
```
lines
```
array are concatenated, not displayed on separate lines
Use separate text widgets for title and subtitle at different y positions
Example: title at y=0 with height=1, subtitle at y=1 with height=1

```
lines
```
数组中的多个项会被拼接，而不是显示为单独的行
标题和副标题请使用单独的文本小部件，放在不同的y位置
示例：标题在y=0，高度=1；副标题在y=1，高度=1

databricks-aibi-dashboards

Original

Translation

AI/BI Dashboard Skill

AI/BI仪表板开发技能

CRITICAL: MANDATORY VALIDATION WORKFLOW

重要提示：强制验证工作流

Available MCP Tools

可用的MCP工具

Implementation Guidelines

实施指南

1) DATASET ARCHITECTURE (STRICT)

1) 数据集架构（严格要求）

2) WIDGET FIELD EXPRESSIONS

2) 小部件字段表达式

3) SPARK SQL PATTERNS

3) Spark SQL 写法

4) LAYOUT (6-Column Grid, NO GAPS)

4) 布局（6列网格，无间隙）

5) CARDINALITY & READABILITY (CRITICAL)

5) 基数与可读性（重要提示）

6) WIDGET SPECIFICATIONS

6) 小部件规范

7) FILTERS (Global vs Page-Level)

7) 过滤器（全局 vs 页面级）

Global Filters vs Page-Level Filters

全局过滤器 vs 页面级过滤器

Filter Widget Structure

过滤器小部件结构

Global Filter Example

全局过滤器示例

Page-Level Filter Example

页面级过滤器示例

8) QUALITY CHECKLIST

8) 质量检查清单

Complete Example

完整示例

Step 1: Check table schema

步骤1：检查表结构

Step 2: Test queries

步骤2：测试查询

Step 3: Build dashboard JSON

步骤3：构建仪表板JSON

Step 4: Deploy

步骤4：部署

Complete Example with Filters

带过滤器的完整示例

Dashboard with a global filter for region

带地区全局过滤器的仪表板

Deploy with filters

部署带过滤器的仪表板

Troubleshooting

故障排除

Widget shows "no selected fields to visualize"

小部件显示“没有选定的可视化字段”

Widget shows "Invalid widget definition"

小部件显示“无效小部件定义”

Dashboard shows empty widgets

仪表板显示空小部件

Layout has gaps

布局有间隙

Filter shows "Invalid widget definition"

过滤器显示“无效小部件定义”

Filter not affecting expected pages

过滤器未影响预期页面

Filter shows "UNRESOLVED_COLUMN" error for associative_filter_predicate_group

过滤器显示associative_filter_predicate_group的“UNRESOLVED_COLUMN”错误

Text widget shows title and description on same line

文本小部件的标题和描述显示在同一行

Filter shows "UNRESOLVED_COLUMN" error for
`associative_filter_predicate_group`

过滤器显示
`associative_filter_predicate_group`
的“UNRESOLVED_COLUMN”错误