# 指南

# 概述

  • LiteBI是一款专为API设计的报表软件,可以快速构建图表(柱状图、饼图、折线图、散点图、地图等),可快速创建仪表板
  • 不依赖其他软件(只需要JDK环境),一键启动,支持windows、linux、macOS
  • 支持图表、仪表板链接分享,方便将图表、仪表板嵌入到其他系统。
  • 仅支持API数据源,对API做了丰富的场景适配。支持动态http参数值,支持token验证,支持定期获取token,支持复杂嵌套的json参数,支持header传参

# 演示网站

# 为什么选择LiteBI?

  • 传统BI工具是在页面上配置数据库账号,然后在页面对数据进行分析汇总(比如选择表、维度字段、指标字段、指标函数),然后选择图形类型,配置图形参数,最后将分析结果以图形展示。这就面临一个问题,报表工具和分析数据的业务逻辑强耦合,比方说如果要切换报表工具,那上面的分析过程就要重做一遍,并且分析汇总后的结果数据只有报表工具自身持有,无法对其他系统提供数据服务。

  • LiteBI的设计理念认为报表系统应该前后端分离,报表工具仅仅只是一个图形渲染工具,不应该关心数据分析汇总的逻辑,数据分析应该全部放在后端服务中,数据通过API与报表对接,这样分析汇总的结果数据永远在后端接口服务中持有,后端接口服务可以对各个系统提供数据服务,并且一旦报表工具切换,数据资产仍然存在,不需要重新进行数据分析。

  • 鉴于以上理念,LiteBI设计成仅支持API数据源。如果您已经有大量的数据类API,比如您已经有DBAPI (opens new window)平台,LiteBI将是您不错的BI软件选择。又或者您非常看重数据资产化,希望分析数据全部放在后端接口服务中,LiteBI将是您不错的BI软件选择。

  • 有朋友会问其他BI工具也支持API数据源,为什么选择LiteBI?答案是LiteBI对API的支持做了很多适配设计,支持API使用的各种场景(同类产品对API的支持都是不足的)。比如说API访问的时候要进行token验证,支持定期获取token,也支持token失效的时候重新获取token;支持API传参,包括复杂嵌套的json参数;支持动态参数值,比如把页面上输入框、选择框的值作为请求参数去访问API获取数据。

  • 轻量化、简单、易用也是LiteBI遵循的设计理念,除了JDK,软件的安装不依赖其他软件,可以一键启动。软件对资源消耗极低,2核4g服务器即可运行。页面交互设计非常简洁,图表的创建操作简单,在数据API已有的情况下,半分钟即可创建一张图。如果搭配DBAPI (opens new window)(零代码创建API工具)的使用,可以让您高效快捷的进行数据分析。如果您处在中小企业、传统行业,数据分析团队小,开发能力不足,这样一款小巧简便的BI工具,会是您不错的选择。

# 基本概念

# 图表

  • 最基础的图表,可以是表格、柱状图、饼图、折线图、散点图、地图等。

# 仪表板

  • 仪表板是图表的集合,可以创建仪表板,将多个图表拼接成仪表板。类似于可视化数据大屏。仪表板中还可以添加输入控件,例如输入框、下拉选择器、日期选择器等,控件中的数据可以作为变量传入图表中,实现图表数据按条件动态变化。

# 变量

  • 变量分为系统变量和局部变量
  • 系统变量是系统中的全局变量,在API的传参中可以引用系统变量作为参数。比如API接口鉴权需要携带token,所有的API都需要使用token,就可以创建一个系统变量token,给多个图表中的API使用。并且系统变量可以设置是从API获取,并且可以定时访问API进行更新,保证token没有过期。
  • 局部变量只在仪表板中存在,仪表板中的每个输入控件(文本输入框、下拉选择器、日期选择器等等)会绑定一个局部变量名,仪表板中的图表中的API就可以引用此局部变量作为请求参数。典型场景是根据输入条件筛选数据。

# 快速开始

# 登录

  • 访问http://localhost:7000/login,默认用户名密码:admin/admin 图 0

# 创建第一个图表

  • 选择图表菜单,点击创建图表按钮

图 3

  • 进入图表编辑页面,选择折线图

图 4

  • 填写基本信息

图表名称填写第一个图表

图 5

  • 填写API数据集

LiteBI系统自带测试的数据API,地址是http://localhost:7000/test/data1,我们使用此API来创建折线图

