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