Использование gpfdist

Антон Монаков

Contents

Обзор синтаксиса
Запуск gpfdist
- Настройка SSL
- Примеры
Остановка gpfdist
Создание внешних таблиц с помощью GPFDIST / GPFDISTS
- Примеры
Рекомендации по улучшению производительности

Параллельный файловый сервер gpfdist (Greenplum Parallel File Server) — это утилита для параллельного распространения файлов. При использовании gpfdist все сегменты Greengage DB могут осуществлять параллельное чтение и запись данных внешних таблиц.

В случае readable-таблиц gpfdist читает данные из файлов указанного каталога, упаковывает их в блок и отправляет блок в ответ на запрос сегмента Greengage DB. Сегменты распаковывают полученные данные и распределяют их согласно политике распределения внешней таблицы. В случае writable-таблиц сегменты отправляют блоки данных в запросе к gpfdist, а gpfdist записывает данные во внешние файлы.

Настроив gpfdist-сервер с помощью специального YAML-файла, можно также производить трансформацию внешних данных из одного из поддерживаемых текстовых форматов в иной формат, например, XML или JSON.

Для доступа к данным с помощью gpfdist в выражении LOCATION команды CREATE EXTERNAL TABLE используйте протокол GPFDIST/GPFDISTS. Более подробную информацию можно получить в разделе Создание внешних таблиц с помощью GPFDIST / GPFDISTS.

Синтаксис команды gpfdist в общем виде выглядит следующим образом:

gpfdist [-d <directory>] [-p <http_port>] |-P <last_http_port>
    [-l <log_file>] [-t <timeout>] [-S] [-w <time>]
    [-v | -V] [-m <max_length>] [--ssl <certificate_path>]
    [-k <seconds>] [--compress] [--multi_thread <number_of_threads>]
    [-I <input_transformation_name>] [-O <output_transformation_name>]
    [-c <config.yaml>]

gpfdist -? | --help

gpfdist --version

Опция Описание

