简介这份Smartbi报表设置文档面向使用Smartbi进行报表开发的数据分析与报表人员聚焦从模板引用到预览发布的完整设置流程适合需要快速上手或查漏补缺的初中级使用者。资源包内含1个docx文档压缩包约1.05MB以图文步骤与代码片段结合的方式组织内容。文档围绕引用模板、页面设置、隔行不同颜色、列宽自适应、参数设置、参数排版与预览发布等环节展开其中列宽自适应给出了可全局或单列调用的通用脚本参数设置部分则提供了校验结束日期不早于开始日期、且间隔不超过90天的宏代码示例并附有参数排版每行不超过6个、两行时第二行至少保留2个等实操建议。目前已有1302人学习可作为报表样式调整、参数逻辑校验与发布前检查的参考模板帮助读者减少重复调试、提升报表规范性与美观度。1. Smartbi报表设置文档从连不上数据源到能交付的完整路径第一次接手 Smartbi 报表设置的人八成会卡在同一个地方数据源连上了数据集建好了拖进报表里数字却对不上。这不是工具的问题是设置链路里某个环节被默认值悄悄改掉了。Smartbi 报表设置文档要解决的核心问题就是把「数据源 → 数据集 → 报表布局 → 交互参数 → 权限发布」这条链路上每一步的配置项讲清楚让做报表的人知道每个开关动了之后会发生什么。它适合两类人一类是刚拿到账号、需要在一周内交出第一张业务报表的开发者另一类是已经能出图、但总在口径对齐和刷新性能上翻车的熟手。下面按实际配置顺序拆开讲每一步都落到具体参数和可复现的操作上。2. 数据源与数据集连接串、驱动和缓存三件事2.1 关系型数据源接入的最小配置Smartbi 连关系型数据库入口在「系统运维 → 数据连接」。新建连接时真正需要你手动填的只有五项驱动类型、连接地址、用户名、密码、连接池上限。驱动类型决定了后面 SQL 方言的解析方式选错不会报连接失败但会在写计算字段时给出莫名其妙的语法错误。# 以 MySQL 为例连接地址的标准写法 jdbc:mysql://10.0.0.21:3306/sales_dw?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse # 连接池关键参数在数据连接的高级设置里 初始连接数 2 最大连接数 20 获取连接超时(ms) 3000 空闲连接回收时间(s) 300地址里的serverTimezone必须显式指定否则跨时区部署时日期字段会整体偏移这个坑在报表层面表现为「本月数据少一天」排查起来很费时间。连接池最大连接数不要直接拉到 100Smartbi 的查询会并发占用连接数据库侧通常还有自己的上限20 到 30 是多数中小数据量场景的稳妥区间。获取连接超时设 3000 毫秒是为了让连接池耗尽时快速失败并抛出明确错误而不是让报表页面一直转圈。2.2 数据集类型的选择依据Smartbi 里能建的数据集不止一种选型直接决定后续能不能做参数联动和行级权限。常见的有 SQL 数据集、可视化数据集、存储过程数据集和 Java 数据集。判断标准很简单需要动态拼接条件的用 SQL 数据集业务人员要自己拖字段的用可视化数据集返回多结果集或需要复杂逻辑的用存储过程对接外部接口的才考虑 Java 数据集。SQL 数据集里有一个「参数定义」区域这里的参数名必须和 SQL 里的占位符完全一致大小写敏感。占位符写法是${参数名}不是?。很多人习惯 JDBC 的?占位粘进来发现预览报错就是因为 Smartbi 用的是自己的参数替换机制不是预编译语句。-- SQL 数据集示例按区域和日期区间过滤 SELECT region_name, order_date, SUM(amount) AS total_amount FROM sales_dw.fact_order WHERE region_name ${region} AND order_date BETWEEN ${beginDate} AND ${endDate} GROUP BY region_name, order_date参数说明region建议设为字符串类型并绑定下拉框beginDate和endDate设为日期类型并给默认值。如果不给默认值数据集预览时会因为参数为空而返回全量数据看起来像是「预览很慢」实际是条件没生效。日期参数在 SQL 里用字符串比较时格式要统一成yyyy-MM-dd否则数据库隐式转换可能导致索引失效。2.3 缓存策略与刷新时机数据集建好后默认是每次查询都回源。数据量大或并发高时必须在数据集属性里开缓存。缓存模式有三种不缓存、按时间过期、手动刷新。按时间过期适合 T1 的报表设成 3600 秒或 86400 秒手动刷新适合需要和上游调度对齐的场景。提示开启缓存后参数不同的查询会各自缓存一份结果。如果参数基数很大比如按用户 ID 过滤缓存会迅速膨胀这时候应该关掉缓存改用数据库侧的物化视图来扛。缓存键的构成里包含参数值所以同一个数据集用不同参数查出来的结果不会互相覆盖。但要注意如果 SQL 里用了NOW()或CURRENT_DATE这类函数缓存过期前结果不会变跨天时会出现「昨天打开还是今天的数据」的错觉。解决办法是把日期作为参数传进来而不是在 SQL 里取当前时间。3. 报表布局与交互参数让数字对得上的设置细节3.1 表格类报表的字段绑定与聚合方式Smartbi 的报表设计器里把数据集字段拖到单元格后默认聚合方式是「不聚合」。这意味着如果数据集返回了明细行报表会直接铺开而不是求和。很多人第一次做汇总表发现数字比预期大很多就是因为忘了改聚合方式。聚合方式在单元格属性里设置可选值有不聚合、求和、计数、去重计数、最大值、最小值、平均值。去重计数对应 SQL 的COUNT(DISTINCT)在统计订单数、用户数时必用。求和和平均值的计算发生在 Smartbi 侧还是数据库侧取决于数据集是否已经聚合过。如果数据集 SQL 里已经GROUP BY了报表侧再求和就是二次聚合结果会错。// 在报表的「加载完成」事件里做一次口径校验 // 用途把报表汇总值和数据集直查值做对比快速定位聚合层级问题 var reportTotal 0; var cells spreadsheet.getActiveSheet().getUsedRange().getValues(); for (var i 1; i cells.length; i) { reportTotal Number(cells[i][2]) || 0; } console.log(报表侧汇总值 reportTotal); // 再手动执行数据集 SQL 的 SUM对比两个数字这段脚本不是必须的但在排查「报表数字和数据库对不上」时非常有用。逻辑是先拿到报表当前展示的所有明细值在客户端做一次求和再和数据库直查的SUM对比。如果两者一致说明聚合层级没问题差异来自过滤条件如果不一致说明报表侧发生了二次聚合或漏掉了某些行。参数说明cells[i][2]里的2是金额所在列的索引实际使用时按列位置调整。3.2 参数联动与默认值设置参数联动的本质是「父参数变化时重新查询子参数的可选值」。Smartbi 里通过参数之间的依赖关系实现配置入口在参数面板的「联动设置」。常见场景是「省份 → 城市」两级下拉省份变的时候城市列表要跟着变。联动配置的关键是子参数的数据来源必须引用父参数。比如城市下拉的数据集 SQL 里要带上WHERE province ${province}。如果忘了这一步城市列表永远是全量联动就是假的。另外父参数如果允许多选子参数的 SQL 要用IN而不是并且 Smartbi 会把多选值拼成逗号分隔的字符串需要确认数据库驱动支持这种写法。默认值设置有两个位置容易混淆参数本身的默认值和报表打开时的初始值。前者在参数定义里设后者在报表属性里设。如果只设了参数默认值但报表属性里没勾选「使用参数默认值」打开报表时参数仍然是空的。这个设置项在不同版本里位置略有差异但逻辑一致报表初始化时会用一组初始参数去查数据这组初始参数从哪来必须明确指定。3.3 条件格式与数字格式的优先级条件格式和数字格式同时作用在一个单元格时优先级是条件格式的颜色覆盖数字格式的颜色但数字格式的小数位数、千分位、百分比符号不受条件格式影响。也就是说条件格式只管前景色和背景色不管显示格式。数字格式的设置建议统一在数据集字段层面做一次而不是在每个单元格里重复设。字段层面的格式会作为默认值带到所有引用它的单元格减少遗漏。百分比字段要注意数据库里存的是 0.15 还是 15决定了格式串是0.00%还是0.00%。前者会把 0.15 显示成 15.00%后者会把 15 显示成 15.00%。搞反了就是「增长率 1500%」这种翻车现场。4. 避坑与排查五条血泪经验4.1 现象报表打开空白数据集预览正常原因通常是参数没有默认值报表初始化时传了空值SQL 里WHERE field 过滤掉了所有行。解决方法是给每个参数设默认值或者在 SQL 里对空值做兼容处理比如AND (${region} OR region_name ${region})。后者会让 SQL 无法走索引数据量大时不建议。4.2 现象数字格式在导出 Excel 后丢失Smartbi 页面上的数字格式是前端渲染的导出 Excel 时如果没勾选「保留格式」导出的是原始值。解决方法是导出配置里开启格式保留或者把格式做在数据集字段上让导出时带出格式定义。另外超过 15 位的数字在 Excel 里会变成科学计数法这是 Excel 自身的限制不是 Smartbi 的问题需要在导出前把长数字转成文本。4.3 现象缓存开启后数据更新了但报表没变这是缓存未过期的正常表现不是 bug。排查时先看数据集的缓存设置确认过期时间。如果是手动刷新模式需要在「系统运维 → 缓存管理」里手动清一次。更隐蔽的情况是数据库侧有查询缓存Smartbi 的缓存清了但数据库返回的还是旧结果这时候要在数据库连接串里加useServerPrepStmtstrue之类的参数来绕过。4.4 现象参数多选后 SQL 报语法错误多选参数传给 SQL 时Smartbi 默认拼成A,B,C的形式如果 SQL 里写的是 ${param}展开后变成 A,B,C语法错误。正确写法是IN (${param})并且参数值本身要带引号。有些版本需要在参数定义里勾选「值带引号」选项具体看版本行为测试时先用两个值验证。4.5 现象报表在测试环境正常生产环境报连接超时先对比两个环境的数据源连接地址和连接池参数。常见差异是生产环境数据库有防火墙白名单Smartbi 服务器 IP 没加进去或者生产环境连接池上限设得比测试环境小并发一上来就耗尽。排查顺序telnet 数据库端口 → 看连接池监控 → 看数据库侧活跃连接数。不要一上来就改 SQL多数超时和 SQL 无关。5. 进阶技巧用数据集参数做行级权限和性能兜底行级权限的常见做法是在数据集 SQL 里加一个用户相关的过滤条件比如AND owner_dept ${currentUserDept}。currentUserDept这个参数不来自报表界面而是来自 Smartbi 的会话变量。配置方式是在数据集参数里把参数类型设为「系统变量」然后绑定到当前用户的部门属性。这样同一个报表不同部门的人打开看到的数据范围不同不需要为每个部门建一张报表。系统变量的可用值取决于 Smartbi 和权限系统的对接方式。如果对接的是内置用户体系变量名通常是SYS_CURRENT_USER和SYS_CURRENT_USER_DEPT这类。如果对接的是外部 LDAP 或单点登录变量名要看对接文档。测试方法是先在数据集里加一个SELECT ${SYS_CURRENT_USER} AS u预览看返回什么确认变量生效后再写进业务 SQL。性能兜底方面有一个容易被忽略的设置数据集的「查询超时」。默认值往往很大甚至不限制一个慢查询会把连接池占满拖垮整个报表模块。建议在数据集属性里设一个 30 到 60 秒的超时超时后返回明确错误而不是无限等待。同时配合数据库侧的慢查询日志把超时 SQL 捞出来优化。-- 行级权限 超时兜底的组合写法 SELECT order_id, owner_dept, amount FROM sales_dw.fact_order WHERE owner_dept ${SYS_CURRENT_USER_DEPT} AND order_date ${beginDate} -- 数据集属性里设置查询超时 45 秒缓存 按时间过期 1800 秒参数说明SYS_CURRENT_USER_DEPT是系统变量不需要在报表界面暴露beginDate是用户可选参数给一个近 30 天的默认值。超时设 45 秒是因为多数交互式报表的容忍上限在 30 到 60 秒之间超过这个时间用户会反复刷新反而加重负载。缓存 1800 秒适合半天更新一次的数据如果数据要求实时把缓存关掉但超时设得更短比如 15 秒让慢查询快速失败。还有一个技巧是用「数据集嵌套」来复用逻辑。比如多个报表都需要同一套过滤条件可以建一个基础数据集其他数据集通过SELECT * FROM (${基础数据集}) t WHERE ...的方式引用。这样过滤逻辑只维护一份改一处全生效。嵌套层数不要超过两层否则 SQL 解析和调试都会变得困难。我自己踩过最深的坑是早期做报表时把所有格式和过滤都放在报表层数据集只做最裸的SELECT *。结果报表越做越多每个报表都要重复设一遍格式改一个口径要翻十几张报表。后来改成数据集层做过滤和字段格式报表层只做布局和交互维护量直接降了一个数量级。这个习惯保持到现在能在数据集里定的绝不拖到报表里做。希望帮到你。本文还有配套的精品资源点击获取