История версий
Требования

YMatrix

Быстрый старт

Развертывание

Моделирование данных

Подключение

Запись данных

Миграция

Запросы

Операции и обслуживание

Настройка производительности

Устранение неполадок

Справочник

Справочник по SQL

Часто задаваемые вопросы

Основные функции MatrixGate

В этом документе описываются основные функции MatrixGate.

Примечание!
Для получения информации о доступе к MatrixGate из языков программирования см. Загрузка данных — Доступ к MatrixGate из языков программирования.


1 Загрузка специальных типов данных через MatrixGate

1.1 Пример загрузки CSV-файлов через MatrixGate

  • Создайте таблицу csvtable в базе данных demo.
    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 Пример загрузки полей JSON через MatrixGate

#### 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 содержит специальные символы, такие как кавычки, параметр --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     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 — это скорость импорта записей и пропускная способность импорта (в МБ/с),
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 поддерживает изменение параметров параллельной загрузки `--stream-prepared` и `--interval` без остановки процесса:
- `--stream-prepared` определяет количество активных слотов при записи данных mxgate в каждую таблицу YMatrix. По умолчанию количество слотов во всех таблицах одинаково. Его можно вручную настроить для отдельной задачи (Job) (по одной задаче на таблицу).
  - Увеличение значения `--stream-prepared` обычно означает повышение степени параллелизма записи данных и, соответственно, производительности, но также увеличивает потребление памяти.
  - Уменьшение значения `--stream-prepared` снижает использование ресурсов памяти на узлах данных (Segment), однако производительность также снижается.
- `--interval` определяет рабочий интервал времени для каждого активного слота, то есть после ожидания каждым слотом `--interval` (в миллисекундах, мс) данные, полученные mxgate за этот период, отправляются в YMatrix.
  - Увеличение значения `--interval` означает увеличение задержки при каждой записи данных и рост объема передаваемых данных (при условии непрерывного потока данных в mxgate).
  - Уменьшение значения `--interval` снижает задержку и объем передаваемых данных.

Таким образом, на практике эти два параметра необходимо разумно настраивать с учетом особенностей различных систем хранения и требований пользователей к реальному времени записи данных.

Примеры использования:

- Установите количество слотов на таблицу равным 3

$ mxgate set --stream-prepared-cli 3

- Получите количество активных слотов на таблицу

$ mxgate get --stream-prepared-get

- Установите интервал между слотами для всех таблиц равным 200 мс

$ mxgate set --job-interval 200

- Получите текущий временной интервал слотов для всех таблиц

$ mxgate get --job-interval-get

> ***Примечание!***  
Для указанных выше параметров, если вы хотите установить или получить количество слотов или время работы для конкретной таблицы, добавьте параметр `--job <name>` после команды. Каждая задача соответствует одной таблице базы данных. Структура параметра job состоит из имени схемы и имени таблицы. Например, если ваша таблица называется test_table, а схема — public, необходимо добавить `--job public.test_table` после существующей команды.

<a name="non-stop_update_table"><br/></a>
## 4 Изменение структуры таблицы без остановки

Во время загрузки данных, по мере расширения источников временных рядов, ранее заданная структура таблицы может перестать соответствовать текущим требованиям, что вызывает необходимость её изменения. В этом разделе объясняется, как mxgate может приостановить запись данных, перезагрузить метаданные таблицы и возобновить запись без остановки. Конкретные шаги следующие:

 * Сначала выполните команду `mxgate pause -X`, чтобы прервать слоты всех таблиц и подготовиться к изменению структуры таблицы базы данных. Параметр `-X` является обязательным — он помогает прервать соединение слотов между mxgate и базой данных. Если слоты не прерваны, изменить структуру таблицы невозможно. Кроме `-X`, можно использовать параметр `-S`, чтобы команда ожидания паузы синхронно дождалась завершения прерывания всех слотов перед возвратом.

$ mxgate pause -X

