NocoBase 数据可视化数据查询指南：Builder 与 SQL 双模式详解

NocoBase 数据可视化数据查询指南Builder 与 SQL 双模式详解【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase图表配置面板整体上划分为三大部分数据查询、图表选项与交互事件底部是取消、预览、保存按钮。其中「数据查询」是整个图表能力的起点——它决定了一张图表的数据从哪来、取哪些字段、如何聚合与过滤。本文以 NocoBase 数据可视化插件的数据查询面板为核心系统讲解 Builder图形化与 SQL手写语句两种查询模式、度量/维度/过滤/排序/分页的完整配置方法并结合仓库源码packages/plugins/nocobase/plugin-data-visualization说明底层的数据结构、校验逻辑与服务端执行链路帮助你快速上手并排错。面板结构「数据查询」面板自上而下依次包含数据源与集合必填选择数据来源与数据表度量Measures必填展示的数值字段维度Dimensions按字段分组日期/品类/地区等过滤Filter设置过滤条件、≠、、、包含、范围等多个条件可组合排序Orders选择排序字段与升/降序分页Limit / Offset控制数据范围与返回顺序。面板最顶部是操作栏模式Builder图形化简单方便与SQL手写语句更灵活运行查询点击执行数据查询请求查看结果打开数据结果面板可切换Table / JSON查看再次点击收起面板。Tips为了更方便地配置当前内容可以先折叠收起其他面板聚焦单一配置区域。面板数据结构的源码映射从源码层面看Builder 模式的配置项与前端定义的QueryValue一一对应见 QueryBuilder.tsxtype QueryValue { collectionPath?: string[]; measures?: any[]; dimensions?: any[]; filter?: { logic: $and | $or; items: any[] }; orders?: any[]; limit?: number; offset?: number; };其中过滤条件filter默认以$and且逻辑组合空过滤初始化为{ logic: $and, items: [] }collectionPath则以[数据源 key, 集合名]的数组形式定位数据表。这些字段最终会通过 API 提交给服务端对应服务端QueryParams类型中的同名属性见 server/types.ts。Builder 模式Builder 模式面向大多数日常场景通过下拉选择与表单即可完成查询构建无需书写任何 SQL。选择数据源与集合在「数据查询」面板将模式切换为Builder选择数据源与集合数据表若集合不可选或列表为空优先检查集合数据表是否已创建、当前用户是否拥有读取权限。数据源选项并非对所有数据源开放。从源码看只有数据库类型的数据源DEFAULT_DATA_SOURCE_KEY即主数据库或数据源配置带isDBInstance标记以及声明了capabilities.query能力的数据源才会出现在可选项列表中见 QueryBuilder.service.ts。数据源/集合选项通过getCollectionOptions生成两级级联结构数据源 → 集合见同文件 L208-L227。配置度量Measures度量是图表中展示的数值字段支持选择一个或多个数值字段作为度量为每个度量设置聚合方式Sum、Count、Avg、Max、Min。常用场景Count统计记录数Sum统计总额。服务端对每个度量项定义了结构化属性见 server/types.tsexport type MeasureProps { field: string | string[]; type?: string; aggregation?: string; alias?: string; distinct?: boolean; };其中field支持点路径写法如user.name关联字段alias用于给聚合结果列起别名例如SUM(total_amount) AS total中的totaldistinct可控制是否去重计数。是否配置了聚合aggregation还直接影响排序字段的可选项——只有在存在聚合度量时排序候选才会被限制为已选维度与度量字段见下文「排序」。配置维度Dimensions维度是按字段分组如日期、品类、地区的依据选择一个或多个字段作为分组维度日期时间字段可设置格式如YYYY-MM、YYYY-MM-DD便于按月/日分组统一展示。日期格式的候选列表由字段类型驱动源码中getFormatterOptionsByField会根据字段 interfacedatetime、date、time等返回对应的格式化选项集formatters.datetime/formatters.date/formatters.time见 QueryBuilder.service.ts。维度项同样支持别名与格式属性见 server/types.tsexport type DimensionProps { field: string | string[]; type?: string; alias?: string; format?: string; options?: any; };过滤、排序与分页过滤添加条件、≠、包含、范围等多个条件可通过$and/$or组合过滤值还支持绑定上下文变量如当前用户、当前时间排序选择字段与升/降序asc/desc服务端排序项还支持nulls属性控制空值排位default/first/last见 server/types.ts分页设置Limit与Offset控制返回行数调试时建议先设置较小的Limit加快预览。排序的可选字段在「存在聚合度量」时会被自动收窄为已选择的维度与度量buildOrderFieldOptions的逻辑避免对未出现在结果集中的字段排序导致报错见 QueryBuilder.service.ts。运行查询与查看结果点击「运行查询」执行请求图表预览即时刷新返回后点击「查看结果」/「查看数据」打开结果面板可切换Table / JSON检查列名与类型映射图表字段前先在这里确认列名与类型避免后续图表为空或报错。后续字段映射后续在配置「图表选项」时基于已选择数据源和集合的表字段进行字段映射如折线图配置xField维度、yField度量、seriesField系列详见 图表选项。Builder 模式的提交校验点击运行/保存前前端会调用validateQuery对查询配置做完整性校验见 QueryBuilder.service.ts要点包括必须选择查询模式modeBuilder 模式必须提供collectionPath数据源集合与至少一个度量measures存在聚合度量时排序字段必须属于已选维度/度量集合过滤条件不允许存在空path未选择过滤字段。这也解释了「最小可用配置」选择集合 至少一个度量建议再添加维度便于分组展示。SQL 模式当 Builder 无法表达复杂查询时多表 JOIN、VIEW、子查询、窗口函数等切换到 SQL 模式直接手写查询语句。编写查询在「数据查询」面板将模式切换为SQL输入 SQL 查询语句点击「运行查询」执行SQL 模式支持完整的查询语句包括多表 JOIN、VIEW 等。示例按日期统计订单金额SELECT TO_CHAR(order_date, YYYY-MM) as mon, SUM(total_amount) AS total FROM order GROUP BY mon ORDER BY mon ASC LIMIT 100;服务端将 SQL 文本放在QueryParams.sql下mode: sql分支直接透传执行见 server/types.ts 与 actions/query.ts。运行查询与查看结果点击「运行查询」执行数据结果支持分页展示可切换Table / JSON检查列名与类型映射图表字段前先在这里确认列名与类型避免后续图表为空或报错。字段映射在「图表选项」中基于查询结果列完成映射。默认会自动将第一列作为维度x 轴或分类、第二列作为度量y 轴或值因此请特别注意 SQL 中字段的书写顺序SELECT TO_CHAR(order_date, YYYY-MM) as mon, -- 维度字段 放在第一列 SUM(total_amount) AS total -- 度量字段 放在后面建议保持列名稳定后再进行图表映射调试阶段设置LIMIT减少返回行数以加快预览。在 SQL 中使用上下文变量SQL 编辑器右上角提供上下文变量插入按钮x按钮选择确认后会在光标位置或选中内容位置插入变量表达式。例如{{ ctx.user.createdAt }}注意不要自己另外加引号——变量表达式会被引擎解析后替换为实际值手动加引号会导致语法错误。更多上下文变量的说明参见 上下文变量 与 SQL 模式查询数据。两种模式的互通性Builder 与 SQL 两种模式互不互通配置独立存储以最后保存时的配置模式为准生效参见 常见问题。因此切换模式后需要重新配置不要期望一方配置自动迁移到另一方。查询的服务端执行链路点击「运行查询」后前端请求charts:queryData接口服务端按以下中间件管线依次执行见 actions/query.tscompose([checkPermission, parseVariables, cacheMiddleware, queryData])checkPermission基于 ACL 校验当前用户对目标集合的查询权限root角色直接放行无权限返回 403No permissions。测试用例覆盖了无权限场景见 query.test.tsparseVariables解析查询中的上下文变量如{{ ctx.user.id }}、{{$nDate.now}}并区分 Builder/SQL 与新旧变量解析通道variableResolution/rd变量解析失败时返回空结果集。相关用例见 query.test.tscacheMiddleware若启用了查询缓存cache.enabled uid按[uid, query]作为缓存键读写data-visualization缓存命名空间refresh标记可强制跳过缓存拉取最新数据ttl控制过期秒数见 actions/query.tsqueryData根据dataSource定位数据源通过repository.query({ context, ...queryOptions, timezone })执行查询并返回结果。时区来自请求头x-timezone确保日期维度按用户时区聚合。从这段链路可以看到数据查询面板产出的不仅仅是「一段 SQL」而是一套结构化、可校验、带权限与缓存机制的查询协议这也是 Builder 模式能够安全组合过滤、排序、分页的底层保证。常见注意点与调试建议综合数据查询的官方指引与 快速开始 文档实际操作中请注意最小可用配置选择集合 至少一个度量建议添加维度便于分组展示日期维度格式按月统计建议选择YYYY-MM避免横轴不连续或错乱查询为空或图表未显示优先检查集合/权限与字段映射在「查看结果」中确认列名与类型是否匹配图表映射预览是临时态所有修改默认自动实时刷新左侧预览但只有点击「保存」才会真正写入数据库并对所有用户生效点击「取消」或刷新页面则回退到上次保存状态调试技巧SQL 与自定义配置模式下为避免频繁刷新建议编写完成后再手动点击「预览」列名稳定后再映射SQL 模式下先运行查询确认列名与类型再进行图表字段映射避免后续报错。完整的从零到一流程添加图表区块 → 配置数据查询 → 运行查询并查看数据 → 配置图表选项 → 预览与保存可继续阅读 快速开始图表的展示配置与字段映射细节参见 图表选项SQL 模式的进阶能力JOIN/VIEW、上下文变量、字段映射规则参见 SQL 模式查询数据。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考