YMatrix 文档

MatrixBench 基本功能

本文档单独并详细地介绍了 MatrixBench 的部分基本功能，包含以下内容：

多数据类型与特征
组合式查询语句

注意！
目前 mxbench 已开源，欢迎你的审阅与贡献，请点击此处阅读 README。

1 多数据类型与特征

1.1 支持

注意！
因时序场景的特殊性，mxbench 规定数据表第一列必须为时间戳列，第二列必须为设备标识列，从第三列开始才为可写入用户数据的指标列。目前多数据类型和特征功能仅支持指标列，即从第三列开始的列。

目前 mxbench 已能够支持信号表中采集多种不同类型的指标：除了 int4， int8，float4，float8 这四种之外，还支持 text 和 varchar 等类型。
int4，int8，float4，float8 这四种还可以指定取值范围等数据特征。
varchar 类型还提供了特殊的类型 plate_template、vin_template，以更好的适应车联网场景的需求。plate_template 类型用于生成车牌号类型特征的 varchar 列，如：粤BDM7709。 vin_template 用于生成车架号类型特征的 varchar 列，如：1G1JC124627237595。

1.2 限制

第 1 列必须为时间戳列，列名不限，类型必须是 timestamp 或 timestamptz。
第 2 列必须为设备编号/设备名列，列名不限，类型必须是 text，varchar，int8 中的其中一种。

1.3 用法

在 mxbench 中实现大量指标，多种数据类型，多个数据取值范围等的配置方式有以下两种。

1.3.1 通过 DDL 文件实现

DDL 文件中，创建表之后，通过为列添加注释：COMMENT ON COLUMN 来表达该列的用途。

CREATE EXTENSION IF NOT EXISTS matrixts;
ALTER EXTENSION matrixts UPDATE;
CREATE SCHEMA IF NOT EXISTS "public";
CREATE TABLE "public"."table1" (
    tsss timestamp
,   vinnn bigint
,   lltt varchar(32)
,   c_arb float8
,   exttt json
)
USING mars2 WITH ( compress_threshold='1000', chunk_size='32' )
DISTRIBUTED BY (vinnn)
PARTITION BY RANGE(tsss) (
        START ('2022-04-18 09:00:00')
        END ('2022-04-19 09:00:06')
        EVERY ('10800 second'),
        DEFAULT PARTITION default_prt
);

CREATE INDEX IF NOT EXISTS "idx_table1" ON "public"."table1"
USING mars2_btree(
        vinnn
      , tsss);

COMMENT ON COLUMN table1.lltt is '{"name": "plate_template"}';
COMMENT ON COLUMN table1.c_arb is '{"min": 3.5, "max": 5}';
COMMENT ON COLUMN table1.exttt is '{"is-ext": true, "columns-descriptions": [{"type": "float8", "count": 1, "comment": {"min": 3, "max": 4}},{"type": "float4", "count": 3, "comment": {"min": 2, "max": 3}}]}';

示例配置如上，COMMENT 全部为 JSON 格式字符串，说明：

前两列有内容限制，具体见上文 “1.2 限制” 部分。
除了前 2 列外，其他都被视为指标列。
lltt 列是 varchar 类型。示例中我们用 COMMENT 标出：name=license_template，则会为 lltt 生成车牌号类型的数据。
c_arb 列是 float8 类型，根据 COMMENT，会生成 3.5 ~ 5 范围的随机数据。
table1.exttt 列是 JSON 类型，其 COMMENT 为：is-ext=true，意为它被标注成了扩展指标列，其中可能包含多个简单指标。查看简单指标有两种方式：
- 如果未指定 columns-descriptions，则读取 Global 类别中的 total-metrics-count 和 metrics-type 两个参数。total-metrics-count 的配置需大于等于 简单指标列总数 + 3，即扩展列至少含 3 个指标，否则会产生报错信息。
- 如果指定了 columns-descriptions，且为合法 json array 字符串，则 Global 类别中的 total-metrics-count 和 metrics-type 两个参数会失效。你需要通过 columns-descriptions 参数了解指标数量。示例如下：
```
[
{"type": "float8", "count": 1, "comment": {"min":  3, "max": 4}},  
{"type": "float4", "count": 3, "comment": {"min":  2, "max": 3}}, 
]
```
  因此，这个扩展列中有 1 个 float8 类型的指标以及 3 个 float4 类型的指标。同时，也有取值范围的限制。

