Модуль прямой загрузки данных QDL

Модуль прямой загрузки данных (Quantum Direct Loader, QDL) - утилита, позволяющая осуществить загрузку из файла формата CSV в таблицу формата QHB согласно конфигурации. Скорость работы существенно превосходит INSERT и COPY за счет использования оптимизированного многопоточного кода, отсутствия блокировок таблицы и обхода транзакционного ядра.

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

ТипыНазвания
Целочисленныеsmallint, int2, integer, int4, int, bigint, int8
Числовые с плавающей запятойfloat4, real, float8, double precision
Текстовыеcharacter, char, varchar, character varying, text
Числа с указанной точностьюdecimal, numeric, dec
Логическиеbool, boolean
Идентификаторыuuid
Временныеtimestamp, date

Примечание.
В текущей версии QDL допускается использование значений NaN (Not a Number) в таких типах данных, как float (числовые с плавающей запятой) и numeric (числа с указанной точностью). В дополнение к обычным числовым значениям и NaN, float также имеют специальные значения: Infinity и -Infinity. Обратите внимание, что все значения, находящиеся в файле формата CSV, не заключаются в кавычки.

Идентификаторы UUID записываются в виде последовательности шестнадцатеричных цифр в нижнем регистре, разделенных знаками минуса на несколько групп, в таком порядке: группа из 8 цифр, за ней три группы из 4 цифр и наконец группа из 12 цифр, что в сумме составляет 32 цифры. Пример UUID в этом стандартном виде: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11. Временные типы поддерживают такие специальные значения как infinity, -infinity и epoch.

Синтаксис

ПРИМЕНЕНИЕ:
    qdl <SUBCOMMAND>

ФЛАГИ:
    -h, --help       Выводит справочную информацию
    -V, --version    Выводит информацию о версии

СУБКОМАНДЫ:
    create_table     Создает скрипт SQL для создания таблицы
    help             Выводит данное сообщение или справку по заданным субкомандам
    insert_values    Заполняет файл с таблицей значениями
    validate         Проверяет правильность файла CSV с данными

Команда create_table

Генерирует SQL-скрипт, создающий таблицу СУБД согласно конфигурации, а также заполняет ее первыми тремя кортежами CSV-таблицы. Это требуется для создания структуры таблицы, которая будет заполнена данными. Также это позволяет нам получить пути расположения файлов и их названия (OID, требуемый для генерации командой insert_values).

ПРИМЕНЕНИЕ:
    qdl create_table [ФЛАГИ] --config <config> --data <data>

ФЛАГИ:
    -h, --help       Выводит справочную информацию
    -V, --version    Выводит информацию о версии
    -v, --verbose    Вывод отладки отображения

ПАРАМЕТРЫ:
    -c, --config <config>    Путь к файлу конфигурации
    -d, --data <data>        Путь к исходным данным. Используйте '-', чтобы читать из stdin

Примечание.
В формате CSV все символы являются значимыми. Значение в таблице, дополненное пробелами или любыми другими символами, кроме DELIMITER, будет включать эти символы. Это может приводить к ошибкам при заполнении таблицы данными из системы, дополняющей строки CSV пробельными символами до некоторой фиксированной ширины. В случае возникновения такой проблемы необходимо обработать файл CSV и удалить из него замыкающие пробельные символы, прежде чем загружать данные из него в QHB.

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

qdl create_table \
  --config config.yml \
  --data data.csv

Команда insert_values

Производит загрузку из файла в формате CSV в таблицу формата, используемого QHB. Данная команда выполняется многопоточно; количество ядер, отводимое под параллельную обработку, указывается в файле конфигурации.
Также рекомендуется предварительно удостовериться, что версия компоновки страницы QHB равна 4. Сделать это можно, например, при помощи расширения pageinspect::page_header.

ПРИМЕНЕНИЕ:
    qdl insert_values [ФЛАГИ] --config <config> --data <data> --out-dir <out-dir>
ФЛАГИ:
    -h, --help       Выводит справочную информацию
    -V, --version    Выводит информацию о версии
    -v, --verbose    Вывод отладки отображения

ПАРАМЕТРЫ:
    -c, --config <config>      Путь к файлу конфигурации
    -d, --data <data>          Путь к исходным данным. Используйте '-', чтобы читать из stdin
    -o, --out-dir <out-dir>    Выходной каталог
ОПЦИИ:
    -C, --cdc-info <out-dir>   Выходной каталог для `qdl-cdc.info` файла (корень PGDATA)

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

qdl insert_values \
  --config config.yml \
  --data data.csv \
  --out-dir output/

Команда validate

Проверяет логическую целостность CSV-файла и согласованность структуры данных с файлом конфигурации, сигнализируя об ошибках соответствующим кодом возврата. Сообщение об успехе выводится только в случае, если был активирован флаг --verbose, в противном случае выполнение этой команды не сопровождается выводом сообщений в консоль.

ПРИМЕНЕНИЕ:
    qdl validate [ФЛАГИ] --config <config> --data <data>

ФЛАГИ:
    -h, --help       Выводит справочную информацию
    -V, --version    Выводит информацию о версии
    -v, --verbose    Вывод отладки отображения

ПАРАМЕТРЫ:
    -c, --config <config>    Путь к файлу конфигурации
    -d, --data <data>        Путь к исходным данным. Используйте '-', чтобы читать из stdin

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

