MatrixGate 主要功能

本文档介绍了 MatrixGate 的主要功能。

注意！
编程语言接入 MatrixGate 请见数据写入 - 编程语言接入 MatrixGate。

1 MatrixGate 加载特殊类型

1.1 MatrixGate 加载 CSV 文件示例

在 demo 数据库中创建表 csvtable。

demo=# CREATE TABLE csvtable (
       time TIMESTAMP WITH TIME ZONE,
       tagid INT,
       c1 INT,
       c2 INT,
       c3 INT
       )
       USING MARS3
       DISTRIBUTED BY (tagid)
       ORDER BY (time,tagid);

编辑数据加载文件 data.csv，内容如下：

1603777821|1|101|201|301
1603777822|2|102|202|302
1603777823|3|103|203|303

启动 mxgate，指定 --source 参数为 stdin，目标表为已经存在的 csvtable，加载并行度为 2。示例中主机为 mdw。

[mxadmin@mdw ~]$ mxgate \
--source stdin \
--db-database demo \
--db-master-host 127.0.0.1 \
--db-master-port 5432 \
--db-user mxadmin \
--time-format unix-second \
--delimiter "|" \
--target csvtable \
--parallel 2 < data.csv

连接数据库查询数据是否加载成功。

demo=# SELECT * FROM csvtable ;
          time          | tagid | c1  | c2  | c3
------------------------+-------+-----+-----+-----
 2020-10-27 05:50:23+08 |     3 | 103 | 203 | 303
 2020-10-27 05:50:22+08 |     2 | 102 | 202 | 302
 2020-10-27 05:50:21+08 |     1 | 101 | 201 | 301

(3 rows)

1.2 MatrixGate 加载 JSON 字段示例

1.2.1 JSON

创建表。

demo=# CREATE TABLE json_test(
     id int,
     j json
     )
     USING MARS3
     ORDER BY (id);

创建数据文件。 ~/json.csv
```
1|"{""a"":10, ""b"":""xyz""}"
```

加载这里使用 stdin 模式为例，其他模式都一样。关键在 --format csv。

[mxadmin@mdw ~]$ mxgate \
--source stdin \
--db-database postgres \
--db-master-host 127.0.0.1 \
--db-master-port 7000 \
--db-user mxadmin \
--time-format raw \
--format csv \
--delimiter "|" \
--target json_test < ~/json.csv

查看加载数据。

demo=# SELECT * FROM json_test;
id |           j
----+-----------------------
1 | {"a":10, "b":"xyz"}
(1 row)

1.2.2 JSON 数组

创建表。

demo=# CREATE TABLE json_array_test(
     id int,
     j json
     )
     USING MARS3
     ORDER BY (id);

创建数据文件 ~/json_array.csv。

1|"{""{\""a\"":10, \""b\"":\""xyz\""}"",""{\""c\"": 10}""}"

加载 mxgate。

[mxadmin@mdw ~]$ mxgate \
--source stdin \
--db-database postgres \
--db-master-host 127.0.0.1 \
--db-master-port 7000 \
--db-user mxadmin \
--time-format raw \
--format csv \
--delimiter "|" \
--target json_array_test < ~/json_array.csv

验证。

demo=# SELECT * FROM json_array_test ;
id |                      j
----+---------------------------------------------
1 | {"{\"a\":10, \"b\":\"xyz\"}","{\"c\": 10}"}
(1 row)

注意！
因为 JSON 列包含引号等特殊字符，所以 mxgate 的 --format 参数必须为 CSV。

2 观测 mxgate 运行指标

watch 是 mxgate 的一个子命令，用一系列指标描述 mxgate daemon 运行情况。 watch 有两种模式：

实时观测模式，用类似 sar 的格式每隔 3 秒将 gate 的各项指标打印在控制台。
历史观测模式，可以指定任意时间段，任意时间周期（例如昨天的每个小时，上个月的每一天，去年的每一个月）统计导入速度。

2.1 实时观测

[mxadmin@mdw ~]$ mxgate watch

会每三秒收集 mxgate 的运行指标，输出结果如下

                 Time          WCount          ICount        WSpeed/s        ISpeed/s  WBandWidth MB/S     BlocakItems
  2022-04-28 15:20:58        14478858        14527011         2598081         2627887            2395               0
  2022-04-28 15:21:01        22231035        22633254         2584059         2702081            2222               0
  2022-04-28 15:21:04        30494310        30500874         2754425         2622540            3551               0
  2022-04-28 15:21:07        38004210        38032956         2503300         2510694            2862               0
  2022-04-28 15:21:10        46188696        46298223         2728162         2755089            2227               0
  ...

可通过 --info 参数来获取上述各个指标的说明

[mxadmin@mdw ~]$ mxgate watch --info

默认情况下只会输出速度指标，可通过 --watch-latency 参数来观测时间指标用于分析问题

[mxadmin@mdw ~]$ mxgate watch --watch-latency

2.2 历史数据观测

[mxadmin@mdw ~]$ mxgate watch --history

