国产化替代
文档
博客
新闻
关于我们
下载

YMatrix 文档

版本发布历史
系统需求

关于 YMatrix

快速上手

标准集群部署

数据建模

连接到数据库

数据写入

数据迁移

数据查询

运维监控

性能调优

故障诊断

参考指南

SQL 参考

常见问题（FAQ）

场景应用

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 支持在不停止运行的情况下，修改并行加载的相关参数：--interval、--stream-prepared。 --interval 代表的是完成从 mxgate 写入数据到数据库表的每个写入连接的工作时间，--stream-prepared 代表的是活跃的写入连接的数量。在 mxgate 逻辑中，同一个数据库表同一时间只有一个写入连接执行写入数据的任务，因此每个数据库表都需要有多个连接在不同时间区间去不停地执行它自身的写入任务，从而保证高速率、高效率地写入数据。在此过程中，你可以通过 --interval 这个参数来实现对于每个写入连接的工作时间的调整，从而改善数据的写入速率，针对性提高加载性能。具体用法示例如下：

  • 设置每个表的写入连接数量为 3
    $ mxgate set --stream-prepared-cli 3
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.1.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
  • 获取每个表活跃的写入连接数量
    $ mxgate get --stream-prepared-get
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.1.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.vehicle_basic_data_mars3 stream-prepared = 3
  • 设置所有表的写入连接的时间间隔为 200ms
    $ mxgate set --job-interval 200
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.1.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
  • 获取所有表的写入连接当前的时间间隔
    $ mxgate get --job-interval-get
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.1.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************

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


4 不停机更新表结构

在数据加载的过程中，你可能会突然发现在变化的时序数据源驱动下，之前设定的表结构对于现在场景不再适用了，然后就有了修改表结构的需求，这是 mxgate 可以满足的。此节将会说明，mxgate 如何在不停机的情况下，执行暂停数据写入，重载修改后的数据库表元信息，恢复数据写入等系列操作。具体步骤如下：

  • 首先，使用命令 mxgate pause -X 中断所有表的写入连接，为修改数据库表结构作准备。其中 -X 参数是必要的，它会帮助中断 mxgate 和数据库之间的连接。如果不中断连接，是无法对数据库表进行修改的。除了 -X 之外，运用 -S 参数可以令 pause 命会同步等待所有连接中断完成再返回。
    $ mxgate pause -X
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.1.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
begin to pause all jobs，please wait...
  • 其次，中断对应表的所有写入连接之后，即可以对数据库对应的数据库表执行修改结构的操作，如增加若干列，删除若干列，删除已有表，重新创建“同名”的新表。

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

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

    $ mxgate resume -R
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.1.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 的对应的表的所有写入连接必须先被暂停，否则会出现如下报错：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 操作如下：

  1. 清空一个表或者一组表
    =# TRUNCATE TABLE <tablename>;
  2. 为某个表增加列、删除列、修改列类型
    =# ALTER TABLE <tablename> ADD COLUMN <columnname> <columndatatype>;
=# ALTER TABLE <tablename> DROP COLUMN <columnname>;
=# ALTER TABLE <tablename> ALTER COLUMN <columnname> TYPE <columndatatype>;
  3. 为某个表更改表名
    =# ALTER TABLE <tablename> RENAME TO <new tablename>;
  4. 先删除表再重新创建它
    =# DROP TABLE <tablename>;
=# CREATE TABLE <tablename(column datatype)>;
  5. 针对分区表的以上四种 DDL 操作


9 mxgate 自动调节连接数

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

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

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

  • 在启动 mxgate 时传入 --auto-tune 参数
  • 在 mxgate 配置文件中设置
  • 通过 mxgate set 命令动态开关
    • 打开：mxgate set --auto-tune
    • 关闭：mxgate set --auto-tune=false

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

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


10 mxgate 百分比量化写入负载

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

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

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

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

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

例如：

$ mxgate set --high-water-mark 20 --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.1.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.1.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.1.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 的自动调整连接数功能，并且设置了对应的高水位阈值，那么在该 Job 的载入压力值没有超过设定的高水位阈值之前，连接数是不会自动增加的，即使 mxgate 尝试通过自动调整功能增加也无济于事。

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

[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.1.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 0.00%