Открыть страницу поиска
Привет, Я DocuDroid!
Открыть страницу ИИ Помощника
Оценка ИИ поиска
Спасибо за оценку нашего ИИ поиска!
Мы будем признательны, если вы поделитесь своими впечатлениями, чтобы мы могли улучшить наш ИИ поиск для вас и других читателей.
GitHub

Использование коннектора PXF File для чтения и записи данных между NFS в Greengage DB

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

Коннектор PXF File позволяет читать и записывать данные, расположенные в сетевой файловой системе (Network File System), смонтированной на хостах Greengage DB.

В этой статье описывается настройка и использование коннектора PXF File для чтения и записи данных в NFS с использованием внешних таблиц, а также приводятся практические примеры.

Перед началом работы убедитесь, что:

  • Файлы доступны пользователю gpadmin или пользователю операционной системы, запустившему процесс PXF.

  • Сетевая файловая система корректно смонтирована в одной и той же локальной точке монтирования на каждом хосте Greengage DB.

  • Создана одна или несколько конфигураций сервера PXF, как описано в разделе Конфигурирование сервера PXF для сетевой файловой системы.

Поддерживаемые типы файлов

С помощью коннектора PXF File можно производить чтение и запись данных в файлах следующих типов.

Тип файла Имя профиля Поддерживаемые операции

Однострочные текстовые значения с разделителями

file:text

Чтение, запись

Однострочные разделенные запятыми текстовые значения (CSV)

file:csv

Чтение, запись

Текстовые значения с разделителями, заключенными в кавычки

file:text:multi

Чтение

Однострочные текстовые значения фиксированной ширины

file:fixedwidth

Чтение, запись

Avro

file:avro

Чтение, запись

JSON

file:json

Чтение, запись

ORC

file:orc

Чтение, запись

Parquet

file:parquet

Чтение, запись

Создание внешней таблицы с использованием протокола PXF

Чтобы создать внешнюю таблицу Greengage DB для чтения и записи данных в NFS, используется следующий синтаксис:

CREATE [READABLE | WRITABLE] EXTERNAL TABLE <table_name>
    ( <column_name> <data_type> [, ...] | LIKE <other_table> )
    LOCATION ('pxf://<path_to_data>?PROFILE=file:<file_type>[&SERVER=<server_name>][&<custom-option>=<value>[...]]')
    FORMAT '[TEXT|CSV|CUSTOM]' (<formatting-properties>)
    [DISTRIBUTED BY (<column_name> [, ... ] ) | DISTRIBUTED RANDOMLY];
Ключевое слово Значение

<table_name>

Имя создаваемой таблицы

<column_name>

Имя создаваемого столбца

<data_type>

Тип данных создаваемого столбца

LIKE <other_table>

Указывает таблицу, из которой внешняя таблица копирует все имена столбцов, типы данных и политику распределения

<path_to_data>

Путь к каталогу или файлу в NFS. Путь трактуется как относительный к базовому пути, указанному в качестве значения свойства pxf.fs.basePath конфигурации сервера. Значение <path_to_data> не должно содержать обозначения относительных путей (например ./ или ../) или символа доллара ($)

PROFILE=file:<file_type>

Профиль указывается как пара file:<file_type>, где <file_type> обозначает один из поддерживаемых типов файлов

SERVER=<server_name>

Имя конфигурации сервера, который используется для доступа к данным. Если опция опущена, используется конфигурация сервера с именем default

<custom‑option>=<value>

Одна из опций, указываемая в строке LOCATION в зависимости от выбранного профиля. Подробнее см. в разделе Опции, формат данных и свойства форматирования

FORMAT <value>

Формат данных, принимающий значения TEXT, CSV или CUSTOM. Подробнее см. в разделе Опции, формат данных и свойства форматирования

<formatting‑properties>

Опции форматирования, поддерживаемые выбранным профилем. Подробнее см. в разделе Опции, формат данных и свойства форматирования

DISTRIBUTED BY

При загрузке данных из таблицы Greengage DB во внешнюю пишущую таблицу рекомендуется указывать ту же политику распределения или имя столбца в обеих таблицах. Это позволит избежать дополнительного перемещения данных между сегментами при выполнении операции загрузки. Более подробную информацию о распределении таблиц можно получить в статье Распределение данных

Примеры

Эти примеры демонстрируют настройку и использование коннектора PXF File для чтения и записи данных CSV в NFS с помощью внешних таблиц.