会计算截至当前时间为止，24小时内的每小时的平均速度，输出结果如下

                TIME RANGE                | SPEED/S  | BANDWIDTH MB/S  | BLOCK ITEMS
  2022-04-28 16:00:00-2022-04-28 17:00:00 |  2208010 |         1254.48 |           0
  2022-04-28 17:00:00-2022-04-28 18:00:00 |  1157920 |         1327.00 |           0
  2022-04-28 18:00:00-2022-04-28 19:00:00 |  2228666 |         2162.32 |           0
  2022-04-28 19:00:00-2022-04-28 20:00:00 |  1371092 |         2881.30 |           0
  2022-04-28 20:00:00-2022-04-28 21:00:00 |  1575320 |         2608.20 |           0

其中 SPEED/S,BANDWIDTH MB/S 代表导入的条目速度与导入带宽（MB/s 为单位）, BLOCK ITEMS 代表阻塞在 mxgate 的数据量，当数据库消费速度跟不上数据源（http，kafka 等）生产速度时，这个值会上升

可以添加 --watch-start，--watch-end，--watch-duration 参数来控制观测历史数据的时间区间与周期例如

[mxadmin@mdw ~]$ mxgate watch --history --watch-start '2022-03-27 00:00:00' --watch-end '2022-04-27 00:00:00' --watch-duration '168h'

可以获得从 3 月 27 日到 4 月 27 日每周(每 168h)平均导入速度其中 --watch-duration 支持 h m s 三种单位

3 不停机更新并行写入

mxgate 支持在不停止运行的情况下，修改并行加载参数 --stream-prepared、--interval：

--stream-prepared 代表的是 mxgate 向 YMatrix 每张表写入数据时活跃 slot 的数量，默认所有表的 slot 数量相同，可手动针对单个任务（Job）调节（每张表只能有一个任务）。
- 增加 --stream-prepared 值，往往意味着提高数据写入的并发度，进而提升性能，同时也会占用更多的内存资源。
- 减少 --stream-prepared 值，则可以减少数据节点（Segment）内存资源的占用，但性能也会随之降低。
--interval 代表的是每个活跃 slot 的工作间隔时间，即每个 slot 等待 --interval（以毫秒为单位，ms）的时间后，将该时间段内 mxgate 接收到的数据发送到 YMatrix。
- 增加 --interval 的值，意味着每个 slot 每次写入数据的延迟会增加，每次写入的数据量会加大（前提是有数据源源不断地流入 mxgate）。
- 减少 --interval 的值，则延迟减少，数据量也降低。

综上，在生产实践中，上述两个参数需要配合不同的存储引擎和用户对数据写入实时性的要求进行合理的调整。

具体用法示例如下：

设置每个表的 slot 数量为 3
```
$ mxgate set --stream-prepared-cli 3
```
获取每个表活跃 slot 数量
```
$ mxgate get --stream-prepared-get
```
设置所有表 slot 的时间间隔为 200ms
```
$ mxgate set --job-interval 200
```
获取所有表的 slot 当前的时间间隔
```
$ mxgate get --job-interval-get
```

注意！
对于以上参数，如果你想设置或获取某个特定表的 slot 数量或工作时间，那么在上述命令后加 --job <名称> 即可。每个任务对应一张数据库表，job 参数结构由模式名与表名组成，意思就是如果你的特定表叫做 test_table，模式名为 public，那么完成指定就需要在已有命令后加上 --job public.test_table 就是对的。

4 不停机更新表结构

在数据加载中，由于时序数据源越来越丰富，之前设定的表结构对于现在场景可能不再适用，因而就有了修改表结构的需求。此节将会说明，mxgate 如何在不停机的情况下，暂停数据写入、重载表元信息以及恢复数据写入。具体步骤如下：

首先，使用命令 mxgate pause -X 中断所有表的 slot，为修改数据库表结构作准备。其中 -X 参数是必要的，它会帮助中断 mxgate 和数据库之间的 slot。如果不中断 slot，是无法对数据库表进行修改的。除了 -X 之外，运用 -S 参数可以令 pause 命会同步等待所有 slot 中断完成再返回。

$ mxgate pause -X
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
begin to pause all jobs，please wait...

其次，中断对应表的所有 slot 之后，即可以对数据库对应的数据库表执行修改结构的操作，如增加若干列，删除若干列，删除已有表，重新创建“同名”的新表。

注意！ 重建的表结构可以不同，但“表名”必须保持一致。

最后，使用命令 mxgate resume -R 恢复所有表的 slot，重载数据表的元信息。其中 -R 参数是必需的，resume 与 -R 将组合完成重载操作。

$ mxgate resume -R
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.2.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
begin to reload all jobs，please wait...

特别地，多个 mxgate 进程同时运行的情况，需要 -p 参数表示对应 mxgate 进程的进程号，上述所有命令都是同理，例如：
```
$ mxgate get --job-interval-get -p 70199 --job
```

注意！
执行重载命令的前提是 mxgate 的对应的表的所有 slot 必须先被暂停，否则会出现如下报错：jobs are not paused，please pause them first

5 UPSERT 功能支持

