图表通用配置

图表是报表中展示数据的基本单位。用户可以通过将数据源绑定到图表并配合可交互的「过滤条件」来展示数据。

同一报表中的图表可以绑定不同的数据源。

图表的控制面板一般分为「基础」、「数据」和「高级」三个部分。

图表的基础设置

图表的基础设置如下图:

图片

在这部分中用户可以配置图表中与数据无关的展示选项,比如图表名称、图表简介和图表尺寸等。

其中图表的宽度有12个挡可以调节,12对应占满整行。图表的高度可以以像素为单位进行调节。在某个图表处于选中状态时,可以通过拖拽边和角的蓝色标记直接调节大小。多个图表将按照各自的大小依次排开:

图片

表格」和「文本」图表可以设置为根据内容自适应高度:

图片

图表的颜色搭配可以进行自定义,您可以选择使用报表主题的色系或自定义图表各个部分的颜色:

图片

对于不同的图表,颜色自定义的配置不尽相同,您可以根据设置的具体情况进行配色的设计。

大屏图表的特殊基础设置

在大屏图表的基础设置中可以调整图表的宽高和位置。宽高和位置都是以像素为单位的,位置的坐标原点是大屏的左上角。如果拖拽调整宽高和位置不能满足您对于精度的要求,这里可以进行像素级别的调整:

图片

图表的数据设置

图表的数据设置可以配置绑定到图表的数据,绑定分为SQL建模与API拉取两种方式:

图片

各图表的API配置以及返回格式请参照「API方式连接数据源」。

如果选择SQL方式绑定图表数据,需要先建立并绑定SQL模型到图表,具体请参照「SQL方式连接数据源」。

选择SQL方式绑定数据时,各类型图表的个性化配置可以在文档的「图表配置」文件夹下各图表自己的文档中查找,这里介绍几个较为通用的数据配置:

过滤条件的豁免

如果用户添加了「过滤条件」并传递了值,但是在「SQL模型的语句中并没有关联这个过滤条件」,Sugar会报错提示过滤条件传递了但是SQL中没使用。

这样做是有原因的,因为如果用户添加了一个新的过滤条件,但是在图表中却忘记了修改相应的伪SQL语句,这时SQL并没有任何的语法错误,会照样查询到数据,但是这时的数据结果可能是不正确的,因为忽略了一个过滤条件。所以Sugar不允许这样的情况出现,我们会主动报错,提醒用户修改SQL语句,此时用户除了修改SQL语句外,还有另外一个选择,那就是豁免该过滤条件对当前图表的影响,如下图在绑定图表的数据时可以选择要豁免的条件。

图片

数据自动补全

数据自动补全是指Sugar将SQL查询出来的数据中空缺的数据自动填补上对应的值,自动补全可以自动填补零或补空。对于折线图而言补空的效果是折线补空的地方无值,折线分成多段)。自动补全有以下四种方式:

简单补全

简单补全是指补全查询结果中没有取值的列:

图片

按日期补全

在一些情况下,我们期望数据能够自动按照日期连续,对缺失日期的数据自动补上零或者空之类。
例如折线图展示1号到30号的数据,但是由于一些原因,数据库中缺失5、6号两行数据,这时如果没有自动补全功能,折线图上就会完全忽略5、6号的数据,4号之后就直接是7号,用户完全不知道缺失了两天的数据,这样对用户来说并不友好。

因此Sugar提供了数据按照日期自动补全的功能。
需要注意的是,按日期补全需要图表绑定的SQL模型中有日期类型的字段。

原始数据:

图片

按日期补零后效果:

图片

按日期补空后效果:

图片

按时间补全

按时间补全和上一节的按日期补全很类似,按日期补全的数据粒度是天,按时间补全的数据粒度可以让您自己选择(支持小时、半小时、10分钟、1分钟、10秒等)。

如果数据的开始和结尾不在某一天的0点或24点,可以选择「从数据起始日的0点开始补全」或「补全到数据结束日的24点」。

需要注意的是,按时间补全需要图表绑定的SQL模型中有时间类型的字段。

图片

原始数据:

图片

4小时粒度的时间补零的效果:

图片

按数字序列补全

图片

有时,数据库中保存的时间,日期或其他有序数据是使用数字序列标识的,比如:-2,-1,0,1,2,3.....。或者是有补位格式的:-02,-01,00,01,02,03.....。
此时,如果你的数据中这个序列存在空缺,可以选择「按数字序列补全」对数据进行补全,补全数据的类型同样可以选择补空或者补零。
首先需要选择数字序列所在的字段,这个字段在 SQL 模型中的数据类型需要是整数或字符串。比如上图例子中选择了 member_id 字段。其内容如下:

图片

如果在 SQL 模型中将 member_id 字段的数据类型设置为「整数」,则补全结果如下:

