[Feature request] Grafana plugin: no table model support and poor tree model UX — needs overhaul | Grafana

[CritasWang]

Search before asking

• I searched in the issues and found nothing similar.

Motivation

Background

The current IoTDB Grafana data source plugin (in iotdb-extras/connectors/grafana-plugin) only supports the tree model. Since IoTDB 2.0 introduced the table model, the plugin has fallen behind. Even for tree-model users, the UX is rough compared to other Grafana data source plugins.

---

Problem 1: No table model support

The plugin has zero awareness of the table model:

• Frontend: QueryEditor offers two modes — SQL: Full Customized (manual SQL) and SQL: Drop-down List (hierarchical tree path picker). Both are hardwired to the root. path system. There is no database/table/column browser for the table model.
• Backend: The Go backend calls three IoTDB REST endpoints — /grafana/v1/query/expression, /grafana/v1/variable, /grafana/v1/node. The getNodes handler (used by the Drop-down List picker) traverses root.-prefixed hierarchical paths, which has no equivalent in the table model's flat two-dimensional structure.
• Result: Table-model users cannot visualize data in Grafana through the plugin and must resort to workarounds like the Infinity data source with raw SQL.

Problem 2: Poor tree-model UX

2.1 "SQL: Full Customized" mode is too raw

It's essentially four text boxes (SELECT / FROM / WHERE / CONTROL). Users must manually type IoTDB-specific SQL syntax. For Grafana operators unfamiliar with IoTDB SQL, the barrier is high and the error rate is high.

2.2 Drop-down List path picker is slow and unintuitive

The TIME-SERIES picker expands each level via a separate HTTP call to /grafana/v1/node. With a large number of time series, every level expansion stalls on a network round-trip, and the nested-dropdown UX makes it hard to locate a target series quickly.

2.3 Missing modern Query Builder experience

Compared to other data source plugins (Prometheus, InfluxDB, MySQL, etc.), the IoTDB plugin lacks:

• Visual metric/field/tag pickers
• In-editor data preview
• Autocomplete and syntax hints
• Real-time query validation
• Toggle between Query Builder and raw SQL editor (the Grafana-recommended dual-mode pattern)

2.4 Go backend tech debt

• Uses deprecated ioutil.ReadAll
• Error handling is coarse (multiple ignored error returns)
• The REST API returns values as []interface{} requiring type-guessing (recoverType), making the data contract fragile

2.5 Stale aggregate function list

The dropdown in QueryEditor lists SUM, COUNT, AVG, EXTREME, MAX_VALUE, MIN_VALUE, FIRST_VALUE, LAST_VALUE, MAX_TIME, MIN_TIME, which may not cover all built-in aggregate functions available in newer IoTDB versions.

2.6 Limited template variable support

Variable values rely on executing SQL via /grafana/v1/variable — they must be queryable from IoTDB. Static variable types like constants or custom lists require workarounds.

---

What we'd like to see