Примеры предполагают, что сетевая файловая система с точкой монтирования /mnt/extdata/pxf настроена и смонтирована на каждом хосте кластера Greengage DB.

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

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

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

Чтобы создать внешнюю таблицу с использованием протокола PXF, предварительно зарегистрируйте в БД расширение PXF, как описано в разделе Регистрация PXF в БД документации PXF:

CREATE EXTENSION pxf;

Конфигурирование сервера PXF для сетевой файловой системы

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

  1. На мастер-хосте Greengage DB войдите под пользователем gpadmin.

  2. Перейдите в каталог $PXF_BASE/servers и создайте каталог конфигурации сервера для сетевой файловой системы (например, с именем nfs):

    $ mkdir $PXF_BASE/servers/nfs

  3. Скопируйте шаблон файла конфигурации $PXF_HOME/templates/pxf-site.xml в каталог $PXF_BASE/servers/nfs:

    $ cd $PXF_BASE/servers/nfs
$ cp $PXF_HOME/templates/pxf-site.xml .

  4. В файле конфигурации требуется указать два обязательных свойства:

    • pxf.fs.basePath определяет базовый путь к общему каталогу сетевой файловой системы. Путь к файлам, указанный в выражении LOCATION команды CREATE EXTERNAL TABLE, трактуется как относительный к базовому пути.

    • pxf.service.user.impersonation управляет имперсонацией пользователей. PXF не поддерживает имперсонацию для NFS и производит доступ от имени пользователя, который запустил процесс PXF, обычно gpadmin. По этой причине имперсонация пользователей должна быть явно отключена.

    Откройте файл конфигурации в текстовом редакторе и установите требуемые значения свойств. Например, если общий каталог NFS — /mnt/extdata/pxf, установите его как значение свойства pxf.fs.basePath:

    <?xml version="1.0" encoding="UTF-8"?>
<configuration>
...
    <property>
        <name>pxf.service.user.impersonation</name>
        <value>false</value>
    </property>
    <property>
        <name>pxf.fs.basePath</name>
        <value>/mnt/extdata/pxf</value>
    </property>
...
</configuration>

  5. Синхронизируйте конфигурацию между хостами кластера Greengage DB:

    $ pxf cluster sync

Чтение CSV-файла из NFS

  1. В общем каталоге NFS создайте CSV-файл с именем customers.csv и следующим содержимым:

    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

  2. На мастер-хосте Greengage DB создайте внешнюю таблицу, ссылающуюся на файл customers.csv. В выражении LOCATION укажите профиль file:csv и конфигурацию сервера. В выражении FORMAT укажите CSV в качестве формата данных:

    CREATE EXTERNAL TABLE customers_r (
    id INTEGER,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100),
    address VARCHAR(255)
    )
    LOCATION ('pxf://customers.csv?PROFILE=file:csv&SERVER=nfs')
    FORMAT 'CSV';

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

    SELECT * FROM customers_r;

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

     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
(4 rows)

Запись CSV-файла в NFS

  1. На мастер-хосте Greengage DB создайте пишущую внешнюю таблицу, которая записывает данные в подкаталог customers общего каталога NFS. В выражении LOCATION укажите профиль file:csv и конфигурацию сервера. В выражении FORMAT укажите CSV в качестве формата данных:

    CREATE WRITABLE EXTERNAL TABLE customers_w (
    id INTEGER,
    first_name TEXT,
    last_name TEXT,
    email TEXT,
    address TEXT
    )
    LOCATION ('pxf://customers?PROFILE=file:csv&SERVER=nfs')
    FORMAT 'CSV';

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

    INSERT INTO customers_w (
     id,
     first_name,
     last_name,
     email,
     address
     ) 
VALUES (5,'Alice','Johnson','alice.johnson@example.com','10 Oak Avenue'),
       (6,'Charlie','Williams','charlie.williams@example.com','42 Maple Drive'),
       (7,'Bob','Smith','bob.smith@example.com','7 Pine Court'),
       (8,'Eve','Brown','eve.brown@example.com','12 Birch Lane');

  3. Просмотрите содержимое подкаталога customers общего каталога NFS. Список файлов должен выглядеть подобным образом:

    230-0000000016_0
230-0000000016_1
230-0000000016_2
230-0000000016_3

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

    8,Eve,Brown,eve.brown@example.com,12 Birch Lane
6,Charlie,Williams,charlie.williams@example.com,42 Maple Drive
7,Bob,Smith,bob.smith@example.com,7 Pine Court
5,Alice,Johnson,alice.johnson@example.com,10 Oak Avenue

