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

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

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

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

Примечание
В текущей версии 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 [флаги] [параметры] [субкоманды]

Флаги

-h
--help
Выводит справочную информацию об аргументах командной строки qdl.

-v
--verbose
Выводит отладочную информацию qdl.

-V
--version
Выводит информацию о версии qdl.

Параметры

-c
--config <файл_конфигурации>
Путь к файлу конфигурации qdl.

-d
--data <файл_данных>
Путь к исходным данным. Используйте '-', чтобы читать из stdin.

Субкоманды

create_table
Генерирует SQL-скрипт для создания таблицы.

help
Выводит список доступных субкоманд или справку по заданным субкомандам.

insert_values
Заполняет файл с таблицей значениями.

validate
Проверяет правильность файла CSV с данными.

Команда create_table

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

qdl --config <файл_конфигурации> --data <файл_данных> create_table [флаги]

Флаги

-h
--help
Выводит справочную информацию об аргументах командной строки create_table.

-V
--version
Выводит информацию о версии create_table.

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

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

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

Команда insert_values

Производит загрузку из файла в формате CSV в таблицу формата, используемого QHB. Данная команда выполняется многопоточно; количество ядер, отводимое под параллельную обработку, указывается в файле конфигурации. Пользователь может установить пороговый процент срабатывания механизма очистки избыточно выделенной памяти.

Параметр --out-dir <выходной_каталог> является обязательным для ввода из командной строки.

Также рекомендуется предварительно удостовериться, что версия компоновки страницы QHB равна 4. Сделать это можно, например, при помощи расширения pageinspect::page_header.

qdl --config <файл_конфигурации> --data <файл_данных> insert_values [параметры] --out-dir <выходной_каталог> [флаги]

Флаги

-h
--help
Выводит справочную информацию об аргументах командной строки insert_values.

-V
--version
Выводит информацию о версии insert_values.

Параметры

-o
--out-dir <выходной_каталог>
Выходной каталог.

-r
--ram-usage-percent <%_оперативной_памяти>
Процент используемой оперативной памяти, после которой запускается сборщик мусора для внутренних буферов (от 1 до 99; значение по умолчанию — 80).

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

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

Команда validate

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

    qdl --config <файл_конфигурации> --data <файл_данных> validate [флаги]

Флаги

-h
--help
Выводит справочную информацию об аргументах командной строки validate.

-V
--version
Выводит информацию о версии validate.

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

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

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

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

1. general — базовая конфигурация приложения. Содержит поля:

   • threads (целочисленное) — количество потоков-обработчиков сырых данных.
   • chunk_size (целочисленное, необязательное) — размер внутреннего буфера передачи данных; данный параметр может меняться с целью оптимизации в нестандартных аппаратных конфигурациях.
   • checksum (логическое, необязательное, по умолчанию true) — задает расчет контрольных сумм.

2. data_source — выбор источника данных. В данной версии единственным поддерживаемым форматом является csv. Содержит поля:

   • delimiter — разделитель столбцов для CSV.
   • double_quote — если true, то две кавычки подряд воспринимаются как одна экранированная кавычка.
   • escape — символ, используемый для экранирования.
   • comment — символ, отмечающий начало комментария.

3. output — конфигурация выходных данных. Содержит поля:

   • segment_size (целочисленное, необязательное) — максимальное количество страниц в сегменте базы данных.
   • oid (целочисленное) — идентификатор основной таблицы.
   • toast_oid (целочисленное, необязательное) — идентификатор таблицы TOAST.

4. table — конфигурация таблицы. Содержит поля:

   • name (строковое) — имя таблицы.
   • fields (повторяющиеся field) — описание каждого из полей (например, field_1 : varchar и необязательная пометка [nullable]).

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

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

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

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

# Конфигурация целевой таблицы:
table:
    # Имя таблицы. Требуется для задания имени создаваемой таблицы.
    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 (необязательный):

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

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

ШАГ 1:

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

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

ШАГ 2:

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

ШАГ 3:

Загрузить таблицу. Этот процесс может занять значительное время, в зависимости от объема загружаемых данных. Потоки, выполняющие чтение/конвертацию/запись, имеют определенные названия; это позволит системному администратору оценить загруженность каждого отдельно взятого потока ядра и определить их количеством таким образом, чтобы добиться оптимальной производительности. Также нужно заметить, что внутренние буфера qdl не имеют ограничения размера, а значит, при очень медленной записи на диск возможна ситуация, когда эти буферы займут всю оперативную память.

qdl --config config.yml --data data.csv insert_values --out-dir ./output_dir/

ШАГ 4:

Заменить файлы СУБД сгенерированными при помощи qdl — копируем файлы при помощи команд операционной системы. После этого нужно выполнить следующий запрос:

SELECT qhb_attach_qdl_data('имя_таблицы');

При этом сбрасывается кэш данных таблицы и соответствующей ей таблицы TOAST (если она имеется), происходит переподключение файлов данных таблицы, переиндексация таблицы TOAST, регистрация данных для функционала CDC (Change Data Capture).

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

Команда create_table:

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

Команда validate:

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

Команда insert_values:

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

Вызов справочной информации:

qdl -h