SurrealDB

此 Grafana 数据源插件可用于连接、查询和可视化 SurrealDB 中存储的信息。

要求

除了已安装和设置的 Grafana 服务（最小版本请参阅插件依赖项），要使用此插件，必须满足以下要求

• 一个已部署的 SurrealDB 实例，可通过安装此插件的 Grafana 服务网络访问

• 一个现有的 SurrealDB 命名空间

• 一个现有的 SurrealDB 数据库

• 一个可选的现有 SurrealDB Scope

• 一个现有的 SurrealDB 用户，拥有对命名空间、数据库以及可选 Scope 的访问权限——建议使用拥有 VIEWER 角色的 SurrealDB 用户，以便仅执行只读操作，不更改任何数据库状态以维护数据完整性

由于此插件用于查询一个或多个 SurrealDB 表的内容，因此默认情况下不要求存在相关表，因为插件可以在没有现有表的情况下安装，并且例如可以查询和可视化数据库信息。

安装

插件可以通过 Grafana 服务本身的用户界面或使用命令行工具进行安装，命令如下：

$ grafana cli plugins install fiskaly-surrealdb-datasource

如果 Grafana 服务是在容器化环境中设置的（例如通过 docker-compose）或在本地机器上启动的，则可以在启动期间通过设置以下环境变量为 Grafana 实例自动安装插件：

GF_INSTALL_PLUGINS="fiskaly-surrealdb-datasource"

配置

按照数据源管理文档并在添加新数据源连接页面中选择此插件，此插件的配置需要设置以下参数：

• WebSocket 连接的位置，格式为 地址:端口（必填，默认值：localhost:8000）

• 要使用的命名空间（必填，默认值：default）

• 要使用的数据库（必填，默认值：default）

• 要使用的 Scope（可选）

• 与 SurrealDB 实例交互的用户的用户名（必填，默认值：root）

• 用于执行身份验证的提供的用户的密码（必填，默认值：root）

用法

插件定义了三种查询模式：Raw、Log 和 Metric。 对于所有模式，实际查询均以 SurrealQL 编写。 因此，Raw 模式以表格视图表示查询结果，作为首选的可视化类型。

Log 模式将首选可视化类型更改为基于日志的视图，并允许定义/设置日志 Time 和可选日志 Message 列信息。

对于基于时间序列值的可视化，插件提供了 Metric 模式，以图形视图表示查询结果作为首选可视化类型。 此模式允许进一步配置/设置实际的 Data 列以可视化时间序列。 此外，基于 Data 列，还可以选择对给定 Field 进行数据分组，以及在给定 Interval 中执行不同的 Rate 计算。

变量查询

此插件为仪表盘变量提供 raw 查询支持。 查询响应中第一列的值用于仪表盘中定义变量的值的结果集。

设计

插件由前端和后端两部分组成。前端使用 TypeScript 编写，提供两个主要组件：(1) ConfigEditor，用于设置和连接到 SurrealDB 实例；以及 (2) QueryEditor，用于编写 SurrealDB 查询语言（SurrealQL）查询、配置查询模式以及与数据源插件的后端部分交互。

后端使用 Golang 编写，通过 SurrealDB WebSocket 接口提供低级连接。 成功连接和 signin 操作后，所有从前端发送到后端的查询都通过 WebSocket 连接使用 custom query 操作直接执行。

由于 SurrealDB 和 Grafana 都支持变量，插件支持并执行以下变量解析步骤：(1) 在前端部分，所有 Grafana Scope 提供的变量都会被替换；(2) 在后端部分，定义了以下插件特定变量，并在查询发送到 SurrealDB 实例执行之前替换这些变量：

• 由当前查询编辑器上下文定义的 $interval
• 查询执行开始时获取的当前 UTC 时间戳 $now
• 当前查询编辑器上下文的开始时间 UTC 时间戳 $from
• 当前查询编辑器上下文的结束时间 UTC 时间戳 $to