1.3.2 通过配置文件实现

在此部分，你可以复用上述的扩展列的 columns-description 语法，使 Global 模块下的 metrics-descriptions 接受一个字符串类型的参数。示例如下：

[global]
  table-name = "table1"
  metrics-descriptions =  """[
    {"type": "float8", "count": 1000, "comment": {"min": 3, "max": 4}},
    {"type": "float4", "count": 3, "comment": {"min": 2, "max": 3}}
    ]"""

此参数的描述意为除固定列（第一列、第二列）不计入指标计算外，表 table1 中还包含 1000 个 float8 类型的指标，3 个 float4 类型的指标，总指标 1003 个，共 1005 列，超过了数据表的列数量上限（1000 列）。
因此按照 YMatrix 逻辑，便会有 6 个指标被安排在 JSON 类型的扩展列中。这样就只有 997 个简单指标和 2 个固定列，以及 1 个扩展列（包含多个指标的列），刚好共计 1000 列，又重新回到数据表的支持范围之内。

注意！
你也可以不指定 --metrics-descriptions 参数，以 Global 类别中的 --total-metrics-count 和 --metrics-type 参数为替代使用。

2 组合式查询语句

直接输入定制化查询语句无法根据本次生成数据的特征来设置 SELECT、WHERE 语句中的某些数值，因此查询测试的效果有限。利用组合式查询语句则可以解决这一问题。

2.1 配置概览

    {
    // 该条查询语句的名称
    "name": "QUERY_NAME",
    // SELECT 后的语句
    "projections": {"use-raw-expression": true, "expression": "*"},
    // SELECT FROM 后的表达式
    "from": {"use-relation-identifier": true, "relation-identifier": "sub-relation-identifier"},
    // 设备标识列相关 WHERE 语句中的表达式
    "device-predicate": {"count": 2, "is-random": ture},
    // 时间戳列相关 WHERE 语句中的表达式
    "ts-predicate": {"start": "2022-05-05 01:04:10", "end": "2022-05-05 01:04:10"},
    // 用户指标相关 WHERE 语句中的表达式
    "metrics-predicate": {"use-raw-expression": true, "expression": "m1>=37.5"},
    // GROUP BY 语句相关表达式
    "group-by": {"use-raw-expression": true, "expression": "device_column_name,ts"},
    // ORDER BY 语句相关表达式
     "order-by": {"user-raw-expression": true, "": "s desc"},
     // LIMIT 语句相关表达式
     "limit": 3
    },

2.2 详解

"name"
该条查询语句的名称。会打印在查询语句的汇总报告中。
"projections"
不允许缺省。指 SELECT 后面的表达式，可以是对所有字段的查询 “*”，也可以是投影查询其中的部分字段。
接受一个 JSON 类型的配置。
使用 raw-expression：
```
{"use-raw-expression": true, "expression": "*"}
```

"from"
FROM 后面的表达式。
缺省为直接使用 Global 类别里面配置的 table-name，等价于：

{
"use-relation-identifier": true, 
"relation-identifier": "table-name-in-global-config",
}

直接使用数据表的名字：

{
"use-relation-identifier": true, 
"relation-identifier": "device_signal_mars2",
}

使用另一个数据表阐述：