Опции, формат данных и свойства форматирования

Опции, формат данных и свойства форматирования, указываемые при создании внешней таблицы, которая ссылается на файл в сетевой файловой системе, зависят от типа файла.

Однострочные текстовые значения и CSV

Ключевое слово Значение

IGNORE_MISSING_PATH=<boolean>

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

SKIP_HEADER_COUNT=<numlines>

Количество строк заголовка, которые необходимо пропустить в начале файла перед чтением данных. Значение по умолчанию — 0, строки не пропускаются

COMPRESSION_CODEC

Кодек сжатия, используемый при записи данных: default, bzip2, gzip или uncompressed (без сжатия). Если значение не указано (или указано uncompressed), сжатие не производится

FORMAT <value>

Формат данных: TEXT при ссылке на обычный текст с разделителями или CSV при ссылке на данные с разделителями-запятыми.

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

delimiter

Символ, использующийся в качестве разделителя полей данных. В формате CSV значение <delim_value> по умолчанию — символ запятой (,). Вы можете использовать спецпоследовательности, начинающиеся с E'', например delimiter=E'\t'

Многострочный текст

Ключевое слово Значение

IGNORE_MISSING_PATH

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

FORMAT

Для чтения многострочных текстовых данных из NFS требуется указать формат CSV

Текст фиксированной ширины

Ключевое слово Значение

NEWLINE

Если значение line_delim указано и содержит \r (CR), \r\n (CRLF) или произвольный набор символов экранирования, требуется также указать NEWLINE, выбрав в качестве значения CR, CRLF или соответствующий набор символов в байтовом формате

COMPRESSION_CODEC

Кодек сжатия, используемый при записи данных: default, bzip2, gzip или uncompressed (без сжатия). Если значение не указано (или указано uncompressed), сжатие не производится

IGNORE_MISSING_PATH

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

FORMAT 'CUSTOM'

Для чтения и записи данных в NFS используется кастомный формат с использованием встроенных кастомных функций форматирования для операций чтения (fixedwidth_in) и записи (fixedwidth_out)

<field_name>='<width>'

Имя и ширина поля данных, указываемая в символах. Поля должны быть перечислены в порядке их физического следования в файле данных. Имена полей должны совпадать с именами столбцов в команде CREATE EXTERNAL TABLE.

При чтении данных, если ширина поля меньше значения <width>, Greengage DB ожидает, что поле дополнено справа пробелами до требуемой ширины. При записи данных, если ширина поля меньше значения <width>, Greengage DB дополняет поле пробелами справа до требуемой ширины, указанной в <width>

line_delim

Указывает символ переноса строки в файле данных, по умолчанию \n (LF). Если значение указано и содержит \r (CR), \r\n (CRLF) или произвольный набор символов экранирования, требуется также указать NEWLINE, выбрав в качестве значения CR, CRLF или соответствующий набор символов в байтовом формате

Avro

Ключевое слово Значение

COLLECTION_DELIM

Символы, используемые в качестве разделителя элементов массива, ассоциативного массива или записи верхнего уровня при сопоставлении составного типа данных Avro и текстового столбца во время чтения данных. По умолчанию используется символ запятой (,)

MAPKEY_DELIM

Символы, используемые в качестве разделителя ключа и значения элемента ассоциативного массива при сопоставлении составного типа данных Avro и текстового столбца во время чтения данных. По умолчанию используется символ двоеточия (:)

RECORDKEY_DELIM

Символы, используемые в качестве разделителя имени и значения поля элемента записи при сопоставлении составного типа данных Avro и текстового столбца во время чтения данных. По умолчанию используется символ двоеточия (:)

SCHEMA

Путь к файлу схемы Avro в NFS. Путь трактуется как относительный к базовому пути, указанному в качестве значения pxf.fs.basePath в конфигурации сервера

IGNORE_MISSING_PATH

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

COMPRESSION_CODEC

Кодек сжатия, используемый при записи данных: bzip2, xz, snappy, deflate или uncompressed (без сжатия). Если значение не указано (или указано uncompressed), сжатие не производится

CODEC_LEVEL

Уровень сжатия (применяется только для кодеков deflate и xz), обеспечивающий баланс между скоростью и уровнем сжатия. Допустимые значения — от 1 (высокая скорость) до 9 (высокая степень сжатия). По умолчанию используется уровень 6

FORMAT 'CUSTOM'

Для чтения и записи данных в NFS используется кастомный формат с использованием встроенных кастомных функций форматирования для операций чтения (pxfwritable_import) и записи (pxfwritable_export)