Опция	Описание
-d <directory>	Каталог, из которого `gpfdist` осуществляет загрузку файлов для readable-таблиц или запись файлов для writable-таблиц. Если опция не указана, выбирается каталог, откуда запущена утилита `gpfdist`
-p <http_port>	HTTP-порт, на котором осуществляется загрузка файлов. По умолчанию используется порт `8080`
-P <last_http_port>	Последний HTTP-порт в диапазоне портов (от `http_port` до `last_http_port`), которые `gpfdist` пытается использовать для загрузки файлов. Загрузка будет производиться с первого успешно привязанного порта
-l <log_file>	Полный путь или имя log-файла для логирования сообщений
-t <timeout>	Допустимое время ожидания соединения с процессом `gpfdist`, от 2 до 7200 секунд (2 часа). Значение можно увеличить при большой загруженности сети. Время ожидания по умолчанию — 5 секунд
-S	Открывает файл для синхронного ввода-вывода с флагом `O_SYNC`. Любые записи в дескриптор выходного файла блокируют `gpfdist` до тех пор, пока данные не будут физически записаны на дисковое устройство
-w <time>	Время ожидания перед закрытием файла, от 0 (время ожидания отсутствует) до 7200 секунд (2 часа). На хостах Greengage DB с несколькими сегментами может наблюдаться задержка при записи в файл данных с нескольких сегментов. Данная опция используется для того, чтобы все данные могли быть успешно записаны в файл до его закрытия
-v	Отображает подробный вывод работы утилиты (сообщения о ходе выполнения и статусе операции)
-V	Отображает очень подробный вывод работы утилиты (все сообщения, генерируемые `gpfdist`)
-m <max_length>	Максимально допустимая длина строки данных в байтах, по умолчанию `32768`. Используйте это значение, если данные содержат очень широкие строки (или при возникновении сообщения об ошибке `line too long`). Не используйте это значение без необходимости, так как это увеличивает потребление ресурсов. Допустимый диапазон: от 32 КБ до 256 МБ. На системах семейства Windows верхний предел составляет 1 МБ
--ssl <certificate_path>	Включает SSL-шифрование данных, передаваемых `gpfdist`. Если опция включена, работа с данными файлового сервера осуществляется только по протоколу GPFDISTS. Корневой каталог (/) нельзя указывать в качестве пути к сертификатам (`certificate_path`). Более подробную информацию о создании внешних таблиц с помощью протокола GPFDISTS можно получить в разделе Создание внешних таблиц с помощью GPFDIST / GPFDISTS
-k <seconds>	Время ожидания перед очисткой сессии при отсутствии POST-запросов от сегментов, от 300 до 86400 секунд (24 часа). Значение можно увеличить при большой загруженности сети. Время ожидания по умолчанию — 300 секунд
--compress	Включает сжатие данных при передаче. `gpfdist` использует алгоритм сжатия Zstandard (zstd). Опция недоступна для операционных систем семейства Windows
--multi_threads <num_threads>	Устанавливает максимальное количество потоков, до 256, используемых `gpfdist` для распараллеливания передачи данных. Если опция включена, автоматически включается и сжатие данных. Опция недоступна для операционных систем семейства Windows
-I <input_transformation_name>	Устанавливает одну из входных трансформаций, описанных в файле конфигурации трансформации (`-c`), в качестве трансформации по умолчанию. Выбранная трансформация применяется ко всем записываемым файлам. Не используется, если трансформация указана на уровне таблицы. По умолчанию трансформация не применяется. Более подробную информацию можно получить в разделе Загрузка с помощью gpfdist
-O <output_transformation_name>	Устанавливает одну из выходных трансформаций, описанных в файле конфигурации трансформации (`-c`), в качестве трансформации по умолчанию. Выбранная трансформация применяется ко всем записываемым файлам. Не используется, если трансформация указана на уровне таблицы. По умолчанию трансформация не применяется. Более подробную информацию можно получить в разделе Загрузка с помощью gpfdist
-c <config.yaml>	Указывает YAML-файл, определяющий набор правил для выбора трансформации данных при загрузке или распаковке. В файле конфигурации трансформации может содержаться описание нескольких трансформаций; выбрать трансформацию по умолчанию можно с помощью опций `gpfdist` `-I` и `-O`. Опция `c` недоступна для операционных систем семейства Windows. Более подробную информацию можно получить в разделе Файл конфигурации трансформации
-?	Отображает справочную информацию `gpfdist`
--version	Отображает версию `gpfdist`

-d <directory>

Каталог, из которого gpfdist осуществляет загрузку файлов для readable-таблиц или запись файлов для writable-таблиц.

Если опция не указана, выбирается каталог, откуда запущена утилита gpfdist

-p <http_port>

HTTP-порт, на котором осуществляется загрузка файлов.

По умолчанию используется порт 8080

-P <last_http_port>

Последний HTTP-порт в диапазоне портов (от http_port до last_http_port), которые gpfdist пытается использовать для загрузки файлов. Загрузка будет производиться с первого успешно привязанного порта

-l <log_file>

Полный путь или имя log-файла для логирования сообщений

-t <timeout>

Допустимое время ожидания соединения с процессом gpfdist, от 2 до 7200 секунд (2 часа). Значение можно увеличить при большой загруженности сети.

Время ожидания по умолчанию — 5 секунд

-S

Открывает файл для синхронного ввода-вывода с флагом O_SYNC. Любые записи в дескриптор выходного файла блокируют gpfdist до тех пор, пока данные не будут физически записаны на дисковое устройство

-w <time>

Время ожидания перед закрытием файла, от 0 (время ожидания отсутствует) до 7200 секунд (2 часа).

На хостах Greengage DB с несколькими сегментами может наблюдаться задержка при записи в файл данных с нескольких сегментов. Данная опция используется для того, чтобы все данные могли быть успешно записаны в файл до его закрытия

-v

Отображает подробный вывод работы утилиты (сообщения о ходе выполнения и статусе операции)

-V

Отображает очень подробный вывод работы утилиты (все сообщения, генерируемые gpfdist)

-m <max_length>