图片

可以看到,虽然数据库中保存的是有补位格式的数字,由于数据类型设置为「整数」,补位的零被忽略了。

如果在 SQL 模型中将 member_id 字段的数据类型设置为「字符串」,则补全结果如下:

图片

此时,Sugar会识别数字序列中的补位形式,并自动生成相同形式的补充数据。

这里需要注意,数据中的补位格式需要固定,如果有:01,2,03这样的数据,会导致最终结果中补位形式的不统一

最后,通过配置「序列起始值」和「序列结束值」可以对数据补全的范围进行设定,范围外不会进行补全,但如果有数据还是会展示。

绑定所有行转列

当SQL模型中开启了「行转列」功能后,我们可以逐列将行转换的新列绑定到了表格中进行展示。
燃鹅,在一些情况下有可能有哪些行转换的新列我们都不确定。如果某一天新增了一个指标,我们只能修改SQL模型新增这样一列并且将它绑定到图表中才能展示,这样做很麻烦,而且如果以后又不断的新增指标怎么办?
因此Sugar允许用户将所有的行转换的列一键绑定到各图表(表格、折线、柱状、饼图等),当图表绑定的SQL模型开启了行转列功能后,可以在图表的控制面板中找到开关:

图片

数据的自动刷新(大屏)

在大屏中,每个需要绑定动态数据的图表都可以设置是否需要定时自动刷新数据:

图片

需要注意的是,如果某次自动刷新时没有取得正确的数据,这个图表的自动刷新会停止,需要手动刷新页面。

图表的高级设置

图表的高级设置各不相同,可以在文档的「图表配置」文件夹下各图表自己的文档中查找。

图表的下钻设置

在编辑报表时,某些图表的控制面板里可以看到「下钻」选项卡:

图片

下钻是指在点击本图表的某一部分时,可以打开一个新的图表或超链接,进而查看与图表此部分相关的详细信息。Sugar支持无限级的下钻,只要下钻的图表也是支持下钻的图表类型,就可以继续配置进一步的下钻。

有些个性化的下钻配置,如绑定超链接的数据字段等,请移步具体图表的配置文档。

下钻的触发

每种图表触发下钻的方式不同,例如:折线图的触发方式是点击折线上的某一点,地图是点击某个区域,表格是点击某行或某列。

总体来说,可以下钻的图表分为两大类:

  • 单一种类下钻:这种类型的图表只能触发一种类型的下钻。比如柱状图,点击每个柱子触发的是同一种下钻图表,只不过根据点击柱子的不同,触发时传递给下钻图表的下钻参数有所不同。这类图表的下钻配置只需要选择触发的下钻类型即可:

图片

  • 多种类下钻:这种类型的图表可以触发多种类型的下钻。比如表格,可以设置点击每行触发下钻,点击某行中的某一列触发下钻。此时需要一个触发ID来进行区分,根据具体的提示填写即可,如表格需要填写触发列的ID。在触发下钻时传入下钻图表的下钻参数中也会带上这个ID信息供数据拉取使用:

图片

下钻的参数

当图表的下钻被触发时,打开的超链接或图表会收到与上层图表点击区域相关的下钻参数,下钻图表可以利用这个信息来拉取数据。

当然,报表的过滤条件在下钻图表中依然可以使用,与普通图表的使用方式相同。

下钻参数不需要用户进行配置,每种图表触发下钻时传递给下层图表的参数格式是固定的,大体格式如下:

[
    {
        "item": {
            "name": "老用户",
            "value": 11472,
            "category": "2018-09-01",
            "type": "line"
        },
        "fireKey": ""
    },
    {
        "item": {
            "subsys": "北京总部",
            "module": "市场部",
            "business": "第一小分队",
            "name": "李四",
            "value": 7673456.78,
            "value_level": "green",
            "url": "http://www.baidu.com",
            "subsys_rowspan": 1,
            "module_rowspan": 1,
            "business_rowspan": 1,
            "name_rowspan": 1,
            "value_rowspan": 1
        },
        "fireKey": "name"
    }
]
  • 总体来说下钻参数是一个数组,当有多层下钻时,数组里包含每一层图表传递给下层的参数,这些参数在本层图表中都是可以使用的
  • 下钻参数的每一项由item和fireKey组成

    • item是一个对象,里面有触发下钻相关的信息,比如触发下钻的表格某行的数据。
    • fireKey是一个字符串,在某种图表可以触发多种下钻的情况下用来区分触发的是哪一种下钻

您可以在配置下钻图表时点击「图表的调试按钮」来查看上层图表传递下来的具体信息。具体过程可以参照下面的两个示例。

下钻参数的使用