qdl validate \
  --config config.yml \
  --data data.csv

Файл конфигурации

Файл конфигурации имеет следующие партиции:

  1. general — базовая конфигурация приложения. Содержит поля threads (целочисленное) и chunk_size (целочисленное, необязательное). Первое ответственно за количество потоков-обработчиков сырых данных. Второе ответственно за размер внутреннего буфера передачи данных; данный параметр может меняться с целью оптимизации в нестандартных аппаратных конфигурациях.
  2. input — конфигурация входных данных. Содержит поля path (путь), encoding (строковое) и delimiter (строковое, необязательное). Первое — путь до входного файла, второе — кодировка, третье — разделитель столбцов для входных форматов, удобочитаемых для пользователя.
  3. output — конфигурация выходных данных. Содержит поля segment_size (целочисленное, необязательное) и oid (целочисленное). Первое — максимальное количество страниц в сегменте базы данных, второе — идентификатор объекта, который составит часть пути до сегментов.
  4. table — конфигурация таблицы. Содержит поля name (строковое) и fields (повторяющиеся field). Первое — имя таблицы, второе — описание каждого из полей (например, field_1 : varchar и необязательная пометка [nullable]).

Пример конфигурации:

# Конфигурация системы:
general:
    # Количество потоков, выделяемых для анализа и сериализации строк.
    # Обратите внимание, что помимо этих потоков обязательно выделяются еще два:
    # поток чтения и поток записи в файл.
    threads: 2

# Конфигурация исходных данных:
input:
    # Кодировка:
    encoding: "utf8"
    # Разделитель столбцов для CSV:
    delimiter: ";"

# Конфигурация получаемых данных:
output:
    # Идентификатор объекта. Определяет целочисленный идентификатор для группы файлов целевой таблицы.
    oid: 16385

# Конфигурация целевой таблицы:
table:
    # Имя таблицы. Требуется для *generate_sql*, чтобы задать имя создаваемой таблицы.
    name: "t_qdl"
    # Колонки в формате "имя": "тип"
    fields:
        id : integer
        social_id : integer [nullable]
        first_name : varchar
        last_name : varchar
        city : varchar (30)
        profession : varchar (30) [nullable]
        salary : double precision
        description : varchar [nullable]

Сценарий использования

ВНИМАНИЕ. Во избежание проблем с правами доступа, все последующие операции требуется проводить от имени пользователя, который запускает экземпляр базы данных.

ШАГ 0 (необязательный): qdl validate --config config.yml --data data.csv — валидируем CSV файл, проверяем на согласованность с конфигурацией. Это может сэкономить большое количество времени в случаях, когда мы конвертируем CSV-файл большого объема, так как если в ходе работы функции insert_values будет обнаружена ошибка, ее выполнение придется повторить после исправления причин ее возникновения.

ШАГ 1: qdl create_table --config config.yml --data data.csv — создаем SQL-скрипт создания таблицы, в которую мы хотим загрузить данные, а впоследствии использовать ее в СУБД. Также этот скрипт получает OID (идентификатор объекта; потребуется для файла конфигурации insert_values) и пути файлов базы данных. Эти операции могут быть произведены вручную, но во избежание возможных ошибок рекомендуется использовать скрипт.

ШАГ 2: Исполнение SQL-скрипта. OID, полученный в ходе выполнения, требуется разместить в файле конфигурации config.yml.

ШАГ 3: qdl insert_values --config config.yml --data data.csv --out-dir ./output_dir/ — загружаем таблицу. Этот процесс может занять значительное время, в зависимости от объема загружаемых данных. Потоки, выполняющие чтение/конвертацию/запись, имеют определенные названия; это позволит системному администратору оценить загруженность каждого отдельно взятого потока ядра и определить их количеством таким образом, чтобы добиться оптимальной производительности. Также нужно заметить, что внутренние буфера qdl не имеют ограничения размера, а значит, при очень медленной записи на диск возможна ситуация, когда эти буфера займут всю оперативную память.

Важно
Если вы используете CDC для создания инкрементальных резервных копий, то следует указать опцию -C, --cdc-info <out-dir> для генерирования информационного файла для CDC, чтобы сохранить консистентность данных в резервных копиях. Этот файл должен лежать в корне PGDATA. После перемещения этого файла в корень необходимо вызвать SELECT qcdc_attach_info() для применения изменений. После этого этот файл удалится автоматически. Если вы используете QDL несколько раз, то опция -C, --cdc-info <out-dir> должна совпадать для всех запусков, иначе резервная копия будет неконсистентной, либо выполняйте SELECT qcdc_attach_info() каждый раз после загрузки данных в базу!

ШАГ 4: Заменяем файлы СУБД сгенерированными при помощи qdl — копируем файлы при помощи команд операционной системы. После этого нужно выполнить переподключение базы данных на вновь сгенерированные файлы; для этого можно выполнить перезагрузку СУБД или выполнить SELECT qhb_drop_rel_cache('имя_таблицы');.

Примечание.
Для чтения из stdin нужно использовать вертикальную черту (|). Примеры использования команд:

Команда create_table:

cat data.csv | qdl create_table --config config.yml --data -

Команда validate:

cat data.csv | qdl validate --verbose --config config.yml --data -

Команда insert_values:

cat data.csv | qdl insert_values --config config.yml --data - --out-dir output/