方法选择post, 请求地址填写http://localhost:7000/test/data1(注意IP端口要改成您自己的IP和端口), 其余项不填。

图 6

  • 点击预览API数据按钮,您可以看到API返回的数据

图 7

  • 填写图表参数

分类字段填写month 指标字段填写apple

图 8

  • 预览图表

点击预览按钮,可以看到图表

图 9

  • 保存图表

点击保存按钮,即可保存图表

图 10

  • 返回图表列表

点击图表菜单,可以看到创建了第一个图表

图 11

  • 预览图表

鼠标悬浮在图上会显示一些操作按钮,点击查看按钮,可以在新页面看到图表

图 12

  • 编辑图表

点击编辑按钮,进入编辑页面,您可以修改配置再保存

图 13

  • 删除图表

点击删除按钮,在弹出的确认窗口中点确认,即可删除图表

图 15

  • 分享图表链接

点击分享按钮,弹窗中填写过期时间,即可生成分享链接,该链接可以嵌入其他系统的页面(使用iframe标签)。 过期时间如果填写-1表示永久有效。

图 16
图 17

# 创建第一个仪表板

  • 选择仪表板菜单,点击创建仪表板按钮,进入仪表板编辑页面

图 21

  • 选择左侧图表菜单,可以看到展示了所有图表,点击图表右上角的添加按钮,即可添加到仪表板

图 22

  • 选中图表可以拖动位置

图 23

  • 鼠标悬浮在图表右下角,可以拖动改变图表尺寸

图 24

  • 填写仪表板名称,点击保存按钮保存

图 25

  • 点击仪表板菜单,查看仪表板列表

图 28

  • 点击查看按钮,可以在单独的页面查看整个仪表板

图 26

  • 点击编辑按钮,可以进入修改仪表板页面

图 27

  • 点击删除按钮,可以删除仪表板

图 29

  • 点击分享按钮,在弹窗中填写过期时间,即可生成分享链接,该链接可以嵌入其他系统的页面(使用iframe标签)

过期时间如果填写-1表示永久有效。

图 30

  • 分享链接可以在链接管理页面查看

图 31

# API配置

  • LiteBI设计遵循一切数据皆来源于API,图表的数据均来自于API,系统变量的值可以来源于API,仪表板中部分控件的参数也可以来源于API(比如下拉选择器的所有选项)
  • 可以配置API的请求地址、请求方法、请求参数、请求头、数据转换脚本。

图 18

# 请求方法

  • LiteBI支持GET和POST两种请求方法

# 请求地址

  • 请求地址填写http协议的url,比如http://localhost:7000/test/data1

注意因为LiteBI使用js代码访问API,所以API端要设置跨域

# 请求参数

  • 如果是GET类型请求,参数只能写在地址中,比如http://localhost:7000/test/data?name=litebi&num=1, 如果参数值中有变量,可以使用${变量名}格式,比如http://localhost:7000/test/data?name=${name}&num=${num}

  • 如果是POST类型请求,参数写在参数输入框中,使用JSON格式填写,比如{"name":"litebi","num":1}, 如果参数值中有变量,可以使用${变量名}格式,比如{"name":${name},"num":${num}}

注意参数值如果是字符串变量,不需要在变量引用外层使用引号包裹

# 请求头

  • 请求头默认包含一项Content-Type: application/x-www-form-urlencoded,可以配置多个请求头,点击添加按钮,可以创建多个请求头

  • 对于POST类型请求,可以传入多层嵌套JSON格式的参数,比如{"name":"litebi","num":1,"data":{"name":"litebi","num":1}}

  • 如果您要传入嵌套JSON格式的参数,必须将请求头Content-Type设置为application/json 图 20

  • 请求头的值可以使用变量值,包括仪表板中的局部变量和系统变量,使用${变量名}格式

  • 典型使用场景是API鉴权,需要添加Authorization请求头,其值就是token,token又是一个系统变量,就可以如下填写

图 19

# API数据转换

  • 不同图表需要的数据格式不同,如果API返回的数据格式和图表需要的数据格式不一致,可以配置数据转换脚本,将API返回的数据转换成图表需要的数据格式。
  • 数据转换脚本有2种类型,JSONPath和 JavaScript 。脚本编写规则请参考数据转换脚本

如果不填写表示API返回的数据不需要转换

图 32

# 图表

  • 图表的创建和编辑,需要填写基本信息、API数据集、图表参数3部分。
  • 其中基本信息、API数据集每种图表配置方式都一样,只有图表参数配置不同。API数据集配置方法参考API配置,以下就介绍不同图表的参数配置。