下钻参数的使用分三种情况:

  • 下钻图表用API拉取数据时,在POST请求的body中带上下钻参数
  • 下钻图表SQL方式拉取数据时,将下钻参数嵌入SQL语句中
  • 下钻类型为超链接类型时,在URL中附加下钻参数

API拉取数据时使用下钻参数

如果下钻图表是使用API方式拉取数据的,那么下钻参数会自动放在API请求的body中发送到用户的后端,用户在API中利用这些参数拉取数据即可。

如果您还需要更详细的信息请参考「图表API请求中的下钻参数

在下钻图表中配置好您要拉取数据的API后点击「图表的调试按钮」即可看到API请求的详情。

SQL拉取数据时使用下钻参数

如果下钻图表是使用SQL方式拉取数据的,那么可以将下钻参数嵌入到下钻图表绑定的SQL模型的SQL语句中,具体的语法请参照「SQL语句中嵌入下钻参数

超链接类型的下钻中使用下钻参数

如果下钻是超链接类型的,则下钻参数会放在url的查询参数中:

图片

柱状图的下钻示例

柱状图只能配置一种下钻,在配置中只需要开启下钻,并选择下钻图表类型即可,这里选择的是「表格」:

图片

点击柱状图的某一个柱子,会弹出下钻图表的编辑弹框:

图片

点击数据选项卡中的调试按钮,可以就看到下钻参数了,也就是刚才我们点击的柱子的详细信息:

图片

接下来就可以在API或SQL拉取数据时利用这些下钻参数了。

表格下钻示例

表格可以配置多个下钻,总的开关可以控制所有下钻是否开启,单个下钻也可以控制自己的开关,如果删除了某个下钻,下钻的图表配置以及其更深层次的下钻图表配置都会被删除:

图片

示例中配置了两个类型的下钻:

第一个的触发ID是空的,意味着是点击行触发一个表格类型的下钻:

图片

点击调试可以看到,点击行的全部数据都传递到了下钻图表中:

图片

接下来就双可以在API或SQL拉取数据时利用这些下钻参数了。

第二个下钻配置的触发ID是表格中「姓名」一列的列ID,现在点击姓名列的某一个值会触发一个折线图类型的下钻:

图片

点击调试,可以看到点击行的详细数据,以及是点击哪个列触发的下钻:

图片

接下来就叒可以在API或SQL拉取数据时利用这些下钻参数了。

图表的联动设置

在编辑报表时,某些图表的控制面板里可以看到「联动」选项卡:

图片

在这个选项卡中,可以选择一些图表作为本图表的下级图表。当点击本图表的某一个数据项时,这个数据项的信息会作为联动参数传递到下级图表中,下级图表会利用这些信息刷新图表数据。

需要注意的是:在配置联动时,Sugar会检查所有图表间的联动关系,图表之间不能存在循环依赖,一个图表不能有多个上级图表。

联动的触发和取消

每种图表触发联动的方式不同,例如:折线图的触发方式是点击折线上的某一点,地图是点击某个区域,表格是点击某行或某列。

总体来说,可以触发联动的图表分为两大类:

  • 单一种类联动:这种类型的图表只能触发一种类型的联动。比如饼图,点击每个扇区会触发同一批下级图表的联动,只不过根据点击扇区的不同,触发时传递给下级图表的联动参数有所不同。这类图表的联动配置只需要选择需要触发哪些下级图表的联动即可:

图片

  • 多种类联动:这种类型的图表可以触发多种类型的联动。比如表格,可以设置点击某行触发一批下级图表联动,点击某行中的某一列触发另一批下级图表联动。此时需要一个触发ID来进行区分,根据具体的提示填写即可,如表格需要填写触发列的ID。在触发联动时传入下级图表的联动参数中也会带上这个ID信息供数据拉取使用:

图片

某个图表可以触发联动时,将鼠标浮动在这个图表上,在图表的右上角会有一个红色的图标提示。

如果用户点击了某个数据项触发了联动,相应的数据项会高亮,下级图表会根据用户的配置刷新。

此时点击图表左上角的「取消下级联动」按钮,或再次点击高亮的数据项都可以使本图表和下级图表恢复初始状态。

图片

图片

联动的参数

当图表的联动被触发时,下级图表会收到与上级图表点击区域相关的联动参数,下级图表们可以利用这个信息来拉取数据。

当然,下级图表在因为联动而刷新时,报表的过滤条件依然在影响这些图表。

联动参数不需要用户进行配置,每种图表触发联动时传递给下级图表的参数格式是固定的,大体格式如下:

