400-800-0824
info@ymatrix.cn
400-800-0824
info@ymatrix.cn
400-800-0824
info@ymatrix.cn
400-800-0824
info@ymatrix.cn
400-800-0824
info@ymatrix.cn
YMatrix 文档
关于 YMatrix
标准集群部署
数据写入
SQL 参考
本文档介绍了 MatrixGate 的主要功能。
注意!
编程语言接入 MatrixGate 请见数据写入 - 编程语言接入 MatrixGate。
在 demo 数据库中创建表 csvtable。
demo=# CREATE TABLE csvtable (time TIMESTAMP WITH TIME ZONE, tagid INT, c1 INT, c2 INT, c3 INT)
DISTRIBUTED BY (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)
创建表。
demo=# CREATE TABLE json_test(id int, j json);
创建数据文件。
~/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)
创建表。
demo=# CREATE TABLE json_array_test(id int, j _json);
创建数据文件
~/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。
watch
是 mxgate 的一个子命令,用一系列指标描述 mxgate daemon 运行情况。
watch
有两种模式:
[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
[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
三种单位
mxgate 支持在不停止运行的情况下,修改并行加载的相关参数:"interval"、“stream-prepared”。 "interval" 代表的是完成从 mxgate 写入数据到数据库表的每个写入连接的工作时间,“stream-prepared” 代表的是活跃的写入连接的数量。在 mxgate 逻辑中,同一个数据库表同一时间只有一个写入连接执行写入数据的任务,因此每个数据库表都需要有多个连接在不同时间区间去不停地执行它自身的写入任务,从而保证高速率、高效率地写入数据。在此过程中,你可以通过 “interval” 这个参数来实现对于每个写入连接的工作时间的调整,从而改善数据的写入速率,针对性提高加载性能。具体用法示例如下:
mxgate set --stream-prepared-cli 3
设置每个表的写入连接数量为 3
mxgate get --stream-prepared-get
获取每个表活跃的写入连接数量
mxgate set --job-interval 200
设置所有表的写入连接的时间间隔为 200ms
mxgate get --job-interval-get
获取所有表的写入连接当前的时间间隔
注意!
对于以上参数,如果你想设置或获取某个特定表的写入连接数量或工作时间,那么在上述命令后加--job <名称>
即可。每个任务(job)对应一张数据库表,job 参数结构由模式名与表名组成,意思就是如果你的特定表叫做 test_table,模式名为 public,那么完成指定就需要在已有命令后加上--job public.test_table
就是对的。
在数据加载的过程中,你可能会突然发现在变化的时序数据源驱动下,之前设定的表结构对于现在场景不再适用了,然后就有了修改表结构的需求,这是 mxgate 可以满足的。此节将会说明,mxgate 如何在不停机的情况下,执行暂停数据写入,重载修改后的数据库表元信息,恢复数据写入等系列操作。具体步骤如下:
首先,使用命令 mxgate pause -X
中断所有表的写入连接,为修改数据库表结构作准备。其中 -X
参数是必要的,它会帮助中断 mxgate 和数据库之间的连接。如果不中断连接,是无法对数据库表进行修改的。除了 -X
之外,运用 -S
参数可以令 pause 命会同步等待所有连接中断完成再返回。
其次,中断对应表的所有写入连接之后,即可以对数据库对应的数据库表执行修改结构的操作,如增加若干列,删除若干列,删除已有表,重新创建“同名”的新表。
注意! 重建的表结构可以不同,但“表名”必须保持一致。
最后,使用命令 mxgate resume -R
恢复所有表的写入连接,重载数据表的元信息。其中 -R
参数是必需的,resume
与 -R
将组合完成重载操作。
特别地,多个 mxgate 进程同时运行的情况,需要 -p
参数表示对应 mxgate 进程的进程号,上述所有命令都是同理。
注意!
执行重载命令的前提是 mxgate 的对应的表的所有写入连接必须先被暂停,否则会出现如下报错:
YMatrix 从 v4.2.0 实现了 MatrixGate 的 UPSERT 功能。详见 数据分批合并场景(UPSERT)。
YMatrix 从 v4.3.0 实现了 MatrixGate 的单表迁移功能。详见 单表迁移。
注意!
YMatrix 不仅支持单表迁移,也支持全库迁移(v4.7.0 及以上)。详见 全库迁移。
我们有时需要打开 mxgate 的 debug 日志来观测一些关键信息,但是打开或者关闭 debug 日志都需要重启 mxgate,并不利于定位问题。因此, YMatrix 提供了动态变更 mxgate 日志级别的功能:
mxgate set --log-level VERBOSE
开启信息比较完整的 VERBOSE
级别的日志或者 mxgate set --log-level DEBUG
开启信息最完整的 DEBUG
级别的日志,等不需要在观察 debug 日志的时候,可以通过 mxgate set --log-level INFO
,恢复日志级别为 INFO
。