图 33

# 柱状图

  • 柱状图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
        "banana": 200,
        "apple": 100,
        "month": "2024-01"
    }, {
        "banana": 190,
        "apple": 78,
        "month": "2024-02"
    }, {
        "banana": 157,
        "apple": 150,
        "month": "2024-03"
    }, {
        "banana": 120,
        "apple": 100,
        "month": "2024-04"
    }
]

  • X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
  • 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据
  • 图例如果需要显示就勾选,否则不显示
  • 标签代表柱子上的数据,如果需要显示就勾选,否则不显示

图 35

  • 可以制作分组柱状图,点击数据字段的添加按钮,填写新的字段banana

图 36

# 堆叠柱状图

  • 堆叠柱状图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
        "banana": 200,
        "apple": 100,
        "month": "2024-01"
    }, {
        "banana": 190,
        "apple": 78,
        "month": "2024-02"
    }, {
        "banana": 157,
        "apple": 150,
        "month": "2024-03"
    }, {
        "banana": 120,
        "apple": 100,
        "month": "2024-04"
    }
]

  • X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
  • 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据。点击添加按钮,可以追加新的数据字段,进行堆叠显示
  • 图例如果需要显示就勾选,否则不显示
  • 标签代表柱子上的数据,如果需要显示就勾选,否则不显示

图 37

# 折线图

  • 折线图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
        "banana": 200,
        "apple": 100,
        "month": "2024-01"
    }, {
        "banana": 190,
        "apple": 78,
        "month": "2024-02"
    }, {
        "banana": 157,
        "apple": 150,
        "month": "2024-03"
    }, {
        "banana": 120,
        "apple": 100,
        "month": "2024-04"
    }
]

  • X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
  • 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据
  • 图例如果需要显示就勾选,否则不显示
  • 标签代表柱子上的数据,如果需要显示就勾选,否则不显示
  • 圆滑折线,勾选后折线变成曲线显示

图 38

  • 可以制作分组折线图,点击数据字段的添加按钮,填写新的字段banana

图 39

# 堆叠折线图

  • 堆叠折线图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
        "banana": 200,
        "apple": 100,
        "month": "2024-01"
    }, {
        "banana": 190,
        "apple": 78,
        "month": "2024-02"
    }, {
        "banana": 157,
        "apple": 150,
        "month": "2024-03"
    }, {
        "banana": 120,
        "apple": 100,
        "month": "2024-04"
    }
]

  • X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
  • 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据。点击添加按钮,可以追加新的数据字段,进行堆叠显示
  • 图例如果需要显示就勾选,否则不显示
  • 标签代表折线上的数据,如果需要显示就勾选,否则不显示

图 40

# 面积图

  • 配置同折线图
  • 折线可以圆滑显示,可以勾选

图 42

图 41

# 堆叠面积图

图 43

# 柱线混合图

  • 堆叠折线图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
        "banana": 200,
        "apple": 100,
        "month": "2024-01"
    }, {
        "banana": 190,
        "apple": 78,
        "month": "2024-02"
    }, {
        "banana": 157,
        "apple": 150,
        "month": "2024-03"
    }, {
        "banana": 120,
        "apple": 100,
        "month": "2024-04"
    }
]

  • X轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
  • 柱图数据字段,填写柱状图需要展示的数据字段,填写apple,就展示apple对应的数据。
  • 折线数据字段,填写折线图需要展示的数据字段,填写banana,就展示banana对应的数据。
  • 柱图、折线图都可以添加多组数据,添加添加按钮,添加字段即可
  • 图例如果需要显示就勾选,否则不显示
  • 标签代表折线上的数据,如果需要显示就勾选,否则不显示

图 44

# 条形图

  • 柱状图要求API返回数据(或者数据转换后的数据)格式必须是对象数组格式,比如:
[{
        "banana": 200,
        "apple": 100,
        "month": "2024-01"
    }, {
        "banana": 190,
        "apple": 78,
        "month": "2024-02"
    }, {
        "banana": 157,
        "apple": 150,
        "month": "2024-03"
    }, {
        "banana": 120,
        "apple": 100,
        "month": "2024-04"
    }
]

  • Y轴字段填写分类的字段,以上面的数据为例,月份就是分类字段,所以填写month
  • 数据字段填写需要展示的数据字段,填写apple,就展示apple对应的数据
  • 图例如果需要显示就勾选,否则不显示
  • 标签代表柱子上的数据,如果需要显示就勾选,否则不显示

