Модуль прямой загрузки данных 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.
Синтаксис
ПРИМЕНЕНИЕ:
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
Файл конфигурации
Файл конфигурации имеет следующие партиции:
- general — базовая конфигурация приложения. Содержит поля threads (целочисленное) и chunk_size (целочисленное, необязательное). Первое ответственно за количество потоков-обработчиков сырых данных. Второе ответственно за размер внутреннего буфера передачи данных; данный параметр может меняться с целью оптимизации в нестандартных аппаратных конфигурациях.
- input — конфигурация входных данных. Содержит поля path (путь), encoding (строковое) и delimiter (строковое, необязательное). Первое — путь до входного файла, второе — кодировка, третье — разделитель столбцов для входных форматов, удобочитаемых для пользователя.
- output — конфигурация выходных данных. Содержит поля segment_size (целочисленное, необязательное) и oid (целочисленное). Первое — максимальное количество страниц в сегменте базы данных, второе — идентификатор объекта, который составит часть пути до сегментов.
- 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/