简介：这份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?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false # 连接池关键参数（在数据连接的高级设置里） 初始连接数 = 2 最大连接数 = 20 获取连接超时(ms) = 3000 空闲连接回收时间(s) = 300地址里的serverTimezone必须显式指定，否则跨时区部署时日期字段会整体偏移，这个坑在报表层面表现为「本月数据少一天」，排查起来很费时间。连接池最大连接数不要直接拉到 100，Smartbi 的查询会并发占用连接，数据库侧通常还有自己的上限，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 缓存策略与刷新时机
数据集建好后，默认是每次查询都回源。数据量大或并发高时，必须在数据集属性里开缓存。缓存模式有三种：不缓存、按时间过期、手动刷新。按时间过期适合 T+1 的报表，设成 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 的缓存清了但数据库返回的还是旧结果，这时候要在数据库连接串里加useServerPrepStmts=true之类的参数来绕过。
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 *。结果报表越做越多，每个报表都要重复设一遍格式，改一个口径要翻十几张报表。后来改成数据集层做过滤和字段格式，报表层只做布局和交互，维护量直接降了一个数量级。这个习惯保持到现在：能在数据集里定的，绝不拖到报表里做。希望帮到你。
本文还有配套的精品资源，点击获取