图 45

  • 可以制作分组条形图,点击数据字段的添加按钮,填写新的字段banana

图 46

# 堆叠条形图

# 饼图

图 47

# 环形图

图 48

# 半环形图

图 49

# 南丁格尔玫瑰图

图 50

# 表格

图 52

# 水球图

# 数字

# 雷达图

# 仪表板

  • 仪表板由图表和控件组成,可以添加已经创建好的图表到仪表板,如果需要条件筛选,可以添加控件到仪表板中。

# 图表操作

# 控件

  • 当图表数据需要切换参数,就会使用到控件

# 系统变量

  • 系统变量是系统中的全局变量,在API的传参中可以引用系统变量作为参数。
  • 比如API接口鉴权需要携带token,所有的API都需要使用token,就可以创建一个系统变量_token,给多个图表中的API使用
  • 系统变量值的引用使用${变量名}格式,例如${_token}

注意系统变量的名称必须是以下划线_开头,不能使用其他字符开头,例如_token

# 系统变量类型

  • 系统变量类型有3种,常量值、API、JS

JS暂不支持,在后续版本中会支持

# 常量值

  • 顾名思义,就是常量值作为系统变量。直接在页面填写常量值

# API

  • 通过API访问获取变量的值,这个值是一个动态值,需要设置更新策略,包含定时刷新和过期刷新两种策略。
# 定时刷新策略

设置固定频率,后台会定时访问API获取值,并更新变量值。

# 过期刷新策略

这种方式要求API返回的数据为JSON格式,并且包含过期时间字段(其值必须是时间戳毫秒格式)

  • 页面上设置过期时间提取表达式和数据提取表达式,每次访问API,后台会根据数据提取表达式提取数据作为变量值存下来,并且会根据过期时间提取表达式来提取过期时间保存下来,以后每次用到此变量的时候,会先检查变量的过期时间,判断是否过期,如果过期,则重新访问API获取值(并保存新的值和过期时间),否则直接使用保存的值。

# 数据转换脚本

如果API返回的数据格式和图表需要的数据格式不一致,可以配置数据转换脚本,将API返回的数据转换成图表需要的数据格式。

# JSONPath语法

要求API返回的数据必须是JSON格式

符号 含义
$ 表示整个数据
@ 表示当前数据
. 访问属性
[] 访问数组
* 匹配所有
[,] 访问数组指定索引
[?] 匹配条件
[?(condition)] 匹配条件
[?(@.age>18)] 匹配age大于18的
  • 示例1:

原始数据:

{
  "name": "张三",
  "age": 18,
  "address": {
    "province": "浙江",
    "city": "杭州"
  }
}

表达式结果如下

$.name
张三

$.age 
18

$.address
{
  "province": "浙江",
  "city": "杭州"
}

$.address.province
浙江

  • 示例2:
 原始数据
{
  data: [
    {
      "name": "张三",
      "age": 18,
      "address": {
        "province": "浙江",
        "city": "杭州"
      }
    },
    {
      "name": "李四",
      "age": 20,
      "address": {
        "province": "上海",
        "city": "上海"
      }
    }
  ],
  success: true,
  message: "success"
}

表达式结果如下

$.data[*]

[
  {
    "name": "张三",
    "age": 18,
    "address": {
      "province": "浙江",
      "city": "杭州"
    }
  },
  {
    "name": "李四",
    "age": 20,
    "address": {
      "province": "上海",
      "city": "上海"
    }
  }
]

# JavaScript语法

  • 使用JavaScript脚本,要求有return关键字,_data表示API返回的数据

  • 示例1:

 原始数据
{
  data: [
    {
      "name": "张三",
      "age": 18,
      "address": {
        "province": "浙江",
        "city": "杭州"
      }
    },
    {
      "name": "李四",
      "age": 20,
      "address": {
        "province": "上海",
        "city": "上海"
      }
    }
  ],
  success: true,
  message: "success"
}

脚本填写

return _data.data.map(item => {
  return {
    name: item.name,
    age: item.age,
    address: item.address.province + '-' + item.address.city
  }
})

结果

[
  {
    "name": "张三",
    "age": 18,
    "address": "浙江-杭州"
  },
  {
    "name": "李四",
    "age": 20,
    "address": "上海-上海"
  }
]