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

Поддерживаемые типы полей
Синтаксис
Команда create_table
- Флаги
- Пример использования
Команда insert_values
Команда validate
- Флаги
- Пример использования
Файл конфигурации
- Пример файла конфигурации
Сценарий использования

Модуль прямой загрузки данных (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.

ПАРАМЕТРЫ

-C
--cdc-info <выходной каталог для cdc.info>
Выходной каталог для qdl-cdc.info файла (корень PGDATA).

-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

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

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

general — базовая конфигурация приложения. Содержит поля:
- threads (целочисленное) количество потоков-обработчиков сырых данных.
- chunk_size — (целочисленное, необязательное) размер внутреннего буфера передачи данных;
  данный параметр может меняться с целью оптимизации в нестандартных аппаратных конфигурациях.
data_source — выбор источника данных. В данной версии единственным поддерживаемым форматом является csv и содержит поля:
- delimiter — разделитель столбцов для CSV.
- double_quote — если true то две кавычки подряд считаются как одна, экранированная кавычка.
- escape — Символ, используемый для экранирования.
- comment — Символ, отмечающий начало комментария.
output — конфигурация выходных данных. Содержит поля:
- segment_size — (целочисленное, необязательное) максимальное количество страниц в сегменте базы данных.
- oid — (целочисленное) идентификатор основной таблицы.
- toast_oid — (целочисленное, необязательное) идентификатор toast таблицы.
table — конфигурация таблицы. Содержит поля:
- name — (строковое) имя таблицы.
- fields — (повторяющиеся field) описание каждого из полей (например, field_1 : varchar и необязательная пометка [nullable]).

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

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

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

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

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

Проверить 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/

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

ШАГ 4:

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

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

Примечание
Для чтения из 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

Документация по СУБД «Квант-Гибрид» 1.5.0