1 概述

   参数是用于动态设定报表和查询条件的变量。用户可以根据需要设定参数值，从而灵活地调整数据模型的输出结果。

1、如果数据模型是 直连模式，则可以根据切换参数值动态筛选；如果数据模型是 抽取 模式，则只能根据设置的默认值筛选，无法动态切换。

2、假设 查询 的参数定义“参数 默认值 是必填； 那么在数据模型参数映射之后，默认值也需要填写；否则不能正常查询报表，会提示需要先设置参数默认值。

3、参数支持权限控制，做法与SQL查询一致，详情可查看：创建SQL查询。

4、如果参数的默认值不设置或者设置为'',则默认查询全部数据；如果要查实际的''数据，需要使用$$$EMPTY_VALUE$$$代表查询空字串。

5、数据模型的参数暂不支持全局参数。

6、参数可以应用计算度量、命名集、计算成员、计算列。

2 参数管理


1、在数据模型中、透视分析、即席查询、模型查询中如果使用了参数，可以设置备选值是否显示”全部“；如果勾选“显示[全部]”，在前端展示时，备选值中会多一个全部、全选的选项；不勾选则没有。

2、其中下拉多选、树形多选、列表多选 组件依然是显示全选：

数据模型参数主要的作用有如下两个方面：

          

2.1 参数映射、参数筛选

如果在查询中定义了参数，可以数据模型的参数管理进行映射、定义参数名称、数据类型、控件类型、默认值、备选值。

示例：根据输入的订单日期查询订单信息。

具体步骤如下：

1、创建数据模型并且在模型中添加 SQL查询 。

2、在 SQL查询 选择产品自带的northwind数据库下的”orders“表，编写SQL语句如下，{['orderDate'=${ParamName} ]}, 这种写法代表参数ParamName默认值可以为空(即不填写)：

3、保存SQL查询并回到模型。

4、点击参数工具栏的进入参数管理界面,映射参数，并设置参数相关选项：

选项内容
入口

点击 数据模型工具栏

一键映射
  • 在”参数面板“中单击 一键映射  按钮，系统自动创建模型参数，并建立好与 查询参数 的映射。
  • 自动映射的参数，默认沿用查询参数的名称、数据类型、控件类型等属性，且默认值为静态列表，值为查询参数默认值。
新建参数
  • 单个映射是指手工定义数据模型参数，并将其与私有查询资源中的参数进行映射关系设置。
  • 单击 新建参数  按钮，生成一个模型参数,需要手工映射参数、设置参数信息。
  • 新建的模型参数，映射关系，只允许选择带参数的查询。
复制参数

数据模型的参数支持复用其它数据模型的参数：通过参数复制功能，实现将目标参数克隆到当前数据模型。

控件类型
  • 支持输入框、列表(单选/多选)、列表(单选/多选)、树形(单选/多选)、日期、时间、日期时间。
默认值
  • 默认值可以不填写，代表查询全部数据。
  • 假设 查询 的参数定义“参数 默认值 是必填； 那么在数据模型参数映射之后，默认值也需要填写；否则不能正常查询报表，会提示需要先设置参数默认值。
  •  默认是”静态列表“选项。
备选值
  •  默认是”静态列表“选项，如果“静态列表”满足不了，可以使用 “SQL”，通过写SQL语句动态显示备选值。
  • SQL表达式支持参数嵌套，例如：select * from table where {[id = ${ParamName}]}，ParamName为参数名：
    “{[ ]}”表示该参数可为空；
     如果没有”{[]}“，只有${}, 比如id = ${ParamName}代表参数ParamName默认必须填写。
  • 支持预览sql语句的数据，如果SQL包含了参数，则以参数默认值进行预览。
数据源
  • 数据源：默认值为”静态列表“时不允许修改，默认禁用关联的查询参数的数据源；
  • 默认值为”SQL“选项时支持时，允许选择数据库(当前登录用户拥有查看权限的数据库)。
插入
X个参数未关联
  • 在”参数面板“中左下角显示当前数据模型的查询参数个数的信息，单击该信息，弹出所有查询参数的列表，列表中列出各参数的归属。

参数生效


  • 默认生效”勾选状态：模型取数子图如包含参数不管有无关联参数的表或查询，这张表或查询都会生效。如果默认勾选，代表的是过滤整个模型的数据，需要过滤事实表数据，所有会变成inner join。
  • “默认生效”不勾选状态：即按需取数，取数子图如没有选择关联了参数的表或查询，参数不会被生效；参数不勾选并且在前端使用了，默认代表过滤自己(映射的那张表)，那他就是 left join。
  • 参数拖入到报表中：如果与查询的数据不在同一个子图，无须生效；如果在同一个子图则会生效。

以"事实表"为中心，通过表或者查询的关系建立一个子图，子图(也可以理解为扩展表)，也可以理解为数据模型中的每个表都可构建一个子图，A表的子图是以A表为中心，根据筛选方向即箭头指向它的代表能筛选它的表，都会把它纳入子图中。


5、设置好参数后，保存数据模型，并去创建 交互式仪表盘，制作组件，并且拖入参数，可以根据参数查询订单信息，效果如下：


2.2 参数联动

参数联动是指参数A的选择影响参数B可选值的一种动态效果。

示例：区域、省份 参数联动查询。

具体步骤如下：

