В этом документе описаны основные функции MatrixGate.
Примечание!
Для доступа к MatrixGate из языков программирования см. раздел Загрузка данных — Доступ к MatrixGate из языков программирования.
demo=# CREATE TABLE csvtable (time TIMESTAMP WITH TIME ZONE, tagid INT, c1 INT, c2 INT, c3 INT)
DISTRIBUTED BY (tagid);1603777821|1|101|201|301
1603777822|2|102|202|302
1603777823|3|103|203|303[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 Пример загрузки полей JSON через MatrixGate
#### 1.2.1 JSON
- Создайте таблицу.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)
#### 1.2.2 Массив JSON
- Создайте таблицу.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 содержит специальные символы, такие как кавычки, параметр --format для mxgate должен быть установлен в CSV.
<a name="watch"><br/></a>
## 2 Наблюдение за показателями работы mxgate
`watch` — это подкоманда mxgate, которая использует ряд показателей для описания работы демона mxgate.
Существует два режима `watch`:
- Режим наблюдения в реальном времени: вывод метрик шлюза каждые 3 секунды в формате, аналогичном sar.
- Режим исторического наблюдения: можно указать любой временной период (например, каждый час вчера, каждый день прошлого месяца, каждый месяц прошлого года) для статистики скорости импорта.
### 2.1 Наблюдение в реальном времени[mxadmin@mdw ~]$ mxgate watch
Показатели работы mxgate будут собираться каждые три секунды, результат вывода следующий: Time WCount ICount WSpeed/s ISpeed/s WBandWidth MB/S BlocakItems2022-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-lateency, чтобы наблюдать за задержками.[mxadmin@mdw ~]$ mxgate watch --watch-latency
### 2.2 Наблюдение за историческими данными[mxadmin@mdw ~]$ mxgate watch --history
Будет рассчитана средняя скорость за каждый час в течение последних 24 часов, результат вывода следующий: TIME RANGE | SPEED/S | BANDWIDTH MB/S | BLOCK ITEMS2022-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 обозначают скорость импорта записей и пропускную способность импорта (в МБ/с),
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'
Средняя скорость импорта в неделю (каждые 168 ч) с 27 марта по 27 апреля.
Параметр `--watch-duration` поддерживает три единицы измерения: `h`` `m`` `s`
<a name="non-stop_update_parameters"><br/></a>
## 3 Обновление параметров параллельной записи без остановки
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` Установите временной интервал соединений записи для всех таблиц в 200 мс
- `mxgate get --job-interval-get` Получите текущий временной интервал соединений записи для всех таблиц
> ***Примечание!***
Для указанных выше параметров, если вы хотите установить или получить количество соединений записи или рабочее время для конкретной таблицы, добавьте после команды `--job <name>`. Каждое задание (job) соответствует одной таблице базы данных. Структура параметра job состоит из имени схемы и имени таблицы. Например, если ваша конкретная таблица называется test_table, а схема — public, необходимо добавить `--job public.test_table` после существующей команды.
<a name="non-stop_update_table"><br/></a>
## 4 Изменение структуры таблицы без остановки
Во время загрузки данных может внезапно выясниться, что из-за изменения источников временных рядов ранее заданная структура таблицы больше не подходит для текущего сценария, и возникает необходимость изменить структуру таблицы, что возможно с помощью mxgate. В этом разделе объясняется, как mxgate выполняет серию операций, таких как приостановка записи данных, перезагрузка изменённой метаинформации таблицы базы данных и восстановление записи данных, без остановки системы. Конкретные шаги следующие:
* Во-первых, используйте команду `mxgate pause -X`, чтобы прервать соединения записи для всех таблиц, подготовившись к изменению структуры таблицы базы данных. Параметр `-X` является обязательным — он помогает прервать соединение между mxgate и базой данных. Если соединение не будет прервано, изменить таблицу базы данных невозможно. Кроме того, вместо `-X` используйте параметр `-S`, чтобы приостановка задания синхронно дождалась завершения прерывания всех соединений перед возвратом.
* Во-вторых, после прерывания всех соединений записи к соответствующей таблице можно изменить структуру таблицы базы данных, например, добавить столбцы, удалить столбцы, удалить существующую таблицу и создать новую таблицу с тем же именем.
> ***Примечание!***
Структура пересозданной таблицы может отличаться, но имя таблицы должно оставаться одинаковым.
* Наконец, используйте команду `mxgate resume -R`, чтобы восстановить соединения записи для всех таблиц и перезагрузить метаинформацию таблицы данных. Параметр `-R` обязателен; `resume` и `-R` совместно выполняют операцию перезагрузки.
* Особо важно: когда одновременно запущено несколько процессов mxgate, необходимо использовать параметр `-p` для указания номера соответствующего процесса mxgate, это относится ко всем вышеуказанным командам.
> ***Примечание!***
Условие выполнения команды перезагрузки — предварительная приостановка всех соединений записи к соответствующей таблице mxgate. В противном случае произойдет следующая ошибка:
<a name="upsert"><br/></a>
## 5 Поддержка функции UPSERT
YMatrix реализует функцию UPSERT в MatrixGate начиная с версии v4.2.0. Подробнее см. [Сценарий пакетного слияния данных (UPSERT)](/ru/doc/5.0/datainput/upsert).
<a name="transfer"><br/></a>
## 6 Миграция одной таблицы
YMatrix реализует функцию миграции одной таблицы в MatrixGate начиная с версии v4.3.0. Подробнее см. [Миграция одной таблицы](/ru/doc/5.0/maintain/migrate/mxgate).
>***Примечание!***
YMatrix поддерживает не только миграцию одной таблицы, но и миграцию всей базы данных (v4.7.0 и выше). Подробнее см. [Миграция всей базы данных](/ru/doc/5.0/maintain/migrate/mxshift).
<a name="log_level"><br/></a>
## 7 Динамическое изменение уровня логирования без остановки
Иногда нам нужно включить отладочный лог mxgate, чтобы наблюдать за некоторыми ключевыми информационными сообщениями, но включение или отключение отладочного лога требует перезапуска mxgate, что неудобно для диагностики проблем. Поэтому YMatrix предоставляет возможность динамически изменять уровень логирования mxgate:
* Когда gate работает, используйте команду `mxgate set --log-level VERBOSE`, чтобы включить уровень лога `VERBOSE` с достаточно полной информацией, или `mxgate set --log-level DEBUG`, чтобы включить уровень лога `DEBUG` с максимально полной информацией. Когда отладочный лог больше не нужен, используйте `mxgate set --log-level INFO`, чтобы восстановить уровень лога до `INFO`.