查询参数组件
2025-5-14 About 58 min
看板参数(筛选器)的作用
看板参数的主要作用是让用户能够动态地调整和筛选数据显示，从而满足个性化需求或探索特定的数据视角。通过设置不同的参数，用户可以轻松地对数据集进行过滤，进而获得更加深入的数据洞察。
看板参数的类型
看板参数提供了多种类型的输入方式，以适应不同的使用场景和需求：
- 通过过滤：通用过滤器，可以实现 [=, ≠, >, <, 区间查询, 关键词查询] 等所有形式的过滤
- 下拉选框：从预定义的选项列表中选择一个或多个值。
- 日期范围：选择一个时间间隔，用以限定查询的数据时间段。
- 日期：选择具体的日期作为查询条件。
- 复选框：允许多选，适合需要从一系列选项中挑选出符合要求的组合。
- 单选：从一组选项中选出一个值，通常用于明确的选择情况。
- 范围查询：输入数值区间，适用于基于数值范围的筛选需求。
- 关键词搜索：通过输入关键字来快速查找匹配的数据记录。
# 添加参数(筛选器)
看板编辑模式下，菜单栏 选择 参数，添加看板参数
# 关联对象
看板参数通过添加 关联对象 建立与图表之间的关联
- 关联对象可以是数据集或者单个图表
- 一个参数可以关联多个不同的数据集或图表
- 关联对象为环境变量时，参数变更时所有使用了环境变量的组件都会被影响
# 关联到数据集
推荐优先选择参数与数据集模型维度节点关联, 通过关联到数据集之后，数据集对应的所有图表都会与看板参数建立连接;
# 排除关联图表
当我们通过数据集把看板参数间接关联到所有基于该数据集的图表之后，如果其中某个图表(如:全年销售总额)不希望受该参数的影响，可以使用参数排除对象配置
# 关联到环境变量
关联到环境变量之后, 可以用于数据集和查询变量设置, 看板 API 动态请求参数, Query 变量赋值等
# 看板参数关联字段设置
添加关联对象之后，当前参数具体作用到数据集哪个维度字段呢？ 一个数据集有多个字段，所以您还需要设定关联到数据集的具体字段，告诉当前参数是进行 日期列筛选、还是国家列筛选
图表中没有使用字段
看板参数可以关联到数据集的所有字段，即使该字段没有在图表上使用，也能关联
# 通用过滤器
- 通用过滤器与自助分析中过滤器类似，可以实现 [=, ≠, >, <, 区间查询, 关键词查询] 等所有形式的过滤
- 如果不希望用户加载关联字段内容，可以在参数配置栏关闭 允许加载 开关，这样用户就只能通过手工输入的方式设定过滤值
# 日期范围过滤
日期范围筛选器的配置项允许用户自定义日期选择器的行为和外观，以满足不同的数据筛选需求。以下是各个配置项的作用解释：
| 配置项 | 解释 |
|---|---|
| 日期类型 | 用户可以选择的日期粒度，具体包括： 年范围, 月范围, 日范围, 周范围, 季度范围 |
| 类型切换 | 控制在看板查看状态下是否允许用户在不同的日期类型之间进行切换。 日期类型切换关联的字段必须为日期类型, 不能是字符串日期 开启类型切换之后，切换到不同的日期类型，日期传值自动根据类型切换 |
| 日期值格式 | 选定的日期以何种值格式传递 当关联字段为日期类型时不需要设置，系统将根据日期类型自动设置日期格式 传值格式常用于以下场景： - 关联字段为 字符串日期 : 如yyyyMM, 202501 - 关联到环境变量 之后用于 字符串拼接 |
| 过滤类型 | 定义日期范围如何应用于数据过滤，如闭区间[a,b]或开区间(a,b)等。 |
| 最大天数 | 设置用户可选择的最大日期跨度，例如30表示最大只能选30天的范围。 |
| 最小/大日期距今 | 设置日期控件上用户可以选的日期, 小于最小、大于最大的日期既不能作为起始日期也不能作为结束日期。 |
| 可清空 | 允许用户清除已选择的日期设置，恢复默认关闭。 |
| 动态日期 | 启用后，看板初始化加载时根据当前日期自动计算并设置日期范围 |
| 开启快捷日期 | 启用后，在日期选择器中显示预设的快捷日期选项，方便快速选择。 |
| 快捷日期 | 用户可以自定义快捷日期选项，包括名称（如“最近1周”）、偏移量和单位等。 |
| 日期格式 | 设置日期的显示格式，如yyyy-MM-dd表示年-月-日格式。 |
| 连接符号 | 设置日期范围中的连接符号，默认为~，也可以修改为其他符号，如-或至。 |
# 动态日期
动态日期配置开启后，看板初始化加载时根据当前日期自动计算并设置日期范围
开始日期距今 和 结束日期距今 分别用于定义日期范围的起始点和终止点相对于当前日期的偏移值。
- 数值：输入具体的天数、周数、月数或年数, 负数代表往前偏移。
- 单位：选择时间单位，如“天”、“周”、“月”或“年”。
例如：
- 如果设置“开始日期距今”为“-7 天”，表示到7天前的日期结束。
- 如果设置“结束日期距今”为“0 天”，表示从今天开始。
取起始值 用于把动态偏移之后的日期日计算到 指定 类型 的“第一天”或“最后一天”。
- 年、月、日、周：选择时间粒度。
- 开始/结束：确定是基于周期的开始还是结束。
例如： 假设今天是2023年10月5日，我们希望查看上一个月的数据，并且想要数据范围从上一个月的第一天到最后一天：
通过这些配置项，用户可以灵活地定义动态日期范围，以满足不同场景下的数据筛选需求，同时保持操作的简便性和结果的准确性。
# 日期类型切换
日期类型切换功能允许用户在不同的时间粒度（如年、月、周等）之间灵活切换，以满足不同场景下的数据查询和分析需求。这种切换不仅改变了用户界面中的日期选择方式，还直接影响了后台数据库查询的逻辑和格式化方式。以下是详细的解释：
日期类型切换原理
当用户在前端界面上选择不同的日期类型时（例如从“年”切换到“月”），系统会根据当前选中的日期类型动态调整日期选择器的显示和交互方式：
- 年：用户可以选择具体的年份。
- 月：用户可以选择具体的月份。
- 周：用户可以选择具体的一周。
- 日：用户可以选择具体的日期。
数据库查询逻辑变化
后台数据库查询逻辑会根据用户选择的日期类型自动调整日期字段的格式化方式，以确保查询结果的准确性和一致性, 如：
- 选择年份：数据库查询通过
DATE_FORMAT(日期字段, 'yyyy')来提取并匹配年份信息。 - 选择月份：数据库查询通过
DATE_FORMAT(日期字段, 'yyyy-MM')来提取并匹配年月信息。
关联字段要求
为了保证日期类型切换功能的正确性和有效性，关联的字段必须是日期类型，而不能是字符串类型的日期表示。这是因为：
- 日期类型字段 可以被
date_format函数处理。
示例说明
假设有一个订单表，其中包含一个order_date字段，记录了每个订单的日期信息。用户选择了“年”作为日期类型，并选择了2024年，则数据库查询语句可能如下：
SELECT * FROM orders WHERE DATE_FORMAT(order_date, 'yyyy') = '2024';
1
如果用户切换到“月”，并选择了2024年8月，则查询语句会自动调整为：
SELECT * FROM orders WHERE DATE_FORMAT(order_date, 'yyyy-MM') = '2024-08';
1
这样，通过日期类型切换功能，用户可以方便地在不同的时间粒度上查看和分析数据，同时系统能够自动适配相应的查询逻辑，确保数据展示的准确性和效率。
# 日期
单日期 筛选控件的配置与日期范围基本相同
| 配置项 | 解释 |
|---|---|
| 日期类型 | 用户可以选择的日期粒度，具体包括： 年, 月, 日, 周, 季度 |
| 类型切换 | 控制在看板查看状态下是否允许用户在不同的日期类型之间进行切换。 日期类型切换关联的字段必须为日期类型, 不能是字符串日期 开启类型切换之后，切换到不同的日期类型，日期传值自动根据类型切换 |
| 日期值格式 | 选定的日期以何种值格式传递 当关联字段为日期类型时不需要设置，系统将根据日期类型自动设置日期格式 传值格式常用于以下场景： - 关联字段为 字符串日期 : 如yyyyMM, 202501 - 关联到环境变量 之后用于 字符串拼接 |
| 过滤类型 | 定义日期如何应用于数据过滤，如：=， >, <, >=, <= |
| 最小/大日期距今 | 设置日期控件上用户可以选的日期, 小于最小、大于最大的日期既不能作为起始日期也不能作为结束日期。 |
| 可清空 | 允许用户清除已选择的日期设置，恢复默认关闭。 |
| 动态日期 | 启用后，看板初始化加载时根据当前日期自动计算并设置日期 |
| 开启快捷日期 | 启用后，在日期选择器中显示预设的快捷日期选项，方便快速选择。 |
| 快捷日期 | 用户可以自定义快捷日期选项，包括名称（如“最近1周”）、偏移量和单位等。 |
| 日期格式 | 设置日期的显示格式，如yyyy-MM-dd表示年-月-日格式。 |
# 复选框
| 配置项 | 解释 |
|---|---|
| 最少/多选择项 | 配置用至少、最多能选择几个项目 |
| 过滤类型 | 控制在看板查看状态下是否允许用户在不同的日期类型之间进行切换。 日期类型切换关联的字段必须为日期类型, 不能是字符串日期 开启类型切换之后，切换到不同的日期类型，日期传值自动根据类型切换 |
| 过滤类型 | 定义日期如何应用于数据过滤，如：=，≠ |
| 手动输入添加值 | CheckBox 的选项为固定的静态选项，用户可以通过手工输入的方式维护选项 |
| 可选项 | 当前CheckBox的选项 |
| 添加目标字段成员 | 用户也可以从左侧加载目标字段成员之后，添加到可选项 |
# 选项值与选项名
如果用户需要选项显示值与传递值区分开可以输入 选项值|选项名称 的格式添加选项
# 选项宽度设置
# 单选
| 配置项 | 解释 |
|---|---|
| 过滤类型 | 控制在看板查看状态下是否允许用户在不同的日期类型之间进行切换。 日期类型切换关联的字段必须为日期类型, 不能是字符串日期 开启类型切换之后，切换到不同的日期类型，日期传值自动根据类型切换 |
| 过滤类型 | 定义日期如何应用于数据过滤，如：=，≠ |
| 手动输入添加值 | CheckBox 的选项为固定的静态选项，用户可以通过手工输入的方式维护选项 |
| 可选项 | 当前CheckBox的选项 |
| 添加目标字段成员 | 用户也可以从左侧加载目标字段成员之后，添加到可选项 |
# 下拉选框
# 下拉框筛选器配置项
| 配置项 | 解释 |
|---|---|
| 是否单选 | 开启后，用户只能选择一个选项。 |
| 可清空 | 开启后，用户可以清除已选择的选项。 |
| 折叠多选 | 开启后，在多选模式下折叠显示已选择的选项。 |
| 选项排序 | 设置选项的排序方式，升序或降序 |
| 过滤类型 | 设置过滤条件的类型，如: =，≠, >, < |
| 设置默认值 | 默认选择的值，用户可以在下方输入框中设置默认值，支持变量，点击“Test”按钮进行测试变量解析。 |
| 可选值查询 | 开启后，允许通过查询获取可选值。 |
| 允许创建条目 | 开启后，用户可以手动输入并创建新的选项条目。 |
| 默认选中第一个 | 开启后，默认选中列表中的第一个选项。 |
| 远程搜索 | 开启后，支持远程搜索功能，实时加载搜索结果。 |
| 显示选项值 | 开启后，在界面上显示具体的选项值。 |
| 使用缓存 | 开启后，使用缓存机制提高加载速度和性能。 |
# 下拉可选值查询
通过配置下拉框可选值查询维度字典表来提高选项获取效率，以及如何实现（选项值和选项名）分离的效果。
下拉框加载比较慢怎么办
默认行为
下拉框选项是通过关联的数据集字段构造子查询来获取的。如果这个数据集是一个性能较慢或比较大的事实表、视图，那么每次字段选项子查询都会带来较大的查询开销。
可选值查询设置
为了优化性能，用户可以启用“可选值查询”功能，并设置一个直接查询维度字典表的SQL语句。这种方法可以直接从专门设计用于快速查找的维度字典表中获取选项，从而显著提升选项加载速度和整体性能。
示例配置: 假设我们有一个国家列表需要展示在下拉框中：
SELECT country_code AS option_value,
country_name AS option_name
FROM countries;
1
2
3
2
3
在这个例子中：
country_code是选项值，它将作为实际提交给服务器的值。country_name是选项名，它是用户在界面上看到的文本。
总结
| 配置项 | 解释 |
|---|---|
| 设置可选值查询 | 用户可以指定一个直接查询维度字典表的SQL语句，提高选项加载效率。 |
| 选项值与选项名 | 当查询返回两个字段时，第一个字段作为选项值，第二个字段作为选项名。 |
| 示例SQL | SELECT option_value, option_name FROM dimension_dictionary; |
通过这种方式，不仅可以大幅减少因频繁查询大型事实表带来的性能问题，同时也能为用户提供更加友好和直观的操作体验。
# 下拉框缓存不推荐的配置
如果不配置可选值查询，在选项列表不会频繁变动的情况下，用户还可以打开下拉框缓存, 默认缓存有效期12小时，可配置。
以下场景下缓存不会生效：
- 维度配置有可选项查询(包含参数配置与数据集维度配置)
- 数据集该字段配置有权限规则
# 下拉框参数级联
参数级联常用于有上下层级关系的两个下拉框之间，上级下拉框参数值变更之后下级下拉框选项内容被上级选项限定，如: 国家->大区, 公司->部门
- 建立级联第一步是，在下级下拉框配置界面，打开级联开关，并选则级联上级参数
提示
当下级参数与正确的上级建立级联关系之后，仅代表上级变更，下级会刷新参数选项，并不代表下级能够利用上级的选项内容来限定选项
- 用户可以通过下面两种方式建立上下级选项直接的逻辑关系
2.1 方法1 上下级对应数据集中层级维度的上下级(后续的更新版本会尝试仅需要上下级在同一数据集即可建立逻辑关系)2.2 方法2 上级关联环境变量，下级开启
维度层级
可选值查询，并在查询脚本中使用上级绑定的环境变量上级国家绑定到country变量
下级开启`可选值查询`
# 下拉框选项远程搜索
下拉框支持远程搜索使用场景，维度成员数量巨大超过阈值之后会被截断，远程搜索可以精确限定选项范围从而控制选项数量 维度字段上的远程搜索，自动通过字段like匹配,自动生成维度列查询如下：
SELECT sales_region -- 维度字段
FROM (
-- 数据集查询定义
) cb_view
WHERE sales_region like '%we%'
GROUP BY sales_region
1
2
3
4
5
6
2
3
4
5
6
您也可以在开启可选值查询中通过keywords内置变量自定义远程查询条件
# 范围查询
| 配置项 | 解释 |
|---|---|
| 交互类型 | 设置用户与筛选器之间的交互方式是滑动条还是输入框。 |
| 过滤类型 | 选择用于匹配输入值和数据集之间的关系类型，如[a,b]。 |
| 最小值 | 设置可选范围的下限。 |
| 最大值 | 设置可选范围的上限。 |
| 步长 | 设置滑动条每次移动的增量。 |
| 格式化 | 提供高级模式和配置格式化的选项，以便对显示的数据进行精细化控制。 |
| 信息栏宽度 | 设置滑动条右边展示的数据范围信息区域的宽度，单位为像素（px）。 |
# 输入框
输入框多用于关键词搜索场景
| 配置项 | 解释 |
|---|---|
| 过滤类型 | 选择用于匹配输入值和数据集之间的关系类型，如like, not like, =等。 |
| 多关键词 | 输入框中输入英文逗号会被拆解为多个关键词， 设置多个关键词之间的逻辑关系，可以选择 OR或AND。 |
| 框内提示 | 为输入框提供提示信息，帮助用户理解应如何输入数据。 |
# 参数容器
默认情况下，看板参数通常被放置在看板头部的参数栏中。然而，如果需要在看板中间或特定位置添加查询参数，可以通过以下步骤实现：
- 在看板中间添加查询参数
- 添加看板参数容器：首先，在您希望添加查询参数的位置插入一个“看板参数容器”。这个容器可以像其他组件（例如图表、文本框等）一样，在看板上进行任意调整其位置和大小。
- 调整看板参数容器：根据您的布局需求，调整该容器的位置和尺寸。这使得您可以精确控制查询参数出现在看板上的具体位置，并确保它与看板中的其他元素协调一致。
- 在参数容器中添加参数组件：一旦参数容器就位，接下来就可以在其内部添加具体的参数组件了。这些组件可以包括但不限于日期范围选择器、下拉菜单、文本输入框等，用于接收用户的查询条件。
# 看板参数配置
- 打开参数变更实时生效之后，每次改变参数内容不需要点击查询直接刷新看板
- 参数名宽度默认为80px，在参数配置中可以批量调整
- 看板参数支持设置参数名称在上输入项上方，支持统一设置高宽
# 网格看板参数隐藏
网格看板支持参数隐藏, 典型使用场景，看板间联动，传参且不希望该联动参数显示
- 在编辑模式下，隐藏参数右上角会有已隐藏图标
- 在查看模式下，隐藏参数不显示
- 隐藏参数中如果有筛选条件，仍然生效
# 环境变量控制参数是否显示
- 环境变量控制参数是否显示, 参数显示时不生效
- 与隐藏不同，通过变量控制的是否显示的看板参数在不显示时，参数不参与筛选数据
# 看板懒加载 v1.12
如果不希望打开看板之后图表立即加载，可开启看板被动加载，图表不会自动加载，在设置查询条件后手动点击查询按钮进行加载。
# 我的常用参数组
在看板参数上的参数比较多或者值选择比较复杂的时候, 为了避免用户重复的选择设置看板参数, 用户可以保存当前看板参数状态值为常用参数组, 之后需要改变条件时一键恢复
保存的参数模板如果与当前看板上的参数不一致(模块保存之后, 某些参数被删除), 恢复参数组, 不会恢复被删除的参数
我的常用看板参数组