1. Table model support

   • A tree/table model switch in QueryEditor
   • Database → Table → Column browser for the table model
   • Standard SQL queries against table-model data (SELECT ... FROM database.table WHERE ...)
   • Corresponding REST API additions (or reuse IoTDB's existing SQL query interface)

2. Tree model UX overhaul

   • A visual Query Builder to lower the entry barrier
   • Keep a raw SQL editor as the advanced/power-user mode
   • Optimize path picker performance (caching, batch loading, search/filter)
   • Add autocomplete and syntax hints
   • Sync the aggregate function list with the latest IoTDB release

3. Codebase modernization

   • Upgrade to the latest Grafana plugin SDK
   • Clean up Go backend tech debt
   • Improve error handling and logging

---

Related repos

Plugin code lives at apache/iotdb-extras under connectors/grafana-plugin/. The three REST endpoints it calls (/grafana/v1/*) live in this repository's REST module.

---

---

背景

当前 IoTDB Grafana 数据源插件（位于 iotdb-extras/connectors/grafana-plugin）仅支持树模型。IoTDB 2.0 引入表模型后，插件已明显滞后。即便是树模型用户，与其他 Grafana 数据源插件相比，使用体验也较差。

---

问题 1：完全不支持表模型

插件对表模型完全无感知：

• 前端：QueryEditor 仅提供「SQL: Full Customized」（手动拼 SQL）和「SQL: Drop-down List」（树形路径选择器）两种模式，均硬编码为 root. 路径体系，没有数据库/表/列的浏览器。
• 后端：Go 后端调用 IoTDB 的三个 REST 端点 —— /grafana/v1/query/expression、/grafana/v1/variable、/grafana/v1/node。getNodes 处理器（供下拉选择器使用）遍历 root. 前缀的层级路径，表模型的平面二维结构没有对等物。
• 结果：表模型用户无法通过插件在 Grafana 中可视化数据，只能借助 Infinity data source 等变通方案直接写 SQL，体验割裂。

问题 2：树模型使用体验较差

2.1 「SQL: Full Customized」模式过于原始

本质是四个文本框（SELECT / FROM / WHERE / CONTROL），用户需手动输入 IoTDB 特有 SQL 语法。对不熟悉 IoTDB SQL 的 Grafana 运维人员来说门槛高、出错率高。

2.2 下拉列表选择路径慢且不直观

TIME-SERIES 选择器每展开一级需调用一次 /grafana/v1/node。序列数量大时，每次展开都要等待网络往返，且嵌套下拉的交互难以快速定位目标序列。

2.3 缺乏现代化的 Query Builder 体验

相比其他数据源插件（Prometheus、InfluxDB、MySQL 等），IoTDB 插件缺少：

• 可视化的 metric/field/tag 选择器
• 编辑器内数据预览
• 自动补全与语法提示
• 实时查询校验
• Query Builder 与原始 SQL 编辑器的双模式切换（Grafana 推荐模式）

2.4 Go 后端技术债务

• 使用了已废弃的 ioutil.ReadAll
• 错误处理粗糙（多处忽略 error 返回值）
• REST API 返回的 values 使用 []interface{} 靠类型猜测（recoverType），数据契约不严格

2.5 聚合函数列表陈旧

QueryEditor 中的聚合函数下拉列表为 SUM, COUNT, AVG, EXTREME, MAX_VALUE, MIN_VALUE, FIRST_VALUE, LAST_VALUE, MAX_TIME, MIN_TIME，可能未覆盖新版 IoTDB 的全部内置聚合函数。

2.6 模板变量支持有限

变量值依赖 /grafana/v1/variable 执行 SQL 查询获取——值必须能从 IoTDB 查到。常量或自定义列表等静态变量类型需要变通方案。

---

期望改进

1. 新增表模型支持

   • QueryEditor 增加「树模型」/「表模型」模式切换
   • 表模型模式下提供数据库 → 表 → 列的浏览器
   • 支持标准 SQL 查询表模型数据
   • 后端新增或复用对应的 REST API

2. 优化树模型使用体验

   • 提供可视化 Query Builder，降低上手门槛
   • 保留原始 SQL 编辑器作为高级模式
   • 优化路径选择器性能（缓存、批量加载、搜索过滤）
   • 添加自动补全和语法提示
   • 同步聚合函数列表

3. 代码现代化

   • 升级 Grafana plugin SDK
   • 清理 Go 后端技术债务
   • 完善错误处理与日志

---

相关仓库

插件代码位于 apache/iotdb-extras 的 connectors/grafana-plugin/ 目录。插件调用的三个 REST 端点（/grafana/v1/*）位于本仓库的 REST 模块。

Solution

No response

Alternatives

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[PDGGK]

I'd like to take this on.

It spans the frontend, the Go backend, and the REST layer, so I'd approach it incrementally:

1. Table model support first — a tree/table switch in QueryEditor, a database → table → column browser, and standard SQL against table-model data, reusing IoTDB's existing SQL query interface where possible rather than adding new REST endpoints.
2. Tree-model UX next — a visual Query Builder with the raw SQL editor kept as the advanced mode, path-picker performance (caching / batch loading / search), and syncing the aggregate function list.
3. Modernization alongside — Grafana plugin SDK upgrade and the Go backend cleanup (ioutil, error handling, the values contract).

I'd start with a focused, independently-reviewable PR for table-model querying, then iterate. Happy to adjust the sequencing if you'd prefer a different starting point.

[HTHou]

Can grafana plugin use https://github.com/apache/iotdb-client-go instead of REST api to connect the IoTDB? I just think the proformance of the native client is more powerful. @CritasWang

[CritasWang]

@PDGGK try use https://github.com/apache/iotdb-client-go?