JSON

Ключевое слово Значение

IDENTIFIER=<value>

Указывается только при обращении к данным JSON с многострочными полями. Значение <value> обозначает имя поля, чей родительский JSON-объект должен быть возвращен в качестве кортежа.

Если во вложенном объекте присутствует поле с тем же именем, что указано в качестве IDENTIFIER, PXF может вернуть неверные данные. Вы можете обойти этот пограничный случай, выполнив сжатие JSON-файла, а затем его чтение с помощью PXF

SPLIT_BY_FILE=<boolean>

Определяет, как разделять файлы, указанные в <path_to_data>. Значение по умолчанию — false: PXF при этом создает несколько разделов для каждого файла и обрабатывает их параллельно. Если установлено значение true, PXF создает и обрабатывает один раздел на файл

IGNORE_MISSING_PATH=<boolean>

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

ROOT=<value>

При записи данных в один объект указывает имя атрибута корневого уровня

COMPRESSION_CODEC

Кодек сжатия, используемый при записи данных: default, bzip2, gzip или uncompressed (без сжатия). Если значение не указано (или указано uncompressed), сжатие не производится.

Если кодек сжатия указан, к записанным файлам применяется следующая схема именования: <базовое имя>.<тип файла JSON>.<расширение сжатия>, например customers.jsonl.gz

FORMAT 'CUSTOM'

Для чтения и записи данных в NFS используется кастомный формат с использованием встроенных кастомных функций форматирования для операций чтения (pxfwritable_import) и записи (pxfwritable_export)

ORC

Ключевое слово Значение

IGNORE_MISSING_PATH

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

MAP_BY_POSITION

Указывает, должны ли столбцы сопоставляться по их порядку. Значение по умолчанию — false: PXF сопоставляет столбец ORC столбцу Greengage DB по имени

COMPRESSION_CODEC

Кодек сжатия, используемый при записи данных: lz4, lzo, zstd, snappy, zlib или none.

Если сжатия данных не требуется, следует явно указать значение none. В противном случае выполняется сжатие с помощью кодека Zlib

FORMAT 'CUSTOM'

Для чтения и записи данных в NFS используется кастомный формат с использованием встроенных кастомных функций форматирования для операций чтения (pxfwritable_import) и записи (pxfwritable_export)

Parquet

Ключевое слово Значение

IGNORE_MISSING_PATH

Действие, которое необходимо выполнить, если <path_to_data> отсутствует или указан неверно. Если установлено значение false (по умолчанию), возвращается ошибка. Если установлено значение true, PXF игнорирует ошибку и возвращает пустой фрагмент. Применяется только для читающих внешних таблиц; в случае пишущих внешних таблиц игнорируется

COMPRESSION_CODEC

Кодек сжатия, используемый при записи данных: snappy, gzip, lzo или uncompressed (без сжатия).

Если сжатия данных не требуется, следует явно указать значение uncompressed. В противном случае выполняется сжатие с помощью кодека Snappy

ROWGROUP_SIZE

Размер (в байтах) группы строк, которая обеспечивает логическое разбиение данных на строки. Размер группы строк по умолчанию составляет 8 * 1024 * 1024 байт

PAGE_SIZE

Размер (в байтах) страницы, которая делит группы строк в столбце на фрагменты столбцов. Размер страницы по умолчанию составляет 1 * 1024 * 1024 байт

ENABLE_DICTIONARY

Указывает, следует ли включать словарное кодирование. Значение по умолчанию — true: словарное кодирование включено при записи файлов Parquet

DICTIONARY_PAGE_SIZE

Когда словарное кодирование включено, для каждого столбца в каждой группе строк определяется единая словарная страница. Параметр DICTIONARY_PAGE_SIZE аналогичен PAGE_SIZE, но задается специально для словаря. Размер словарной страницы по умолчанию составляет 1 * 1024 * 1024 байт

PARQUET_VERSION

Версия Parquet; поддерживаются значения v1 (по умолчанию) и v2

SCHEMA

Путь к файлу схемы Parquet в NFS. Путь трактуется как относительный к базовому пути, указанному в качестве значения pxf.fs.basePath в конфигурации сервера

FORMAT 'CUSTOM'

Для чтения и записи данных в NFS используется кастомный формат с использованием встроенных кастомных функций форматирования для операций чтения (pxfwritable_import) и записи (pxfwritable_export)
Предыдущая
Текст фиксированной ширины
Следующая
Iceberg