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

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

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

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

Типы	Названия
Целочисленные	`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.

Синтаксис

USAGE:
    qdl <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    create_table     Generate SQL script to create a table
    insert_values    Populate a table file with values
    validate         Validates csv data file
    help             Prints this message or the help of the given subcommand(s)

Команда `create_table`

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

USAGE:
    qdl create_table [FLAGS] [OPTIONS] --config <config>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Display debug messages

OPTIONS:
    -c, --config <config>    Path to config
    -d, --data <data>        Path to csv file with data

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

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

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

Команда `insert_values`

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

USAGE:
    qdl insert_values [FLAGS] [OPTIONS] --config <config> --out-dir <out-dir>
FLAGS:
    -h, --help           Prints help information
    -s, --skip-errors    Continue adding rows despite errors
    -V, --version        Prints version information
    -v, --verbose        Display debug messages

OPTIONS:
    -c, --config <config>            Path to config
    -d, --data <data>                Path to csv file with data
    -o, --out-dir <out-dir>          Output directory

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

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

Команда `validate`

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

USAGE:
    qdl validate [FLAGS] [OPTIONS] --config <config>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Display debug messages

OPTIONS:
    -c, --config <config>    Path to config
    -d, --data <data>        Path to csv file with data

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

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

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

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

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

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

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

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

# Конфигурация получаемых данных:
output:
    # Object IDentifier. Определяет целочисленный идентификатор для группы файлов целевой таблицы.
    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 (Object Identifier; потребуется для файла конфигурации insert_values) и пути файлов БД. Эти операции могут быть произведены вручную, но во избежание возможных ошибок рекомендуется использовать скрипт.

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

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

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

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