Максимально допустимая длина строки данных в байтах, по умолчанию 32768. Используйте это значение, если данные содержат очень широкие строки (или при возникновении сообщения об ошибке line too long). Не используйте это значение без необходимости, так как это увеличивает потребление ресурсов.

Допустимый диапазон: от 32 КБ до 256 МБ. На системах семейства Windows верхний предел составляет 1 МБ

--ssl <certificate_path>

Включает SSL-шифрование данных, передаваемых gpfdist.

Если опция включена, работа с данными файлового сервера осуществляется только по протоколу GPFDISTS. Корневой каталог (/) нельзя указывать в качестве пути к сертификатам (certificate_path). Более подробную информацию о создании внешних таблиц с помощью протокола GPFDISTS можно получить в разделе Создание внешних таблиц с помощью GPFDIST / GPFDISTS

-k <seconds>

Время ожидания перед очисткой сессии при отсутствии POST-запросов от сегментов, от 300 до 86400 секунд (24 часа). Значение можно увеличить при большой загруженности сети.

Время ожидания по умолчанию — 300 секунд

--compress

Включает сжатие данных при передаче. gpfdist использует алгоритм сжатия Zstandard (zstd). Опция недоступна для операционных систем семейства Windows

--multi_threads <num_threads>

Устанавливает максимальное количество потоков, до 256, используемых gpfdist для распараллеливания передачи данных. Если опция включена, автоматически включается и сжатие данных. Опция недоступна для операционных систем семейства Windows

-I <input_transformation_name>

Устанавливает одну из входных трансформаций, описанных в файле конфигурации трансформации (-c), в качестве трансформации по умолчанию. Выбранная трансформация применяется ко всем записываемым файлам. Не используется, если трансформация указана на уровне таблицы. По умолчанию трансформация не применяется.

Более подробную информацию можно получить в разделе Загрузка с помощью gpfdist

-O <output_transformation_name>

Устанавливает одну из выходных трансформаций, описанных в файле конфигурации трансформации (-c), в качестве трансформации по умолчанию. Выбранная трансформация применяется ко всем записываемым файлам. Не используется, если трансформация указана на уровне таблицы. По умолчанию трансформация не применяется.

Более подробную информацию можно получить в разделе Загрузка с помощью gpfdist

-c <config.yaml>

Указывает YAML-файл, определяющий набор правил для выбора трансформации данных при загрузке или распаковке. В файле конфигурации трансформации может содержаться описание нескольких трансформаций; выбрать трансформацию по умолчанию можно с помощью опций gpfdist -I и -O. Опция c недоступна для операционных систем семейства Windows.

Более подробную информацию можно получить в разделе Файл конфигурации трансформации

Отображает справочную информацию gpfdist

--version

Отображает версию gpfdist

Утилита gpfdist находится в каталоге $GPHOME/bin на мастер-хосте и на каждом сегмент-хосте Greengage DB. Для установки утилиты на произвольный хост скопируйте ее в удобное место и обновите переменную среды PATH. Чтобы не снижать производительность при выполнении запросов, gpfdist обычно запускается на машинах ETL, а не на хостах, где установлен Greengage DB. При запуске нескольких экземпляров gpfdist на одном ETL-хосте используйте разные каталоги и порты для каждого экземпляра.

ПРИМЕЧАНИЕ

Утилиты gpfdist и gpload совместимы только с мажорной версией Greengage DB, в комплекте с которой они поставляются (например, 6.x).

Для создания внешних таблиц с помощью протокола GPFDISTS требуется настроить SSL-соединение между Greengage DB и файловым сервером.

Сгенерируйте сертификат для файлового сервера, как описано в разделе Создание сертификатов. Сгенерированный сертификат может храниться в любом удобном месте на файловом сервере. Его местоположение передается в опции --ssl при запуске утилиты gpfdist.
Сгенерируйте сертификат для клиента, как описано в разделе Создание сертификата для клиента. Сохраните следующие сертификаты клиента в подкаталоге gpfdists каталога данных на каждом сегменте (например, /data1/primary/gpseg0/gpfdists) каждого сегмент-хоста:
- client.crt — файл сертификата клиента;
- client.key — файл закрытого ключа клиента;
- root.crt — файл корневого центра сертификации.