| \/ | | | _ () / _| | | __ | |\/| |/ ` | | '| \ \/ / | / ` | / \ | | | | (| | || | | |> <| || | (_| | || / || ||_,|_|| |//_\|\,_|\_| Version: v5.2.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.2.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`

<a name="upsert"><br/></a>
## 5 Поддержка функции UPSERT

YMatrix реализует функцию UPSERT в MatrixGate начиная с версии v4.2.0. Подробнее см. [Сценарий пакетного слияния данных (UPSERT)](/ru/doc/5.2/datainput/upsert).

<a name="transfer"><br/></a>
## 6 Миграция одной таблицы

YMatrix реализует функцию миграции одной таблицы в MatrixGate начиная с версии v4.3.0. Подробнее см. [Миграция одной таблицы](/ru/doc/5.2/maintain/migrate/mxgate).

>***Примечание!***  
YMatrix поддерживает не только миграцию одной таблицы, но и миграцию всей базы данных (начиная с версии v4.7.0 и выше). Подробнее см. [Миграция всей базы данных](/ru/doc/5.2/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`.

<a name="eventtrigger"><br/></a>
 ## 8 Событийные триггеры mxgate

Иногда нам нужно выполнить некоторые DDL-изменения в таблице во время операции вставки через mxgate. Эта функция позволяет mxgate «отложить» входящую операцию вставки после получения инструкции DDL, чтобы DDL-оператор мог быть выполнен как можно скорее.

Поддерживаемые DDL-операции:
 1. Очистка таблицы или группы таблиц

=# TRUNCATE TABLE ;

2. Добавление столбцов, удаление столбцов и изменение типов столбцов в таблице

=# ALTER TABLE ADD COLUMN ; =# ALTER TABLE DROP COLUMN ; =# ALTER TABLE ALTER COLUMN TYPE ;

3. Изменение имени таблицы

=# ALTER TABLE RENAME TO ;

4. Удаление таблицы с последующим повторным созданием

=# DROP TABLE ; =# CREATE TABLE <tablename(column datatype)>;

5. Вышеуказанные четыре DDL-операции для партиционированных таблиц

<a name="autotune"><br/></a>
## 9 Автоматическая настройка количества слотов mxgate

Обычно мы можем адаптировать нагрузку (то есть объем данных для записи) различных задач записи, вручную регулируя параметр [stream-prepared](/ru/doc/5.2/tools/mxgate/parameter#streamprepared) (количество параллельно выполняемых сессий слотов). Однако в некоторых бизнес-сценариях нагрузка на задачи записи постоянно меняется, и эти изменения невозможно корректировать вручную.

Поэтому MatrixGate разработал автоматический механизм: автоматическая адаптация нагрузки записи осуществляется путем включения параметра `--auto-tune`.

Этот параметр можно включить следующими способами:
- [Передача параметра --auto-tune через конфигурационный файл при запуске](/ru/doc/5.2/tools/mxgate/parameter#autotune)
- [Динамическое переключение с помощью команды mxgate set](/ru/doc/5.2/tools/mxgate/parameter#autotuneset)
- [Получение статуса настройки с помощью команды mxgate get](/ru/doc/5.2/tools/mxgate/parameter#autotunestatus)

>***Примечание!***  
Включение этой функции обеспечивает максимально эффективную производительность записи в реальном времени, но использование ресурсов сессионных слотов не обязательно будет оптимальным.

>***Примечание!***  
Если включена автоматическая настройка количества слотов и установлен [порог высокой нагрузки] (#sourcepressure), функция автоматической настройки будет работать только при превышении порога нагрузки записи.

<a name="sourcepressure"><br/></a>
## 10 mxgate Процентная квантованная нагрузка записи

mxgate поддерживает квантование нагрузки записи исходных данных (в процентах от 0 до 100%). В процессе записи данных с помощью mxgate нагрузку записи соответствующей задачи (Job) можно получить с помощью следующей команды:

$ mxgate get --source-pressure

| \/ | | | _ () / _| | | __ | |\/| |/ ` | | '| \ \/ / | / ` | / \ | | | | (| | || | | |> <| || | (_| | || / || ||_,|_|| |//_\|\,_|\_| Version: v5.2.0 Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any

public.t2 source-pressure = 27.26%

If there are multiple jobs, you can get the corresponding write load through the name of the job, or get the write load of multiple jobs at once:

$ mxgate get --source-pressure --job public.t2

| \/ | | | _ () / _| | | __ | |\/| |/ ` | | '| \ \/ / | / ` | / \ | | | | (| | || | | |> <| || | (_| | || / || ||_,|_|| |//_\|\,_|\_| Version: v5.2.0 Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any

public.t2 source-pressure = 15.73%

$ mxgate get --source-pressure

| \/ | | | _ () / _| | | __ | |\/| |/ ` | | '| \ \/ / | / ` | / \ | | | | (| | || | | |> <| || | (_| | || / || ||_,|_|| |//_\|\,_|\_| Version: v5.2.0 Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any

public.t2 source-pressure = 35.84% public.t1 source-pressure = 0%

After completing the percentage load quantization, you can use this metric to set a corresponding high water level threshold. If the data writing load at the source end exceeds the set threshold, the corresponding number will be displayed as **red**. At this time, you can manually adjust the slot number to reduce the write pressure. Of course, you can also use the [mxgate automatic slot number] (#autotune) function.

The threshold value needs to be set through the following command:

$ mxgate set --high-water-mark --job 

For example:

$ mxgate set --high-water-mark 20 --job public.t2

| \/ | | | _ () / _| | | __ | |\/| |/ ` | | '| \ \/ / | / ` | / \ | | | | (| | || | | |> <| || | (_| | || / || ||_,|_|| |//_\|\,_|\_| Version: v5.2.0 Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any

public.t2 high-water-mark = 20.00%

Get the high water level threshold of the corresponding job through the following command:

$ mxgate get --high-water-mark-get --job public.t2

| \/ | | | _ () / _| | | __ | |\/| |/ ` | | '| \ \/ / | / ` | / \ | | | | (| | || | | |> <| || | (_| | || / || ||_,|_|| |//_\|\,_|\_| Version: v5.2.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.2.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 и установите соответствующий порог высокого уровня, количество слотов не будет автоматически увеличиваться, пока нагрузка по записи задачи не превысит установленный порог высокого уровня. Даже если 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.2.0 Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any

public.t2 high-water-mark = 0.00%

Следующая →
История версий