1、创建数据模型并且在模型中添加 即席查询 。

2、在 即席查询 选择产品自带的northwind数据库，分别拖拽”发货区域“和”省份“字段到条件区，自动生成两个参数:

3、保存即席查询后，并返回数据模型。

4、单击数据模型 设置参数 按钮，打开 参数管理 窗口，单击 一键映射 按钮，自动创建模型参数并映射即席查询中的参数：按照如下修改这两个参数设置：

销售区域参数

销售省份参数

5、参数设置后，保存该数据模型。

6、创建自助仪表盘，并去创建 交互式仪表盘，制作组件，并且从右侧资源树拖入“销售区域”与参数“销售省份”，联动动态效果如下：


2.3 下拉树参数

示例：查询区域-省份-运费列表

具体操作步骤如下：

1、创建数据模型，并且在模型中增加即席查询，并且把 省份 作为筛选条件，如下图：

2、保存模型，并且在 参数管理映射对应的参数，以及编写SQL构建层级关系，该示例为2层：

选项内容
参数
  • 参数具体操作可参考 本文 2.1 参数映射、参数筛选 章节
默认值
  • 真实值，显示值都填写F0。
select
  distinct  T6.`ShipRegion` as `F1`,
    T6.`ShipProvince` as `F0`
from
 `northwind_orders`   T6
limit 1


备选值
  • 真实值，显示值都填写F0， 父ID填写F1作为父层。
select
  distinct  T6.`ShipRegion` as `F1`,
    T6.`ShipProvince` as `F0`
from
 `northwind_orders`   T6


根节点
  • 真实值，显示值都填写F1。
select
  distinct  T6.`ShipRegion` as `F1`
from
 `northwind_orders`   T6


3、创建好参数之后，保存模型去创建仪表盘，拖入参数，可查看下拉树作为参数效果以及筛选效果：

2.4 参数动态应用

参数在计算度量、计算成员和命名集中的应用可以实现根据参数取值的不同而动态获取结果。

2.4.1 参数应用于计算度量

示例： 根据参数”结算时间点“选择的值，显示从当年1月1日至所选时间点的销量总和。

1、创建数据模型并且在模型中添加 即席查询 。

2、在 即席查询 选择产品自带的northwind数据库，拖拽字段如下：

3、保存即席查询后，并返回数据模型，基于时间字段”订单日期 创建时间层次，并且保存模型：

4、创建参数"结算时间点"

5、创建计算度量”累计销售量“，并且引用参数"结算时间点"，其中

6、保存计算度量及数据模型后，在交互式仪表盘中使用该计算度量：


2.4.2 参数应用于计算成员

详情也查看：自定义计算成员。

示例：排除所选区域的销售汇总。

具体操作步骤如下：

1、基于 2.3.1 创建好的数据模型，创建地理维度:

2、在数据模型创建参数“销售区域”：

3、创建计算成员”排除所选区域外度量汇总“：

5、保存计算成员及数据模型后，在自助仪表盘中运用该计算成员：



2.4.3 参数应用于命名集

详情也查看：自定义命名集。

示例：排除所选区域的销售汇总。

具体操作步骤如下：

1、基于 2.3.1 创建好的数据模型，参数“销量”：

2、创建命名集”销量大于某值的区域“：

5、保存命名集及数据模型后，在自助仪表盘中运用该命名集，可以通过参数”销量“实现动态变更


3 各个查询参数介绍

目前数据模型查询类型除数据源表(HaNa数据库的表可以有参数)、导入文件、日期表 之外，其它几种类型都支持带参数。

3.1 SQL查询

SQL查询中，在表达式中通过“${ParamName}”来标识参数，其中“ParamName”为参数名；用“{[ ]}”表示该参数可为空。如：参数表达式 {[id = ${产品编码}]}，表示id字段与参数“产品编码”匹配，且参数允许为空用于输出所有编码的产品。

示例如下图，详情可参考： 创建SQL查询。


3.2 即席查询

即席查询中的参数由拖拽字段生成的条件会自动生成参数，详情可参考：创建即席查询。

3.3 ETL高级查询

1、参数表达式中的参数名与参数设置的”参数名“必须一致。

2、定义参数时，可以设置参数为空；再使用参数的地方，用“{[ ]}”表示该参数可为空，即查询全部数据。

1、在ETL高级查询支持定义参数，先在ETL高级查询定义好参数之后，再用到可以调用参数的地方或者节点上。

2、ETL高级查询可以在”关系数据源“、“数据查询”节点使用定义好的参数，详情可参考：自助ETL。

  “数据查询”节点使用参数：

 ”关系数据源“节点使用参数：

3.4 存储过程查询

如果存储过程自动识别的参数默认值不能为空，在 数据模型/参数管理 参数映射时也不能设置参数默认值为空，否则会报错。

1、存储过程查询中的参数在定义存储过程的时候定义，根据参数默认值输出结果集。

2、详情可参考：接入存储过程查询。

3.5 脚本查询

脚本查询中的参数在脚本代码的结果集中定义，根据参数默认值输出结果集。

3.6 Java查询

如果 Java查询 自动识别的参数默认值不能为空，在 数据模型/参数管理 参数映射时也不能设置参数默认值为空，否则会报错。

1、存储过程查询中的参数在定义存储过程的时候定义，根据参数默认值输出结果集。

2、详情可参考：Java查询。