（一）背景
PromQL 是 Prometheus 监控系统的查询语言，用于对时序数据进行查询、分析和聚合。PromQL 以表达式能力强大、简洁、逻辑清晰著称，GreptimeDB 作为时序数据库当然对其进行了（目前还是部分）支持。目前，GreptimeDB 在 Rust 中重新实现了 PromQL 的解析，并通过接口将能力开放。
通过 GreptimeDB 提供的接口，我们开发出各语言版本的 SDK 并且也在 GreptimeCloud 控制台（下面将它称为 Dashboard）中应用这些接口。本文将简单介绍它在 Dashboard 和 JS-SDK 中的使用。
GreptimeDB 实现了 Prometheus HTTP API 中的 range_query 接口，如下：
curl -X GET \
-H 'Authorization: Basic {{authorization if exists}}' \
-G \
--data-urlencode 'db=public' \
--data-urlencode 'query=avg(system_metrics{idc="idc_a"})' \
--data-urlencode 'start=1667446797' \
--data-urlencode 'end=1667446799' \
--data-urlencode 'step=1s' \
http://localhost:4000/v1/promql
（二）建表
在开始之前，我们需要下载 GreptimeDB，过程详情请参见 Dashboard｜GitHub[1] 。下载并运行 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_metrics
VALUES
('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 文档[2] 。
（四）Dashboard
下图是 Dashboard 对 range_query 的简单使用：
这里可以通过界面交互的方式，进行时间范围的选择以及 Step 值的设置，对应着 start, end, step 三个参数。可以简单选择一个最近时间，也可选取一个时间段；
参数 db 会被自动带上，值为当前 dashboard 所使用的 db 值，无需过多关注；
用户只需要关注 query 的写入即可；
需要注意的是，当指标的 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 类型。
4.1 greptime-js-sdk
如果想在自己的 Node.js 项目或者网站中使用 GreptimeDB，可以使用我们的 JS-SDK。
地址：https://github.com/GreptimeTeam/greptime-js-sdk
安装：
npm i greptime
简单使用：
// use in your project
import 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()
首先我们调用 greptime() 函数，将{ host, dbname, username, password } 作为参数。
你可以在 GreptimeCloud[3] 中创建一个 service 来获取以上参数（service 为云端数据库）。
或者在 GreptimeDB Download[4] 页面下载 Greptime 数据库并在本地运行（如上 Dashboard），这样则可以使用 { } 作为参数传递。
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 查询操作。
⚠️ 注意：与 Dashboard 中相似，当指标中含有非 Double 类型的 value 时，query() 中不能传入 PromQL 中的函数进行查询。 例如：
query('avg(your_metrics)') ❌
query('your_metrics') ✅
（五）总结
在时序数据领域，PromQL 语言是十分值得学习的一门语言，在对时序数据的查询和二次计算方面，它有着显著的优势，结合我们的 Dashboard 与 SDK，让用户感受查询的便捷，帮助用户探索时序数据的真正价值。
📢 关于PromQL 语法
我们曾推出两篇文章对其语法进行解析，希望可以给您带来一些帮助：
References:
[1] https://github.com/GreptimeTeam/dashboard
[2] https://docs.greptime.cn/user-guide/concepts/overview
[3] https://console.greptime.cloud/login
[4] https://www.greptime.com/download
点击下方链接🔗关注 GreptimeDB，了解更多技术干货👇
关于 Greptime
Greptime 格睿科技于 2022 年创立，目前正在完善和打造时序数据库GreptimeDB 和格睿云 GreptimeCloud 这两款产品。
GreptimeDB 是一款用 Rust 语言编写的时序数据库，具有分布式、开源、云原生、兼容性强等特点，帮助企业实时读写、处理和分析时序数据的同时，降低长期存储的成本。
GreptimeCloud 基于开源的 GreptimeDB，为用户提供全托管的 DBaaS，以及与可观测性、物联网等领域结合的应用产品。利用云提供软件和服务，可以达到快速的自助开通和交付，标准化的运维支持，和更好的资源弹性。GreptimeCloud 已正式公测，欢迎关注公众号或官网了解最新动态！
官网：https://greptime.com/
GitHub: https://github.com/GreptimeTeam/greptimedb
文档：https://docs.greptime.com/
Twitter: https://twitter.com/Greptime
Slack: https://greptime.com/slack
LinkedIn: https://www.linkedin.com/company/greptime/
往期精彩文章：
👇 点击下方阅读原文，立即体验 GreptimeDB！
