用户指南系列 | 使用 Greptime 官方工具高效地进行 PromQL 查询

背景

PromQL 是 Prometheus 监控系统的查询语言，用于对时序数据进行查询、分析和聚合。PromQL 以表达式能力强大、简洁、逻辑清晰著称，GreptimeDB 作为时序数据库当然对其进行了（目前还是部分）支持。目前，GreptimeDB 在 Rust 中重新实现了 PromQL 的解析，并通过接口将能力开放。

通过 GreptimeDB 提供的接口，我们开发出各语言版本的 SDK 并且也在 GreptimeCloud 控制台（下面将它称为 Dashboard）中应用这些接口。下面将简单介绍它在 Dashboard 和 JS-SDK 中的使用。

GreptimeDB 实现了 Prometheus HTTP API 中的 range_query 接口，如下：

建表

在开始之前，我们需要下载 GreptimeDB，过程详情请参见 Dashboard｜Github。下载并运行 GreptimeDB 后，可在 http://localhost:4000/dashboard/playground 页面的指引下完成建表。

你也可以选择尝试一下我们的云服务，目前处于限免预览期：https://console.greptime.cloud/

我们通过 SQL 进行建表，下面是一个简单的参考：

CREATE TABLE IF NOT EXISTS cpu_metrics (    hostname STRING,    environment STRING,    usage_user DOUBLE,    usage_system DOUBLE,    usage_idle DOUBLE,    ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP TIME INDEX,    PRIMARY KEY(hostname, environment));

这里的 PRIMARY KEY 对应表模型中 标签列（Tag Columns） 的概念，后面将详细说明。

同样的，我们可以通过 SQL 插入几条数据：

INSERT INTO cpu_metricsVALUES    ('host_0','test',32,58,36,1680307200),    ('host_1','test',29,65,20,1680307200),    ('host_1','staging',12,32,50,1680307200),    ('host_2','staging',67,15,42,1680307200);

表模型

GreptimeDB 的表模型基于关系型数据库，同时考虑到了时序数据的特点，可简单理解为增加了 Timestamp (ts) 列，它用于指定 ts 列作为该表的时间索引列。

GreptimeDB 中的所有数据都被组织成表，它由四个部分组成：表名 Table Name（指标）、标签列（Tag Columns）、度量列（Field Columns）和时间索引列（Timestamp）。

这里有一点需要注意，GreptimeDB 将全部的标签列（Tag Columns）作为 Primary Key 使用。

表模型详情可参见 GreptimeDB 文档。

Dashboard

下图是 Dashboard 对 range_query 的简单使用：

1. 这里可以通过界面交互的方式，进行时间范围的选择以及 Step 值的设置，对应着 start, end, step 三个参数。可以简单选择一个最近时间，也可选取一个时间段。

2. 参数 db 会被自动带上，值为当前 dashboard 所使用的 db 值，无需过多关注。

3. 用户只需要关注 query 的写入即可。

4. 需要注意的是，当指标的 value 值中出现非 Double 类型的时候，PromQL 的计算函数将不可用，例如：（Tips: 第一行为 Timestamp，二三行为 Primary Key，后面几行则为 Field Columns）：

此时的 up 是一个 String 类型的 value，当我们对 bilibili_video_list_info_new 这个指标进行运算的时候便会获得一个报错，如下图所示：

为什么指标中会出现 String 类型的 value 呢？其原因在于，在 GreptimeDB 中，我们需要使用 SQL 语句进行建表操作，此时可以允许非 Double 类型的 value 存在（此处表的概念可近似理解为指标）。

如果希望在 GreptimeDB 中更好地使用 PromQL 语句进行查询，建议不要将 value 指定为其他非 Double 类型。

greptime-js-sdk

如果想在自己的 Node.js 项目或者网站中使用 GreptimeDB，可以使用我们的 JS-SDK。

地址： https://github.com/GreptimeTeam/greptime-js-sdk

安装：

npm i greptime

简单使用：

// use in your projectimport greptime from 'greptime'
const { sql, promql} = greptime({    host: 'your_host',    dbname: 'your_dbname',    username: 'your_username',    password: 'your_password'})
// if you download the greptime and run it locally, you can use {} as the parameter ⬇️const { sql, promql} = greptime({})
// to use promql ⬇️const resOfDuration = await promql.qurey('your_metrics')    .duration('5m')    .step('1s')    .run()
// or select time bucket ⬇️const res = await promql.qurey('your_metrics')    .start('start_time')    .end('end_time')    .step('1s')    .run()

1. 首先我们调用 greptime() 函数，将{ host, dbname, username, password } 作为参数。a. 你可以在 GreptimeCloud 中创建一个 service 来获取以上参数（service 为云端数据库）。b. 或者在 GreptimeDB Download 页面下载 Greptime 数据库并在本地运行（如上 Dashboard），这样则可以使用 { } 作为参数传递。

2. greptime() 函数返回 SQL 与 PromQL 两个实例，SQL 实例中包括建表与增删查等操作，这里便不展开讨论。我们一起来看看 PromQL 实例，PromQL 实现了链式调用，更方便开发者使用与理解，下面是 PromQL 相关函数说明：

函数说明

• query: 必须，需传入一个指标名或 PromQL 中的函数 sum(), avg() 等，类型为 String。例如：query('avg(your_metrics)')。

• start，end：可选，且与下面的 duration 二选一。起始时间与结束时间，需成对出现，需传入一个时间戳，类型为 number。

• duration：可选，需传入一个时间段，类型为 String，例如：duration('10m')，不传入参数则默认为'5m'，意思为选取 5 分钟前到当前时间这个时间段。若不使用 duration 或（start, end) 函数，则默认 duration('5m')。

• step：可选，传入一个查询步长，类型为 String，例如：step('10s') ，若不使用 step 函数则默认查询步长为'1s'。

• run：必须，无参数，用于执行 PromQL 查询操作。

3. ⚠️注意：与 Dashboard 中相似，当指标中含有非 Double 类型的 value 时，query() 中不能传入 PromQL 中的函数进行查询。例如：query('avg(your_metrics)') ❌query('your_metrics') ✅

总结

在时序数据领域，PromQL 语言是十分值得学习的一门语言，在对时序数据的查询和二次计算方面，它有着显著的优势，结合我们的 Dashboard 与 SDK，让用户感受查询的便捷，帮助用户探索时序数据的真正价值。

为了让更多不同语言的开发者更方便地使用 GreptimeDB，我们正在开发不同语言的 SDK 以及可视化工具。同时我们也会在后续版本中不断提高 PromQL 的兼容性、持续开发并优化我们的工具包，希望可以给用户带来真正的价值，欢迎加入我们的 Slack 社区，为我们提供真实的用户反馈。

PromQL 语法

关于 PromQL，我们曾在公众号 GreptimeDB 推出两篇文章对其语法进行解析，希望可以给您带来一些帮助：

1. 找 ChatGPT 写 SQL? 不如试试 PromQL，三行解决复杂时序场景查询

2. PromQL 语法进阶解析 | 基于 Rust 的解析库 promql-parser v0.1 现已开源 https://greptime.com/