В этом документе описана подробная информация о параметрах MatrixGate.
Примечание!
Параметры в этом разделе задаются в конфигурационном файле, создаваемом до запуска mxgate.
| Имя параметра | Значение по умолчанию | Описание |
|---|---|---|
| Категория [database] | ||
| --db-database | postgres | Имя базы данных YMatrix, к которой подключается MatrixGate |
| --db-master-host | Локальное имя хоста | Имя хоста master-узла YMatrix, к которому подключается MatrixGate |
| --db-master-port | 5432 | Номер порта master-узла YMatrix, к которому подключается MatrixGate |
| --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 | Пустая строка | Строка, обозначающая NULL. Значение по умолчанию — пустая строка без кавычек. Если ограничение столбца таблицы — NOT NULL, а в данных для этого столбца указано пустое значение, загрузка завершится ошибкой. Подсказка: чтобы использовать \N в качестве NULL, экранируйте обратную косую черту, например: --null-as \N |
| --time-format | unix-second | Единица измерения метки времени: unix-second, unix-ms, unix-nano или raw. \nMatrixGate по умолчанию считает первый столбец каждой строки Unix-представлением метки времени и автоматически преобразует его в формат времени базы данных. Если метка времени находится не в первом столбце или уже преобразована пользователем в формат базы данных, используйте raw — в этом случае MatrixGate не выполняет преобразование временного типа |
| --upsert-key | Пусто | Имена ключей для выполнения UPSERT; можно указать несколько.Таблица, для которой выполняется UPSERT, должна иметь ограничение UNIQUE, а в параметре должны быть указаны все ключи ограничения |
| --deduplicate-key | Пусто | Использование аналогично UPSERT, отличие в том, что обновляются только значения NULL: если старое значение не NULL, новое значение отбрасывается.Взаимоисключающий с параметром --upsert-key; можно выбрать только один из них |
| --use-auto-increment | true | Если в целевой таблице есть автоинкрементные столбцы, пропускать ли их значения при загрузке данных и использовать значения по умолчанию |
| --target | schemaName.tableName | Имя целевой таблицы; schemaName можно опустить, по умолчанию — public. Допускается указание нескольких целевых таблиц: "--target table1 --target table2 …". Если параметр не задан, можно дополнительно указать --allow-dynamic, чтобы разрешить динамический подбор имён таблиц |
| --dml-template | Путь к файлу шаблона сопоставления полей JSON со столбцами кортежа (Tuple Column) | |
| Категория [misc] | ||
| --log-archive-hours | 72 | Файлы журналов MatrixGate в каталоге журналов, не изменявшиеся в течение указанного времени, автоматически сжимаются |
| --log-compress | true | Глобальный переключатель автоматического сжатия журналов |
| --log-dir | /home/mxadmin/gpAdminLogs | Каталог журналов |
| --log-max-archive-files | 0 | Максимальное количество сохраняемых сжатых файлов журналов; при превышении самые старые файлы удаляются. 0 — не удалять |
| --log-remove-after-days | 0 | Через сколько дней сжатые файлы журналов удаляются автоматически. 0 — не удалять |
| --log-rotate-size-mb | 100 | При превышении текущим файлом журнала указанного размера происходит переключение на новый файл, а старый файл немедленно сжимается |
| -v / --verbose | Выводить подробные журналы verbose | |
| -V / --debug | Выводить подробные отладочные журналы (включая журналы verbose и debug) | |
| --pprof-port | Порт для доступа к информации Pprof; 0 — отключено |
|
| --no-cleanup | Сохранять временную схему даже при нормальном завершении | |
| --grpc-port | Порт для доступа к информации gRPC; 0 — отключено |
|
| Категория [metrics] | ||
| --metrics-enable | true | Включить метрики |
| --metrics-sample-interval | 15 (изменено на 15 начиная с v5.3.2, ранее было 3) | Интервал выборки метрик (в секундах). Установите значение больше 0, чтобы включить сбор метрик (снижает производительность) |
| Категория [source] | ||
| --source | http | Источник данных MatrixGate; поддерживаются http / stdin / kafka / transfer / grpc |
| Категория [source] | [HTTP] | Примечание: этот режим — режим подключения к источнику данных по умолчанию в конфигурационном файле |
| --http-port | 8086 | HTTP-интерфейс для отправки данных пользователями MatrixGate |
| --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 | IP-адрес master-узла исходной базы данных | |
| --src-port | Номер порта master-узла исходной базы данных | |
| --src-user | Имя пользователя для подключения к исходной базе данных (рекомендуется Superuser) |
|
| --src-password | Пароль для подключения | |
| --src-schema | Имя схемы исходной таблицы | |
| --src-table | Имя исходной таблицы | |
| --src-sql | SQL-запрос для фильтрации данных при миграции | |
| --compress | Метод сжатия при передаче данных с segment-узлов исходной базы данных в текущую базу данных: Пустая строка "" — без сжатия, передача в открытом виде gzip: сжатие gzip; на каждом segment-хосте исходной базы данных должна быть установлена Linux-команда gziplz4: сжатие lz4; на каждом segment-хосте исходной базы данных должна быть установлена Linux-команда lz4Рекомендуется lz4 > gzip > без сжатия |
|
| --port-base | 9129 | При передаче занимается один порт |
| --local-ip | Необходимо указать IP-адрес этой машины, достижимый из исходной базы данных | |
| Категория [source] | [Kafka] | Примечание: этот режим не является режимом по умолчанию; для его использования настройте параметры этого раздела вручную; полный пример аутентификации см. в Защищённом подключении Kafka |
| --kafka-broker | Нет | Адрес брокера Kafka; несколько брокеров указываются через запятую |
| --kafka-version | 1_0_0_0 | Версия Kafka. Допустимые значения: 0_8_2_0, 0_8_2_1, 0_8_2_2, 0_9_0_0, 0_9_0_1, 0_10_0_0, 0_10_0_1, 0_10_1_0, 0_10_1_1, 0_10_2_0, 0_10_2_1, 0_11_0_0, 0_11_0_1, 0_11_0_2, 1_0_0_0, 1_1_0_0, 2_0_0_0 |
| --kafka-lib-log | false | Выводить ли журнал процесса подключения к Kafka |
| --kafka-max-checkpoint-gap | 134217728 | Максимально допустимый интервал (в байтах) между checkpoint потребления и потреблённым offset |
| --kafka-message-count | 0 | Количество сообщений, которые нужно потребить; 0 — без ограничения |
| --kafka-params | Пусто | Значения topic, partition, consumer-group, consumer-group-members и job в виде строки; при использовании [[source.kafka.topic]] можно не указывать |
| --enable-sasl | false | Включить ли аутентификацию SASL |
| --enable-sasl-handshake | false | Включить ли Kafka SASL handshake; для стандартных SASL-подключений Kafka обычно устанавливается true |
| --sasl-mechanism --sasl-user --sasl-password |
Пусто | Механизм аутентификации SASL и данные аутентификации |
| --scram-algorithm --scram-authz-id |
Пусто | Алгоритм и идентификатор авторизации, используемые при аутентификации SCRAM |
| --ssl-ca-cert | Пусто | Путь к CA-сертификату; после настройки этого параметра включается SSL-подключение |
| --gssapi-auth-type | Пусто | Способ аутентификации GSSAPI: KEYTAB — аутентификация с помощью файла keytab, USER — аутентификация с помощью имени пользователя и пароля |
| --gssapi-kerberos-config-path --gssapi-keytab-path --gssapi-user --gssapi-password --gssapi-realm --gssapi-service-name |
Пусто | Пути к конфигурации и данные идентификации, необходимые для аутентификации GSSAPI; пример см. в Защищённом подключении Kafka |
| --gssapi-disable-pafxfast | false | Отключить ли быструю аутентификацию GSSAPI (PAFXFAST); если подключение завершается ошибкой на этапе быстрой аутентификации, установите true и повторите попытку |
| Категория [source] | [[source.kafka.topic]] |
Примечание: по одной записи на каждый topic; для одного topic можно настроить несколько участников потребления |
| --topic | Нет | Топик Kafka, который нужно потреблять |
| --partition | Нет | Разделы, которые нужно потреблять; * — все разделы |
| --job | Нет | Имя задачи (Job) записи, соответствующей этому topic |
| --consumer-group | Пусто | Группа потребителей, используемая этим topic; если не настроена, группа потребителей не используется |
| --consumer-group-members | — | Количество участников потребления этого topic; при настройке нескольких участников topic потребляется совместно несколькими участниками одной группы потребителей |
| Категория [transform] | ||
| --transform | plain | Преобразование формата или типов записываемых данных. Поддерживаются plain / json / nil / tsbs / hanagdbc |
| Категория [writer] | ||
| --interval | 100 миллисекунд | Период выполнения пакетной загрузки данных в MatrixGate |
| --writer | stream | MatrixGate записывает данные в YMatrix с помощью Writer. Поддерживаются stream / nil |
--stream-prepared |
10 | Сколько процессов slot одновременно вызывается в одной задаче (Job) |
| --stream-host | mdw | Имя хоста, к которому master-узел YMatrix подключается к MatrixGate. Полезно, если в системе несколько сетевых интерфейсов |
| --use-gzip | auto | Включать ли сжатие при отправке данных MatrixGate на segment-узлы; допустимые значения auto/yes/no:при auto приоритет отдаётся алгоритму сжатия zstd;--use-gzip=yes означает использование алгоритма сжатия gzip--use-gzip=no запрещает передачу со сжатием. Это немного снижает загрузку ЦП, но значительно увеличивает объём передаваемых данных. Рекомендуется не использовать no, если только это не одиночная база данных, и mxgate, и база данных находятся на одном хосте; во всех случаях достаточно значения по умолчанию auto |
| --max-seg-conn | 128 | Количество segment-узлов, запускаемых при выгрузке данных из MatrixGate во внешнюю таблицу; увеличение этого параметра повышает расход сетевых ресурсов |
| --timing | false | При установке true MatrixGate добавляет в журнал информацию о затраченном времени для каждого оператора INSERT |
| --insert-timeout | 600000 | Время ожидания выполнения оператора INSERT в MatrixGate.При значении больше 0 оператор завершается по тайм-ауту через указанное время в миллисекундах |
| -I / --instrumentation | disable | Включение трассировки slot(s); поддерживаются варианты disable / single / all:disable — функция отключена;single — включена трассировка только slot[0];all — включена трассировка всех slot |
--bytes-limit |
Ограничение размера пакетной загрузки данных. Обеспечивает равномерность загрузки при неравномерном потоке данных, поступающем в MatrixGate. По умолчанию функция отключена; для включения необходимо вручную задать размер в диапазоне 0~INT_MAX |
|
--auto-tune |
false | При установке true MatrixGate может изменять количество slot задачи записи |
--abort-by-pause-timeout |
10000 | После выполнения команды приостановки (Pause) задачи (Job) по истечении указанного времени ожидания накопленные в памяти и предназначенные для записи в базу данных данные автоматически отбрасываются. Диапазон значений — 0~INT_MAX; рекомендуется 1000~10000, единица измерения — миллисекунды (ms); значение 0 отключает функцию. Рекомендуется задавать это значение значительно ниже --request-timeout, чтобы для неприостановленных задач по-прежнему использовалось время ожидания --request-timeout. После приостановки задачи mxgate автоматически сравнивает оба указанных параметра времени ожидания и вызывает ошибку тайм-аута по меньшему из них. Этот параметр можно настраивать только при writer="stream" |
Примечание!
Параметры в этом разделе можно выполнять в командной строке после запуска mxgate.
| Имя параметра | Имя подпараметра | Описание |
| run | Запустить MatrixGate в командной строке | |
| start | Запустить фоновый процесс MatrixGate | |
| stop | Завершить фоновый процесс MatrixGate | |
| -f / --force | Принудительно завершить процесс MatrixGate | |
| --grpc-port | Завершить процесс MatrixGate, слушающий указанный порт, отправкой gRPC-запроса | |
| status | Вывести состояние фонового процесса MatrixGate | |
| config | Вывести полный конфигурационный файл | |
| log | Показать последние 10 записей журнала | |
| -n / --lines int | Указать, сколько последних записей журнала показывать; после параметра нельзя опускать значение int | |
| version | Показать версию | |
| help | Показать синтаксис и список параметров | |
| -C / --config | Загрузить конфигурационный файл; в настоящее время поддерживается как подпараметр команд start / run | |
| -p / --pid | ID процесса MatrixGate; в настоящее время поддерживается как подпараметр команд stop / log / watch / pause / resume | |
| --job | Задача (Job), для которой задаётся параметр. Поскольку каждая задача существует в одной таблице, на практике достаточно указать имя соответствующей таблицы; в настоящее время поддерживается как подпараметр команд stop / log / watch / pause / resume | |
| set | --stream-prepared-cli | Задать количество активных slot записи в задаче (Job) ࠾ Значение по умолчанию для --stream-prepared-cli — 10 ࠾ Пример: mxgate set --stream-prepared-cli 3 |
| --job-interval | Задать рабочее время ETL (Extract-Transform-Load) задачи записи (в миллисекундах, ms) ࠾ Значение по умолчанию для --job-interval — 100 ࠾ Пример: mxgate set --job-interval 150 |
|
| --high-water-mark | Задать порог верхнего уровня (нагрузки записи) для целевой задачи ࠾ Значение по умолчанию для --high-water-mark — 0 ࠾ Пример: mxgate set --high-water-mark 20 |
|
| --disable-high-water-mark | Задать, отключать ли порог верхнего уровня ࠾ Значение по умолчанию для --disable-high-water-mark — false ࠾ Пример: mxgate set --disable-high-water-mark=true |
|
--auto-tune | Задать, включать ли функцию автоматической регулировки количества slot ࠾ Включить эту функцию для всех задач: mxgate set --auto-tune=true ࠾ Отключить эту функцию для всех задач: mxgate set --auto-tune=false ࠾ Включить эту функцию для указанной задачи: mxgate set --auto-tune=true --job public.t1 |
|
| get | --stream-prepared-get | Получить количество slot записи в задаче (Job) ࠾ Пример: mxgate get --stream-prepared-get |
| --stream-status-get | Получить состояние slot записи в задаче записи ࠾ Пример: mxgate get --stream-status-get |
|
| --job-interval-get | Получить рабочее время задачи записи ࠾ Пример: mxgate get --job-interval-get |
|
| --job-list | Получить сведения о всех задачах записи ࠾ Пример: mxgate get --job-list |
|
| --job-state | Получить состояния всех задач записи ࠾ Пример: mxgate get --job-state |
|
| --current-config | Получить конфигурацию текущего процесса MatrixGate ࠾ Пример: mxgate get --current-config |
|
| --kafka-topics | Получить все тестовые топики (Kafka Topic) ࠾ Пример: mxgate get --kafka-topics |
|
| --kafka-messages | Получить все сообщения (Messages) указанного топика Kafka ࠾ Пример: mxgate get --kafka-messages |
|
| --source-pressure | Получить нагрузку записи данных источника, соответствующего целевой задаче ࠾ Пример: mxgate get --source-pressure |
|
| --high-water-mark-get | Получить заданный для целевой задачи порог верхнего уровня (нагрузки записи) ࠾ Пример: mxgate get --high-water-mark-get |
|
--auto-tune-status | Получить состояние автоматической регулировки количества slot задачи записи ࠾ Получить состояние автоматической регулировки количества slot для всех задач записи: mxgate get --auto-tune-status ࠾ Получить состояние автоматической регулировки количества slot для указанной задачи: mxgate get --auto-tune-status --job public.t1 |
|
| pause | -X / --disconnect | Разрывать ли slot между segment-узлами и mxgate при приостановке mxgate (это приведёт к прерыванию всех slot всех задач) ࠾ Пример: mxgate pause -X |
| -S / --sync | Если этот подпараметр не указан явно, mxgate выполняет асинхронную приостановку; при явном указании подпараметра mxgate дожидается приостановки всех задач записи (Job) и только затем возвращает результат ࠾ Пример: mxgate pause -S |
|
| resume | -R / --reload | Перезагружать ли метаданные задачи при возобновлении записи ࠾ Пример: mxgate resume -R |
| offset-reset | Сбросить позиции потребления остановленного потока данных Kafka; при нескольких потоках данных сначала локализуйте один из них параметрами выбора (при единственном потоке он выбирается автоматически) ࠾ Пример: mxgate offset-reset --topic csv_test --to-earliest --dry-run ࠾ Подробнее см. раздел «Сброс позиций потребления Kafka» в документе Подключение Kafka |
|
| --topic / --consumer-group / --job | Локализовать поток данных для сброса; при указании этих параметров они должны в точности соответствовать одному потоку (flow); при отсутствии группы потребителей `--consumer-group` опускается | |
| --to-earliest | Сбросить к самой ранней позиции, всё ещё сохранённой в Kafka | |
| --to-latest | Сбросить к самой новой позиции (с пропуском накопившихся данных) | |
| --to-datetime | Сбросить к первому сообщению в указанное время или позже | |
| --to-offsets | Указать позиции по разделам, например `'0:100,1:200'` | |
| --dry-run / --output / -y | Только вывести план сброса, ничего не изменяя; `--output json` выводит один объект JSON, используется вместе с `--dry-run` или `-y`; `-y` пропускает интерактивное подтверждение и подходит для автоматизации | |
| watch | ||
| -D / --daemon-addr | Адрес gRPC-службы процесса MatrixGate (host:port) | -i / --info | Непрерывно выводить назначение каждого столбца соответствующих метрик, отображаемых mxgate watch ࠾ Пример: mxgate watch --info |
| -T / --time | Указать продолжительность вывода соответствующих метрик мониторинга (в секундах, s) ࠾ Значение по умолчанию — -1, то есть непрерывный вывод ࠾ Пример: mxgate watch --time 200 |
|
| -H / --history | Показать исторические метрики ࠾ Пример: mxgate watch --history |
|
| --watch-latency | Непрерывно выводить метрики мониторинга Latency ࠾ Пример: mxgate watch --watch-latency |
|
| --watch-start | Просмотреть исторические записи о запусках; по умолчанию за последние 24 часа от текущего времени, например 2022-04-11 11:09:20 ࠾ Пример: mxgate watch --watch-start |
|
| --watch-end | Просмотреть исторические записи о завершениях; по умолчанию — текущее время, например 2022-04-11 11:09:20 ࠾ Пример: mxgate watch --watch-end |
|
| --watch-duration | Просмотреть историческую продолжительность ࠾ Пример: mxgate watch --watch-duration |
Примечание!
Об основных функциях MatrixGate см. Основные функции MatrixGate.
