用途:管理分析仪表盘(Dashboard)的存储、创建与修改。仪表盘是 SQL 支撑的资源,新仪表盘与分析存放在模板表中,而非 settings KV 行。
存储:dashboards、dashboard_views、dashboard_shares、dashboard_revisions 保存仪表盘记录、筛选预设、共享授权与历史快照;analyses、analysis_revisions、analysis_shares 对应分析。旧 settings 键(如 u:<email>:dashboard-、adhoc-analysis-)仍作为回退读取,访问时复制进 SQL,不应再新建仪表盘 settings 行。
主要能力:用 mutate-dashboard 编辑现有仪表盘,用 update-dashboard 做新全量配置保存或低层 JSON-pointer 编辑;每次保存会把旧状态快照进 dashboard_revisions,可用 list-dashboard-revisions 查看撤销点、restore-dashboard-revision 恢复(恢复前先快照当前状态)。分析同理。禁止用 db-patch、原始 SQL 或 settings 键创建/修改仪表盘配置。
面板来源:panel.source 是后端选择器,可选 bigquery(字面仓库 SQL)、ga4(Google Analytics Data API JSON 描述符)、amplitude(Amplitude 查询 JSON 描述符)、first-party(对本模板 analytics_events 的只读 SQL)。不要用 app-db 作为来源。
创建:先读 <data-dictionary>,指标或粒度不明确时用 ask-question 澄清一次;未文档化的指标不要猜列名。构建含 name 与 panels 的 SqlDashboardConfig,每个面板需 id、title、source、chartType、width、sql;section 面板跳过 source/sql,可设 columns;extension 面板需 config.extensionId。用 update-dashboard 持久化,再用 pnpm action navigate --view=adhoc --dashboardId=<id> 打开。布局在内容宽度低于 md 阈值时始终单列堆叠,使用容器查询,侧边栏变窄也会堆叠。
筛选与变量:filters[] 定义全局控件,值通过 {{var}} 插值;日期范围输出 {{<id>Start}} 与 {{<id>End}}。筛选 id 必须唯一,重复会 400。用 variables 存共享常量,用 {{?country}}...{{/country}} 做条件块。筛选变更自动应用,无 Apply 按钮。
修改与排序:默认用 mutate-dashboard,传入字符串脚本,仅解析文档化的 dashboard.* 方法调用,参数须为 JSON 兼容字面量,不支持变量、循环、函数、网络、文件系统、数据库或其他 action。可用 panel、panels、panelsMatching 按 id 或元数据选择,用 moveToTop/moveBefore/moveAfter/moveToIndex 排序,避免索引算术。get-sql-dashboard 默认紧凑,返回面板摘要与 layout.panelOrder 等,需要完整 SQL 时传 includeConfig: true。
限制:扩展面板全出血渲染,不接收仪表盘筛选/变量/日期范围;嵌入不授予扩展访问权,需与仪表盘共享同一受众。保存路径会先试运行 BigQuery 面板,校验失败应修查询而非绕过。资料未提供收费、价格与平台信息。