数据分析与通用查询
约 1139 字大约 4 分钟
2025-03-03
数据分析服务用于将已配置的数据源和查询模板转成可授权的通用查询，适合看板、业务统计和聚合展示。设备最新属性/历史数据可直接使用 Things 对应接口；复杂报表可先通过定时任务生成统计表，再交给数据分析查询。
选型与数据准备
| 数据场景 | 推荐方式 |
|---|---|
| 原始设备属性和历史 | Things 物模型数据查询 |
| 按小时/天汇总的稳定业务指标 | 定时任务生成统计表 |
| 多张关系表联合统计 | 管理员维护 SQL 模板/视图后配置查询 |
| TDengine 等时序聚合 | 使用对应数据源与该引擎支持的函数 |
查询配置是受控的服务端配置，不让普通前端提交任意 SQL 或数据库凭据。
1. 数据源
通过平台数据源管理创建配置，接口前缀为 /api/v1/data/datasource/manage，包括 create、get-list、get-one、update、delete、ping。数据源是平台基础设施，仅有权的平台管理员可管理。
| 字段 | 作用 |
|---|---|
| code/name | 稳定数据源编码和显示名 |
| dbType | mysql、pgsql、sqlite 或 tdengine |
| driver | TDengine 等所需驱动 |
| dsn | 连接串，作为敏感配置管理 |
| maxIdleConns/maxOpenConns | 连接池上限 |
| funcMap | 按引擎覆盖函数模板 |
| status | 1 启用，2 禁用 |
先测试连接，再创建查询。SQLite 可用于本机验证，但内置时间格式函数不保证与其他引擎一致；PostgreSQL 的 time_bucket 还取决于扩展是否安装。
2. 配置一个查询
通过 /api/v1/data/query/manage 的管理接口创建表查询或 SQL 查询。下面示例需要先创建含 tenant_code/date/num/type 的 demo_daily_count 表并插入测试数据，不是平台预置查询编码：
{
"code":"demoDailyCount",
"name":"业务统计",
"dataSourceCode":"<source-code>",
"type":"table",
"table":"demo_daily_count",
"columns":"date,num,type",
"isToHump":1,
"permConfig":{"isFilterTenant":1}
}SQL 模式使用 type: "sql" 和服务端维护的 sql。默认列、排除列、默认排序、预定义过滤器都在查询配置维护；列名和函数需要与真实表结构匹配。
3. 执行单个查询
POST /api/v1/data/query/info/get-one：
{
"code":"demoDailyCount",
"aggregations":[{"argFunc":"sum","column":"num"}],
"groupBy":"hourFmt:date",
"columns":"hourFmt:date",
"filter":{"type:eq":"publish","dayFmt:date:>=":"2026-10-01"},
"page":{"page":1,"size":24,"orders":[{"field":"date","sort":0}]}
}返回包含 list 的对象。aggregations 是数组，不能写成顶层 argFunc。排序 sort 为 0 升序、1 降序；分组列和聚合列需符合目标数据库规则。
只统计总量时可省去 groupBy，并选择 sum/count 等聚合；按日曲线将 hourFmt 改为 dayFmt。响应字段受列名和驼峰转换影响，页面应按实际合同解码。
4. 批量查询
同一个页面要多组数据时使用 POST /api/v1/data/query/info/get-list：
{
"finds":[
{"code":"demoDailyCount","aggregations":[{"argFunc":"sum","column":"num"}]},
{"code":"demoDailyCount","columns":"dayFmt:date","groupBy":"dayFmt:date","aggregations":[{"argFunc":"sum","column":"num"}]}
]
}返回 list 是按请求顺序排列的结果数组集合，不是带名字的统计对象，也不表示对多组数据建立数据库快照事务。
函数与过滤
| 形式 | 含义 |
|---|---|
dayFmt:date、hourFmt:date | 日期/小时格式分组 |
monthFmt:date、yearFmt:date | 月/年格式，注意是 monthFmt |
timeBucket1h:ts、timeBucket1d:ts | 按数据源能力分桶 |
field:eq、field:in | 精确匹配、逗号分隔集合 |
field:>=、field:< | 范围比较 |
path:subChildren | 按路径前缀过滤 |
column.key:jsonEq | JSON 子字段匹配，依赖数据库函数支持 |
动态过滤中普通字符串默认可能走模糊匹配，需要精确匹配时显式使用 :eq。时间单位、时区和边界应成对定义，例如前闭后开的统计窗口，不依赖客户端显示日期推断。
权限过滤
permConfig 可配置企业过滤、固定 preFilters、软删除列、角色过滤和 dataFilter Hook。Hook headers 是“参数名 → 运行时 HTTP header 名”的映射，而不是把任意用户输入作为可信 SQL。
客户端 filter 不能替代服务端权限条件。看板跨企业/项目时，验证更改 header、请求 code 或 filter 均不能扩大权限；公开 URL 也不能跳过查询认证。
验证
先在小数据集核对明细、总量、分组和批量结果，再检查空数据、时间边界、禁用数据源、分页排序、无权用户及恶意列名。统计表回填或迁移遵循数据库迁移，定时计算需可重复执行。
更新日志
2026/10/16 19:46
查看所有更新日志
b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于