{ 
"relation-statement":
 {
 "projections": {"use-raw-expression": true, "expression": "device_column_name,max(m1) as mp, min(m2), count(m1), avg(m3)"},
 "device-predicate": {"count": 17, "is-random": true},
 "ts-predicate": {"start": "2022-05-05 00:00:00", "end": "2022-05-06 00:00:00"},
 "group-by": {"use-raw-expression": true, "expression": "device_column_name"}
 }
}

"device-predicate"
有关设备号的 WHERE 语句中的表达式，接受一个 JSON 类型的配置。
缺省为没有关于设备号的相关 WHERE 语句中的表达式，即全设备。
随机选取 n（n 是正整数，处于设备数范围内）个设备：例如 n = 2，以下配置生成：WHERE <device_column_name> IN (<random_device_id1>, <random_device_id2>)。
```
{
"count": 2, 
"is-random": false
}
```
若 n = 1，则会解释为等值查询，以下配置生成：WHERE <device_column_name>=<random_device_id>。
```
{
"count": 1, 
"is-random": false
}
```
使用 raw-expression： "expression" 后的字符串直接出现在 WHERE 后。和其他 predicates 是 "AND" 的关系。
```
{
"use-raw-expression": true, 
"expression": "device_column_name IN (1234, 4321)"
}
```
"ts-predicate"
有关时间戳的 WHERE 语句中的表达式，接受一个 JSON 类型的配置。
缺省为没有关于设备号的 WHERE 语句中的表达式，即全设备。随机选取 1 个时间点（在生成数据的时间戳范围内）。
```
{
"is-random": true, 
"duration": 3600  
}
```
设置起止时间：假设时间戳字段名为 ts，则会生成 WHERE ts >= '2022-07-15 18:07:00' AND ts <= '2022-07-15 18:31:17' 的表达式。
```
{
"start": "2022-07-15 18:07:00", 
"end": "2022-07-15 18:31:17",
}
```
等值查询：WHERE ts = '2022-07-15 18:07:00'。
```
{
"start": "2022-07-15 18:07:00", 
"end": "2022-07-15 18:07:00",
}
```
开区间查询：WHERE ts >= '2022-07-15 18:07:00' AND ts < '2022-07-15 18:31:17'。
```
{
"start": "2022-07-15 18:07:00", 
"end": "2022-07-15 18:07:00",
"end-exclusive": true
}
```
为时间戳字段设置 alias：WHERE tttt >= '2022-07-15 18:07:00' AND tttt < '2022-07-15 18:31:17'。
```
{
"has-alias": true,
"alias": "tttt",
"start": "2022-07-15 18:07:00", 
"end": "2022-07-15 18:07:00",
"end-exclusive": true
}
```
使用 raw-expression："expression" 后的字符串直接出现在 WHERE 后。和其 predicates 是 "AND" 的关系。
```
{
"use-raw-expression": true, 
"expression": "ts='2022-07-16 10:31:17'"
}
```
"metrics-predicate"
有关指标过滤的 WHERE 语句中的表达式，接受一个 JSON 类型的配置。
缺省为不添加指标过滤。使用 raw-expression："expression" 后的字符串直接出现在 WHERE 后。和其他 predicates 是 "AND" 的关系。
```
{
"use-raw-expression": true, 
"expression": "m1>=37.5"
}
```
"group-by"
GROUP BY 语句，接受一个 JSON 类型的配置。
缺省为不添加 GROUP BY 语句。
使用 raw-expression：
```
{
"use-raw-expression": true, 
"expression": "device_column_name,ts"
}
```
"order-by"
ORDER BY 语句，接受一个 JSON 类型的配置。
缺省为不添加 ORDER BY 语句。
使用 raw-expression：
```
{
"user-raw-expression": true, 
"expression": "s desc"
}
```
"limit"
接受一个正整数。

注意！
MatrixBench 完整的命令行参数信息请见 MatrixBench 命令行参数；MatrixBench 进度信息与统计报告详解请见 MatrixBench 理解进度信息与统计报告。