ВАЖНО

Закрытые ключи клиента и сервера (server.key и client.key) не должны быть защищены с помощью парольной фразы.

Обратите внимание, что GPFDISTS реализует безопасность SSL в клиент-серверной схеме со следующими атрибутами и ограничениями:

Необходимы клиентские сертификаты.
Многоязычные сертификаты не поддерживаются.
Список отозванных сертификатов (Certificate Revocation List, CRL) не поддерживается.
Требуется TLS версии 1.2 и выше.
Поддерживается пересогласование (renegotiation) SSL.

С помощью параметра конфигурации сервера verify_gpfdists_cert можно включить аутентификацию по SSL-сертификату при обращении Greengage DB к gpfdist. Для проверки соединения между Greengage DB и файловым сервером параметру можно присвоить значение false. В этом случае игнорируются следующие ошибки SSL:

Самоподписанный SSL-сертификат, используемый gpfdist, не является доверенным для Greengage DB.
Имя хоста в SSL-сертификате не совпадает с именем хоста, на котором запущен gpfdist.

ВАЖНО

Отключение аутентификации по SSL-сертификату несет риск для безопасности, так как не производится проверка SSL-сертификата gpfdist.

В данных примерах иллюстрируются несколько частых сценариев запуска gpfdist.

Запуск gpfdist в фоновом режиме (&), прослушивание порта по умолчанию (8080) и загрузка файлов из текущего каталога:
```
$ gpfdist &
```
Запуск gpfdist в фоновом режиме (&), прослушивание порта 8801 и загрузка файлов из каталога /home/gpadmin/external_files:
```
$ gpfdist -p 8801 -d /home/gpadmin/external_files &
```
Запуск gpfdist в фоновом режиме (&), прослушивание порта по умолчанию (8080), загрузка файлов из текущего каталога и логирование сообщений и ошибок в файл gpfdist_log:
```
$ gpfdist -l /home/gpadmin/gpfdist_log &
```
Запуск gpfdist в режиме SSL с каталогом сертификатов /home/gpadmin/certs, прослушивание порта port 8811 и загрузка файлов из каталога /home/gpadmin/external_files:
```
$ gpfdist --ssl /home/gpadmin/certs -p 8811 -d /home/gpadmin/external_files
```
Запуск gpfdist в режиме многопоточной передачи данных (четыре потока), прослушивание порта по умолчанию (8080) и загрузка файлов из текущего каталога:
```
$ gpfdist --multi_thread 4
```

Вывод команд должен выглядеть следующим образом:

Без использования SSL

INFO Before opening listening sockets - following listening sockets are available:
INFO IPV6 socket: [::]:8811
INFO IPV4 socket: 0.0.0.0:8811
INFO Trying to open listening socket:
INFO IPV6 socket: [::]:8811
INFO Opening listening socket succeeded
INFO Trying to open listening socket:
INFO IPV4 socket: 0.0.0.0:8811
INFO Opening listening socket succeeded
Serving HTTP on port 8811, directory /home/gpadmin/external_files

С использованием SSL

INFO Before opening listening sockets - following listening sockets are available:
INFO IPV6 socket: [::]:8811
INFO IPV4 socket: 0.0.0.0:8811
INFO Trying to open listening socket:
INFO IPV6 socket: [::]:8811
INFO Opening listening socket succeeded
INFO Trying to open listening socket:
INFO IPV4 socket: 0.0.0.0:8811
INFO Opening listening socket succeeded
Serving HTTPS on port 8811, directory /home/gpadmin/external_files

Для остановки gpfdist, запущенного в фоновом режиме:

Найдите ID процесса gpfdist:

$ ps -ef | grep gpfdist

Вывод должен выглядеть следующим образом:

gpadmin    12687       1  0 Apr07 ?        gpfdist --ssl /home/gpadmin/certs -p 8811 -d /tmp
gpadmin    41509   41470  0 13:00 pts/3    gpfdist
gpadmin    41521   41510  0 13:01 pts/3    grep --color=auto gpfdist

Остановите необходимый процесс. В данном примере ID процесса — 41509:
```
$ kill 41509
```

Для создания внешней таблицы с помощью протокола GPFDIST / GPFDISTS в команде CREATE EXTERNAL TABLE используйте выражения LOCATION и FORMAT следующим образом:

GPFDIST

CREATE [[READABLE] | WRITABLE] EXTERNAL TABLE <table_name> ( ... )
    LOCATION ('gpfdist://<host>[:<port>]/<path>/<file>')
    FORMAT 'TEXT' | 'CSV' | 'CUSTOM';

GPFDISTS

CREATE [[READABLE] | WRITABLE] EXTERNAL TABLE <table_name> ( ... )
    LOCATION ('gpfdists://<host>[:<port>]/<path>/<file>')
    FORMAT 'TEXT' | 'CSV' | 'CUSTOM';

В выражении LOCATION укажите URI для доступа к файлам: имя файлового сервера (<host>), порт (<port>) и путь к файлу относительно каталога, в которой запущен gpfdist (<path>/<file>). При использовании нескольких gpfdist-серверов можно указать несколько URI. Для указания нескольких файлов можно использовать подстановочные знаки (wildcards), например * или []. Утилита gpfdist автоматически распаковывает файлы .gz, .bz2, и .zst во время чтения данных и упаковывает их во время записи.

ПРИМЕЧАНИЕ

Сжатие и распаковка не поддерживаются при запуске gpfdist на операционных системах семейства Windows.

В выражении FORMAT укажите формат данных.

В данных примера иллюстрируется создание внешних таблиц с помощью протоколов GPFDIST / GPFDISTS.

Предварительные требования

Для выполнения примеров из этого раздела подключитесь к мастер-хосту Greengage DB как gpadmin с помощью psql, как описано в статье Подключение к Greengage DB с использованием psql. Затем создайте тестовую базу данных customers и подключитесь к ней.

DROP DATABASE IF EXISTS customers;
CREATE DATABASE customers;
\c customers

В этом примере создается readable-таблица customers, данные в которую загружаются из двух файлов, расположенных в каталоге /tmp на файловом сервере fs.

В каталоге /tmp хоста fs создайте два файла с исходными данными:

Файл customers.csv.gz, сжатый с помощью gzip:

#!/bin/bash

cat > customers.csv <<EOF
id,first_name,last_name,email,address
1,John,Doe,john.doe@example.com,123 Elm Street
2,Jane,Smith,jane.smith@example.com,456 Oak Street
EOF

gzip customers.csv

Обычный файл customers.csv:

#!/bin/bash

cat > /tmp/customers.csv <<EOF
id,first_name,last_name,email,address
3,Bob,Brown,bob.brown@example.com,789 Pine Street
4,Rob,Stuart,rob.stuart@example.com,119 Willow Street
EOF

На хосте fs запустите утилиту gpfdist из каталога /tmp:
```
$ gpfdist -p 8811 -d /tmp/ &
```
На мастер-хосте запустите команду CREATE EXTERNAL TABLE. В выражении LOCATION укажите имя хоста файлового сервера (fs) и используйте подстановочный знак *, чтобы указать, что чтение будет осуществляться из двух файлов. В выражении FORMAT укажите CSV в качестве формата данных и включите пропуск заголовка (HEADER):
```
CREATE EXTERNAL TABLE customers (
    id INTEGER,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100),
    address VARCHAR(255)
)
    LOCATION ('gpfdist://fs:8811/customers.csv*')
    FORMAT 'CSV' (HEADER);
```

Выполните запрос к созданной таблице:

SELECT * FROM customers;

Вывод должен выглядеть следующим образом:

 id | first_name | last_name |         email          |      address