"dependence": {
    "item": {
        "subsys": "北京总部",
        "module": "市场部",
        "business": "第一小分队",
        "name": "张三",
        "value": 6672389,
        "url": "http://www.baidu.com"
    },
    "fireKey": "name"
}
  • 联动参数是一个对象,由item和fireKey组成
  • item是一个对象,里面有触发联动相关的信息,比如触发联动的表格某行的数据。
  • fireKey是一个字符串,在某种图表可以触发多种联动的情况下用来区分触发的是哪一种联动

在某个图表的上级图表触发联动之后,您可以点击下级图表的「图表的调试按钮」来查看上层图表传递下来的具体信息。

联动参数的使用

联动参数的使用分两种情况:

  • 联动图表用API拉取数据时,在POST请求的body中带上联动参数
  • 联动图表用SQL方式拉取数据时,将联动参数嵌入SQL语句中

API拉取数据时使用联动参数

如果下级图表是使用API方式拉取数据的,那么联动参数会自动放在API请求的body中发送到用户的后端,用户在API中利用这些参数拉取数据即可。

如果您还需要更详细的信息请参考「图表API请求中的联动参数

需要注意的是:这些下级图表同时也是普通图表,API需要处理其上级图表没有触发联动(即联动参数不存在)时的数据拉取逻辑。

在本图表的上级图表触发联动,且本图表数据API配置好后,您可以点击本图表的「图表的调试按钮」来查看到API请求的详情。

SQL拉取数据时使用联动参数

如果下级图表是使用SQL方式拉取数据的,那么可以将联动参数嵌入到下级图表绑定的SQL模型的SQL语句中。

需要注意的是:这些下级图表同时也是普通图表。因此在将联动参数嵌入SQL中时,需要确保其上级图表没有触发联动(即联动参数不存在)时SQL可以正确运行,为此联动参数的嵌入语法提供了配置默认值的语法。

具体的语法请参照「SQL语句中嵌入联动参数」。

图表的调试和刷新

在图表的控制面板和绑定的SQL模型中所做的任何修改都可以通过「刷新图表」来看到效果。
更改了图表相关的过滤条件值时也可以通过点击「刷新图表」来进行更新。

调试是非常有用的工具,在使用SQL绑定数据时出现的问题几乎都可以在这里进行定位。

图片

在图表控制面板中的数据选项卡中点击调试按钮可以打开调试弹框。

SQL方式绑定图表数据的调试

这里展示了从发起查询到最终获得到数据的每一步转换。用户可以在这里定位到大多数可能出现的问题。

图片

SQL方式的调试弹框分为以下几个部分:

数据调试结论

这里的信息代表现有的SQL数据绑定配置是否能成功的拉取到数据,如果有问题会提供报错信息。

图片

图片

POST到后端的数据

这里显示了POST到后端的数据,这里包含了拉取数据所需要的「过滤条件」等信息。

如果是下钻图表,这里还可以看到上层图表传递下来的「下钻参数」等信息。

如果是某个处于联动触发状态图表的下级图表,这里还可以看到上级图表传递下来的「联动参数」等信息。

这些信息是发送到Sugar后端使用的,用户可以根据这些数据来决定将那些查询条件或下钻参数嵌入到SQL语句中。

图片

SQL语句

在这个部分用户可以看到「SQL模型中用户编辑的伪SQL语句」、「Sugar最终生成的送入库里执行的语句」以及转换所消耗的时间。

图片

SQL查询结果

这里是SQL语句查询到的原始SQL结果以及查询耗时。

图片

SQL中间结果

这里展示了Sugar对原始查询结果进行的转换,包括进行行转列、数据补全等操作后的结果。

图片

格式化后结果

这里是Sugar将数据格式化为图表相关的数据结构的结果。

图片

API方式绑定图表数据的调试

图片

API方式的调试弹框分为以下几个部分:

数据调试结论

这里的信息代表API的返回格式是否符合本图表的要求,如果不符合会提供报错信息。

图片

图片

后端数据API

这里可以看到本次请求的API的地址。

图片

API请求的Header

这里显示了POST到后端的Header内容,可能会包含用户的验证信息以及「API Token」等。

图片

API请求的Body

这里显示了POST到后端的Body内容,这里包含了拉取数据所需要的「过滤条件」等信息,过滤条件的API格式可以参考「过滤条件api格式」。

如果是下钻图表,这里还可以看到上层图表传递下来的「下钻参数」等信息。

如果是某个处于联动触发状态图表的下级图表,这里还可以看到上级图表传递下来的「联动参数」等信息。

用户可以在自己的API中读取这些信息并进行图表数据的拉取。

图片

API的返回结果

这里可以看到API的返回结果以及API请求消耗的时间等。

图片

图表名称的动态化

图表名称的动态化是指图表的名称根据用户的交互而改变,例如图表名称中嵌入过滤条件,如下图:

图片

图表名称中嵌入过滤条件的语法是:{conditions.key},其中key是指过滤条件的「查询key值」。

本页内容