YMatrix 文档

版本发布历史
系统需求

关于 YMatrix

快速上手

标准集群部署

数据建模

连接到数据库

数据写入

数据迁移

数据查询

运维监控

性能调优

故障诊断

参考指南

SQL 参考

常见问题（FAQ）

场景应用

MatrixGate 参数

本文档介绍了 MatrixGate 的详细参数信息。

1 配置文件

参数名 默认值 参数含义
[general]类别
-C / --config string 空 MatrixGate 要加载的配置文件
-f / --force 强制终止 MatrixGate 进程
-p / --pid -1 MatrixGate 进程的 ID，目前支持 stop / log / watch / pause / resume 等
-D / --daemon-addr MatrixGate 进程的 gRPC 服务地址（host:port）， 目前支持 watch 等
-n / --lines 10 打印最新的十条日志
-s / --set 设置某些参数
-g / --get 获取某些参数
--job-interval-get false 获取写入任务的工作时间
--job-list false 获取所有的写入任务信息
--job-state false 获取所有的写入任务状态
--stream-prepared-get 11 获取写入任务中写入连接的数量
--stream-status-get false 获取写入任务中写入连接的状态
--stream-prepared-cli 0 写入任务中活跃写入连接的数量
--status 获取当前 MatrixGate 进程的状态
--current-config 获取当前 MatrixGate 进程的配置
--kafka-topics 获取所有的测试主题（Kafka Topic）
--kafka-messages 获取某一 Kafka Topic 的所有消息（Messages）
--job-interval 写入任务的 ETL（Extract-Transform-Load）工作时间
--pause false 中断写入
--resume false 恢复写入
-X / --disconnect 当 mxgate 暂停时，是否断开 Segment 和 mxgate 之间的连接
-R / --reload 是否重新加载任务的元数据
-S / --sync false 默认情况下，我们将执行异步暂停，当 sync == true，将等待所有数据插入任务暂停完成
--job 需要设置参数的任务
-w / --watch 持续打印 watch 相关的监控指标
-i / --info 打印 mxgate watch 展示出来的相关指标每一列的含义
-T / --time -1，即不间断打印 指定相关监视指标的持续时间（秒）
--watch-latency false 打印 Latency 相关监控指标
--watch-start now-24h 查看历史启动记录，默认当前时间前 24 小时内，如 2022-04-11 11:09:20
--watch-end now 查看历史终止记录，默认当前时间，如 2022-04-11 11:09:20
--watch-duration 1h 查看历史时长
-H / --history 显示历史指标
--source-pressure 0 获取目标任务对应的源端数据写入负载
--high-water-mark 0 设定目标任务的（写入负载）高水位阈值
--high-water-mark-get false 获取为目标任务设定的（写入负载）高水位阈值
--disable-high-water-mark false 禁用高水位阈值
[database]类别
--db-database postgres MatrixGate 连接 YMatrix 数据库名
--db-master-host 本机主机名 MatrixGate 连接 YMatrix 主机名
--db-master-port 5432 MatrixGate 连接 YMatrix 主机端口号
--db-user 当前系统用户名 MatrixGate 连接 YMatrix 用户名
注意！ 该用户必须具有创建外部表的权限，如果使用的是非超级权限用户，请使用如下命令增加权限：
alter user {username} CREATEEXTTABLE;
--db-password 空 MatrixGate 连接 YMatrix 用户密码
--db-max-conn 10 MatrixGate 连接 YMatrix 最大连接数
[job]类别
--allow-dynamic false 当指定 --allow-dynamic=true 时，允许根据 POST 的数据内容(第一行)，动态适配插入的目标表。此选项应仅用于 MatrixGate 启动时目标表名尚未确定的场景。如果固定插入某个已知的目标表，推荐用 --target 显式指定表名
--delimiter | 指定用于分隔文件每一行（行）中各列的字符
--error-handling accurate 遇到格式错误行的处理方式
'accurate'：错误数据不入库并记录错误日志，该批次其他数据不受影响
'legacy'：该批次整体失败
--exclude-columns 空 数据加载默认提供的列数量和列顺序需要与表定义一致，当数据加载仅提供部分列时，--exclude-columns 用于标记排除的列名，其他列仍需要保证顺序与表定义一致。 提示：如果已经开启 --use-auto-increment 跳过自增字段，则不需要在此列出这些自增字段。这个参数只需要标记出其他还需要排除的列名即可
--format text 指定源数据的数据格式 text 或 csv。text 速度最快，但不支持字符类型中出现换行。csv 格式适用性更广，对字符类型的列必须用双引号。
--null-as 空字符串 指定表示空值的字符串。 默认值为无引号的空字符串。当数据表中的列约束为非空 NOT NULL，且数据内容上该列给出了空值，将会导致加载报错。提示：如需要使用 \N 为空值，需要对反斜杠进行转义，如：--null-as \N
--time-format unix-second 指定时间戳单位：unix-second \| unix-ms\|unix-nano \| raw。\n MatrixGate默认将每行数据的第一列当作时间戳的 Unix 表示，自动将其转化为数据库时间格式。如果时间戳不在第一列，或者用户已经自行转换为数据库格式，则应使用 raw，这样 MatrixGate 不会做时间类型转换。
--upsert-key 空 进行 UPSERT 的键名，可以指定多个。
需要做 UPSERT 的表，必须建立 UNIQUE 约束，且参数中要指定所有约束键。
--deduplicate-key 空 用法和 UPSERT 类似，区别是只更新空值，如果旧值非空，新值丢弃。
和 --upsert-key 参数互斥，只能选一种。
--use-auto-increment true 当 target 表中含有自增字段时，是否在加载数据中跳过自增字段赋值而使用系统默认自增值
--target schemaName.tableName 指定目标的表名，schemaName 可以省略，默认为 public。允许指定多个目标表，使用方法是 "--target 表1 --target 表2 …"。当不提供此参数时，可以额外指定 --allow-dynamic 参数来允许动态适配表名。
--dml-template 将 JSON 字段映射到元组列（Tuple Column）的映射模板的文件路径
[misc]类别
--log-archive-hours 72 日志目录下，超过一定时间未发生改变的 MatrixGate 日志文件，被自动压缩
--log-compress true 是否开启 log 自动压缩的全局开关
--log-dir /home/mxadmin/gpAdminLogs 日志目录
--log-max-archive-files 0 最多保留多少个压缩的 log 文件，超过这个数量，则最老的日志文件会被删除。0 为不删除
--log-remove-after-days 0 被压缩后的 log 文件，再经过多少天被自动删除。0 为不删除
--log-rotate-size-mb 100 当前 log 文件超过一定大小则自动切换到一个新文件，旧文件则立即压缩
-v / --verbose 打印详细的 verbose 日志
-V / --debug 打印详细的调试日志（包含 verbose 日志及 debug 日志）
--pprof-port 访问 Pprof 信息的端口，0 表示禁用
-h / --help 打印 MatrixGate 用法
--version 打印 MatrixGate 版本
--no-cleanup 即使在正常退出时也保留临时模式
--grpc-port 访问 gRPC 信息的端口，0 表示禁用
[metrics]类别
--metrics-enable true 启用指标
--metrics-sample-interval 3 指标的采样间隔（秒）。将其设置为 >0 以启用指标收集（会降低性能）
[source]类别
--source http MatrixGate 数据来源，支持 http / stdin / kafka / transfer / grpc
[source]类别 [HTTP]
--http-port 8086 MatrixGate 用户提交数据的 HTTP 接口
--max-body-bytes 4194304 每个 HTTP 包体大小上限
--max-concurrency 40000 HTTP 最大并发连接数
--request-timeout 0 请求超时时间，默认 0。当设置大于 0 的值，会在等待毫秒单位的设置时间后超时并返回 timeout(408)
--disable-keep-alive false MatrixGate 在每次 HTTP 请求后强制断开连接
--http-debug false 输出附加 HTTP 源的诊断信息
[source]类别 [Transfer]
--src-host 源库 Master 的 IP 地址
--src-port 源库 Master 的端口号
--src-user 连接源库的用户名(建议使用 Superuser)
--src-password 连接密码
--src-schema 源表的模式名
--src-table 源表的表名
--src-sql 进行迁移数据过滤的 SQL
--compress 源数据库 Segment 主机到本数据的传输方法：
空白字符串“”，代表不压缩，明文传输
gzip：使用 gzip 压缩，需要源数据库的 Segment 主机上必须安装有 gzip 这个 Linux 命令
lz4：使用 lz4 压缩，需要源数据库的 Segment 主机上必须安装有 lz4 这个 Linux 命令
推荐 lz4 > gzip > 不压缩
--port-base 传输中会占用一批端口，端口的范围为 9129～
--local-ip 必须用源库可以连接到本机的 IP 地址
[transform]类别
--transform plain 将写入的数据进行格式或类型转换。支持 plain / json / nil / tsbs / hanagdbc
[writer]类别
--interval 100 毫秒 MatrixGate 执行批量数据加载时间周期
--writer stream mxgate 通过 Writer 将数据写入到 YMatrix。支持 stream / nil