----+------------+-----------+------------------------+-------------------
  1 | John       | Doe       | john.doe@example.com   | 123 Elm Street
  2 | Jane       | Smith     | jane.smith@example.com | 456 Oak Street
  3 | Bob        | Brown     | bob.brown@example.com  | 789 Pine Street
  4 | Rob        | Stuart    | rob.stuart@example.com | 119 Willow Street

В данном примере создается writable-таблица orders, содержимое которой будет выгружено в файл orders.csv. Файл будет создан автоматически в каталоге /tmp на файловом сервере fs.

На файловом сервере fs запустите утилиту gpfdist из каталога /tmp, передав в опции --ssl ~/certs местоположение сертификатов и тем самым включив соединение по протоколу GPFDISTS:
```
$ gpfdist --ssl ~/certs -p 8811 -d /tmp/ &
```
На мастер-хосте запустите команду CREATE WRITABLE EXTERNAL TABLE. В выражении LOCATION укажите имя хоста файлового сервера (fs). В выражении FORMAT укажите CSV в качестве формата данных создаваемого файла orders.csv:
```
CREATE WRITABLE EXTERNAL TABLE orders (
    id INTEGER,
    total NUMERIC(10,2),
    status VARCHAR(50)
)
    LOCATION ('gpfdists://fs:8811/orders.csv')
    FORMAT 'CSV';
```

Вставьте данные в созданную таблицу:

INSERT INTO orders (customer_id, total, status)
VALUES (1, 999.99, 'Pending'),
       (2, 499.99, 'Shipped'),
       (3, 299.99, 'Delivered');

Проверьте содержимое созданного файла orders.csv:
```
$ cat /tmp/orders.csv
```
Содержимое должно выглядеть следующим образом:
```
1,999.99,Pending
2,499.99,Shipped
3,299.99,Delivered
```

Утилиту gpfdist можно одновременно запускать на нескольких хостах, а также запускать несколько экземпляров gpfdist на одном хосте. Это позволяет размещать gpfdist-сервера, задействуя всю доступную пропускную способность сети и параллелизм Greengage DB, и обеспечивает максимальную скорость загрузки и выгрузки данных.

Используйте все доступные сетевые интерфейсы ETL-хоста. Запустите по экземпляру gpfdist на каждый сетевой интерфейс на ETL-хосте и используйте имя хоста каждого сетевого адаптера (NIC) в выражении LOCATION команды CREATE EXTERNAL TABLE.
Разделите исходные данные равномерно по количеству запущенных на ETL-хосте экземпляров gpfdist. Например, при использовании ETL-системы с двумя сетевыми адаптерами запустите два экземпляра gpfdist (по одному на адаптер) для оптимизации скорости загрузки и разделите исходные данные внешней таблицы поровну между двумя серверами gpfdist.
Используйте символ вертикальной черты (|) в качестве разделителя полей исходных данных. Greengage DB заключает в одинарные или двойные кавычки все значения, разделенные запятой. gpfdist при разборе строк, в свою очередь, убирает кавычки. Используя вертикальную черту, можно избежать этого шага, улучшив тем самым производительность.
При использовании сжатия (т.е. при включении опции compress) gpfdist передает больший объем данных при меньшей загрузке сети, однако сжатие требует значительных вычислительных ресурсов процессора и может потенциально увеличить нагрузку на кластер.
При использовании многопоточности (т.е. при включении опции multi_threads) может уменьшиться время, затраченное на сжатие данных. Это увеличивает скорость передачи и снижает нагрузку на сеть.
С помощью параметра gp_external_max_segs конфигурации сервера в файле postgresql.conf можно установить количество сегментов, которые могут одновременно обращаться к экземпляру gpfdist (по умолчанию 64). Таким образом, можно использовать часть сегментов для работы с внешними данными, а остальные — для выполнения прочих задач СУБД.

Обзор

Использование gpload

Использование gpfdist

Обзор синтаксиса

Запуск gpfdist

Настройка SSL

Примеры

Остановка gpfdist

Создание внешних таблиц с помощью GPFDIST / GPFDISTS

Примеры

Readable-таблица с помощью GPFDIST

Writable-таблица с помощью GPFDISTS

Рекомендации по улучшению производительности