YMatrix 从 v4.2.0 实现了 MatrixGate 的 UPSERT 功能。详见数据分批合并场景（UPSERT）。

6 单表迁移

YMatrix 从 v4.3.0 实现了 MatrixGate 的单表迁移功能。详见单表迁移。

注意！
YMatrix 不仅支持单表迁移，也支持全库迁移（v4.7.0 及以上）。详见全库迁移。

7 不停机更新日志级别

我们有时需要打开 mxgate 的 debug 日志来观测一些关键信息，但是打开或者关闭 debug 日志都需要重启 mxgate，并不利于定位问题。因此， YMatrix 提供了动态变更 mxgate 日志级别的功能:

在 gate 运行的时候，使用命令 mxgate set --log-level VERBOSE 开启信息比较完整的 VERBOSE 级别的日志或者 mxgate set --log-level DEBUG 开启信息最完整的 DEBUG 级别的日志，等不需要在观察 debug 日志的时候，可以通过 mxgate set --log-level INFO,恢复日志级别为 INFO。

8 mxgate 事件触发

有时我们需要在 mxgate 对某表执行插入操作的过程中，对此表进行一些 DDL 的修改，此功能可以使 mxgate 在收到 DDL 修改指令后对正在发生的插入操作进行“退避”，从而使得 DDL 语句在第一时间可以得到执行。

支持的 DDL 操作如下：

清空一个表或者一组表
```
=# TRUNCATE TABLE <tablename>;
```

为某个表增加列、删除列、修改列类型

=# ALTER TABLE <tablename> ADD COLUMN <columnname> <columndatatype>;
=# ALTER TABLE <tablename> DROP COLUMN <columnname>;
=# ALTER TABLE <tablename> ALTER COLUMN <columnname> TYPE <columndatatype>;

为某个表更改表名

=# ALTER TABLE <tablename> RENAME TO <new tablename>;

先删除表再重新创建它

=# DROP TABLE <tablename>;
=# CREATE TABLE <tablename(column datatype)>;

针对分区表的以上四种 DDL 操作

9 mxgate 自动调节 slot 数

通常，我们可以通过手动调节 stream-prepared 参数（并行执行的 slot 会话数量）来适配不同写入任务的负载（即将写入的数据量）。但在某些业务场景中，写入任务的负载存在持续的动态变化，这种变化无法通过人工的方式来调整。

因此，MatrixGate 设计了一种自动机制：通过开启 --auto-tune 参数来完成对写入负载的自动适配。

此参数可通过以下几种方式启用：

注意！
开启此功能可以实时保证最高效的写入性能，但是对于会话 slot 资源的利用，不一定为最优。

注意！
如果你设置了开启自动调整 slot 数，同时设置了高水位阈值，那么只有在写入负载超过阈值的情况下自动调整 slot 数功能才会生效。

10 mxgate 百分比量化写入负载

mxgate 支持对源端数据的写入负载进行量化（百分比 0 ～ 100%），在 mxgate 执行数据写入的过程中，通过如下命令即可获取到对应任务（Job）的写入负载：

$ mxgate get --source-pressure
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 source-pressure = 27.26%

如果有多个 Job，则可以通过 Job 的名称来获取对应的写入负载，或者一次性获取多个 Job 的写入负载：

$ mxgate get --source-pressure --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 source-pressure = 15.73%

$ mxgate get --source-pressure
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 source-pressure = 35.84%
public.t1 source-pressure = 0%

完成百分比负载量化后，你可以使用此指标设置一个相应的高水位阈值。如果源端数据写入负载超过了设定的阈值，则对应的数字会展示为红色。此时可以手动调整 slot 数以降低写入压力，当然也可以使用 mxgate 自动调节 slot 数功能。

阈值需通过以下命令设置：

$ mxgate set --high-water-mark <highwatermark> --job <jobname>

例如：

$ mxgate set --high-water-mark 20 --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 20.00%

通过如下命令获取对应 Job 的高水位阈值：

$ mxgate get --high-water-mark-get --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 20.00%

$ mxgate get --high-water-mark-get
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t1 high-water-mark = 0.00%
public.t2 high-water-mark = 20.00%

注意！
如果超过了设定的阈值，压力值会变红。

如果你开启了 mxgate 的自动调整 slot 数功能，并且设置了对应的高水位阈值，那么在该 Job 的载入压力值没有超过设定的高水位阈值之前，slot 数是不会自动增加的，即使 mxgate 尝试通过自动调整功能增加也无济于事。

例如：我们设定了高水位阈值为 75%。在载入压力为 35% 的时候，虽然 mxgate 经过判断认为应该增加 slot 数，但是因为没有达到高水位阈值设置的 75%，此时 slot 数并不会增加，而是会显示如下报错：

[WARN]:-[SlotsLauncher] Sources pressure = 35.21 of job(public.t2) is lower than the high water mark(75), the slot increase is not allowed

注意！
示例值仅为参考，请根据实际业务需求和当前数据写入速度来设置相应高水位阈值。

如果想解除高水位阈值的限制，则可以使用如下命令：

$ mxgate set --disable-high-water-mark=true --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 0.00%