--stream-prepared		 10 插入工作进程并行度
--stream-host mdw YMatrix 中 Master 连接到 MatrixGate 的主机名。这是为了系统有多个网络接口
--use-gzip auto MatrixGate 向 Segment 发送数据时是否开启压缩，可配置参数为 auto/yes/no。auto 设置下优先选用 zstd 压缩算法，如果目标数据库不支持（4.8.0 版本之前），则自动退化为 gzip 压缩算法，如果 gzip 也不支持则不压缩；如果强制设为 --use-gzip=no，则会禁止压缩传输。此设置虽能节省少量 CPU 占用，但是会大大增加网络传输数据量，我们建议除非为单机部署的数据库，且 mxgate 和数据库全部在同一台主机上，否则慎用 no 设置，一律采用默认值 auto 即可
--max-seg-conn 128 外部表从 MatrixGate 拉取数据时启动的 Segment 数量，调大该参数会增加网络连接资源
--timing false 开启该参数后，MatrixGate 在记录日志时会为每条 INSERT 增加耗时信息
--insert-timeout 600000 MatrixGate 执行 INSERT 语句超时时间。
设置大于 0 的值后会在等待毫秒单位配置时间后超时
-I / --instrumentation disable 打开 slot(s) 的检测，支持 disable / single / all 选项。single 表示只打开 slot[0] 的检测，all 表示打开所有 slot 的检测

--bytes-limit		 批量数据加载的的大小限制。在输入到 MatrixGate 的数据流不均匀的情况下，保障入库数据均匀

--auto-tune		 false 开启该参数后，MatrixGate 可以调整任务的写入连接数

2 命令行参数

命令行参数名 参数含义
--run 在命令行运行 MatrixGate
--start 启动 MatrixGate 后台进程
--stop 终止 MatrixGate 后台进程
--status 打印 MatrixGate 后台进程的状态
--config 打印配置文件完整模版
--log 显示日志
--set 设置某些参数
--get 获取某些参数
--watch 观测 MatrixGate 守护进程指标，你可以执行 mxgate watch --info 获取观测表的列名
--version 显示版本
--help 显示用法和参数列表

注意！
MatrixGate 主要功能介绍请见 MatrixGate 主要功能。