gpload

Contents

Синтаксис
Требования
Описание
Параметры
- Параметры подключения
Формат управляющего файла
Формат лог-файла
Примечания
См. также

Запускает задачу загрузки данных, описанную в управляющем файле формата YAML. Подробное описание и примеры использования см. в статье Использование gpload.

gpload -f <control_file>
       [ -l <log_file> ]
       [ -h <hostname> ]
       [ -p <port> ]
       [ -U <username> ]
       [ -d <database> ]
       [ -W ]
       [ --gpfdist_timeout <seconds> ]
       [ --no_auto_trans ]
       [ --max_retries <retry_times> ]
       [ [ -v | -V ] [ -q ] ]
       [ -D ]

gpload -?

gpload --version

Клиентский хост, с которого запускается gpload, должен соответствовать следующим требованиям:

Установлена утилита параллельной загрузки файлов gpfdist, доступная в PATH. Обычно она находится в каталоге $GPHOME/bin вашей установки Greengage DB.
Доступ по сети (входящие и исходящие соединения) ко всем хостам кластера Greengage DB, включая мастер и сегменты.
Доступ по сети (входящие и исходящие соединения) ко всем хостам, на которых расположены источники данных для загрузки (ETL-серверы).

Описание

gpload — утилита для загрузки данных, которая служит интерфейсом к функции параллельной загрузки внешних таблиц Greengage DB. Используя спецификацию загрузки, заданную в управляющем файле в формате YAML, gpload выполняет следующие действия: вызывает параллельный файловый сервер Greengage DB (gpfdist), создает определение внешней таблицы на основе исходных данных и запускает операцию INSERT, UPDATE или MERGE для загрузки данных в целевую таблицу.

ПРИМЕЧАНИЕ

Утилита gpfdist совместима только с мажорной версией Greengage DB, с которой она поставляется. Например, gpfdist, установленная вместе с Greengage DB 6.x, не может использоваться с Greengage DB 7.x.

ПРИМЕЧАНИЕ

Операции MERGE и UPDATE не поддерживаются, если имя столбца целевой таблицы является зарезервированным ключевым словом, содержит заглавные буквы или включает любой символ, требующий кавычек (" ") для идентификации столбца.

Операции, включая любые SQL-команды, указанные в разделе SQL управляющего YAML-файла (см. раздел Формат управляющего файла), выполняются в рамках одной транзакции, чтобы предотвратить неконсистентность данных при выполнении нескольких одновременных операций загрузки в целевую таблицу.

-f <control_file>: (Обязательно) YAML-файл, содержащий спецификацию загрузки. Подробности см. в разделе Формат управляющего файла.
--gpfdist_timeout <seconds>: Устанавливает тайм-аут ожидания ответа программы параллельной загрузки файлов gpfdist. Допустимые значения: от 0 до 30 секунд (0 отключает тайм-ауты). Обратите внимание, что в сетях с высокой нагрузкой может потребоваться увеличить это значение.
-l <log_file>: Указывает путь к лог-файлу. По умолчанию ~/gpAdminLogs/gpload_YYYYMMDD. См. подробности в разделе Формат лог-файла.
--no_auto_trans: Отключает обработку операции загрузки как единой транзакции при выполнении одной операции загрузки в целевую таблицу.

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

Данная опция не может использоваться совместно с -v или -V.
-D: Проверка на наличие ошибок без выполнения фактической загрузки.
-v: Отображает подробный вывод шагов загрузки по мере их выполнения.

Данная опция не может использоваться совместно с -q.
-V: Отображает максимально подробный вывод загрузки.

Данная опция не может использоваться совместно с -q.
-?: Выводит справочную информацию.
--version: Выводит версию утилиты и завершает работу.

-d <database>: Имя базы данных, в которую выполняется загрузка. Если параметр не указан, используется значение из управляющего файла загрузки, переменной окружения PGDATABASE или имя текущего пользователя системы.
-h <hostname>: Имя хоста, на котором запущен мастер Greengage DB. Если параметр не указан, используется значение из управляющего файла загрузки, переменной окружения PGHOST или localhost.
-p <port>: TCP-порт, на котором мастер Greengage DB ожидает подключения. Если параметр не указан, используется значение из управляющего файла загрузки, переменной окружения PGPORT или 5432.
--max_retries <retry_times>: Максимальное количество попыток подключения gpload к Greengage DB после тайм-аута подключения. Значение по умолчанию — 0 (не выполнять повторных попыток). Отрицательное число, например -1, указывает на неограниченное количество попыток.
-U <username>: Имя роли базы данных для подключения. Если параметр не указан, используется значение из управляющего файла загрузки, переменной окружения PGUSER или имя текущего пользователя системы.
-W: Принудительно запрашивает пароль у пользователя. Если параметр не указан, пароль читается из переменной окружения PGPASSWORD, файла паролей, указанного в PGPASSFILE, или из ~/.pgpass. Если ни один из этих источников не указан, gpload запросит пароль даже без указания -W.

Управляющий файл gpload использует формат YAML 1.1 и содержит собственную схему для описания шагов операции загрузки в Greengage DB. Файл должен быть корректным YAML-документом.

gpload обрабатывает управляющий файл последовательно, используя отступы (пробелы) для определения иерархии документа и взаимосвязей между разделами. Использование пробелов имеет значение. Не стоит использовать пробелы для форматирования, а символы табуляции полностью запрещены.

Базовая структура управляющего файла загрузки:

---
VERSION: 1.0.0.1
DATABASE: <db_name>
USER: <db_username>
HOST: <master_hostname>
PORT: <master_port>
GPLOAD:
  INPUT:
    - SOURCE:
        LOCAL_HOSTNAME:
          - <hostname_or_ip>
        PORT: <http_port>
      | PORT_RANGE: [ <start_port_range>, <end_port_range> ]
        FILE:
          - </path/to/input_file>
        SSL: true | false
        CERTIFICATES_PATH: </path/to/certificates>
    - FULLY_QUALIFIED_DOMAIN_NAME: true | false
    - COLUMNS:
        - <field_name>: <data_type>
    - TRANSFORM: '<transformation>'
    - TRANSFORM_CONFIG: '<configuration-file-path>'
    - MAX_LINE_LENGTH: <integer>
    - FORMAT: text | csv
    - DELIMITER: '<delimiter_character>'
    - ESCAPE: '<escape_character>' | 'OFF'
    - NEWLINE: 'LF' | 'CR' | 'CRLF'
    - NULL_AS: '<null_string>'
    - FILL_MISSING_FIELDS: true | false
    - FORCE_NOT_NULL: <column_name> [, ...]
    - QUOTE: '<csv_quote_character>'
    - HEADER: true | false
    - ENCODING: <database_encoding>
    - ERROR_LIMIT: <integer>
    - LOG_ERRORS: true | false
  EXTERNAL:
    - SCHEMA: <schema> | '%'
  OUTPUT:
    - TABLE: <schema.table_name>
    - MODE: insert | update | merge
    - MATCH_COLUMNS:
        - <target_column_name>
    - UPDATE_COLUMNS:
        - <target_column_name>
    - UPDATE_CONDITION: '<boolean_condition>'
    - MAPPING:
        <target_column_name>: <source_column_name> | '<expression>'
  PRELOAD:
    - TRUNCATE: true | false
    - REUSE_TABLES: true | false
    - STAGING_TABLE: <external_table_name>
    - FAST_MATCH: true | false
  SQL:
    - BEFORE: "<sql_command>"
    - AFTER: "<sql_command>"

Ключ Описание Обязательность

Ключ	Описание	Обязательность
VERSION	Версия схемы управляющего файла `gpload`. Текущая версия — 1.0.0.1	Да
DATABASE <db_name>	База данных, к которой выполняется подключение. Если значение не указано, по умолчанию применяется значение `PGDATABASE` или имя текущего пользователя системы. Указать базу данных также можно с помощью опции командной строки `-d` при запуске `gpload`	Нет
USER <db_username>	Указывает имя роли, с помощью которой выполняется подключение к базе данных. Если значение не указано, по умолчанию используется имя текущего пользователя или применяется значение `PGUSER`, если оно установлено. Указать роль также можно с помощью опции командной строки `-U` при запуске `gpload`. Если пользователь запускает `gpload`, не являясь при этом суперпользователем, то ему должны быть выданы соответствующие привилегии, разрешающие загрузку данных	Нет
HOST <master_hostname>	Имя мастер-хоста Greengage DB. Если значение не указано, по умолчанию используется `localhost` или применяется значение `PGHOST`, если оно установлено. Указать имя мастер-хоста также можно с помощью опции командной строки `-h` при запуске `gpload`	Нет
PORT <master_port>	Порт, прослушиваемый мастер-сервером Greengage DB. Если значение не указано, по умолчанию используется порт `5432` или применяется значение `PGPORT`, если оно установлено. Указать номер порта также можно с помощью опции командной строки `-p` при запуске `gpload`	Нет
GPLOAD	Содержит спецификацию загрузки. Спецификация должна содержать разделы `INPUT` и `OUTPUT`	Да
INPUT	Определяет местоположение и формат исходных данных	Да
SOURCE	Указывает местоположение исходного файла данных. В разделе `INPUT` можно указать более одного подраздела `SOURCE`. Каждый созданный подраздел `SOURCE` соответствует одному экземпляру `gpfdist`, запущенному на локальной машине. В каждом подразделе `SOURCE` должна быть указана спецификация `FILE`	Да
LOCAL_HOSTNAME <hostname_or_ip>	Указывает имя хоста или IP-адрес локальной машины, на которой запущен `gpload`. Если на машине настроено несколько сетевых адаптеров (NIC), можно указать имя хоста или IP-адрес каждого отдельного адаптера, чтобы разрешить сетевому трафику использовать их все одновременно. По умолчанию используется только основное имя хоста или IP-адрес локальной машины	Нет
PORT <http_port>	Указывает номер порта, который использует утилита `gpfdist`. Можно также использовать `PORT_RANGE` для указания диапазона портов. Если одновременно указаны значения `PORT` и `PORT_RANGE`, выбирается значение `PORT`. Если значения `PORT` и `PORT_RANGE` не указаны, по умолчанию выбирается свободный порт в диапазоне между `8000` и `9000`. Если в ключе `LOCAL_HOSTNAME` указано несколько имен хостов, выбранный номер порта используется для всех хостов. Такая конфигурация рекомендуется в случае, когда требуется использовать несколько сетевых адаптеров для загрузки одного файла или нескольких файлов из одного каталога	Нет
PORT_RANGE <start_port_range>, <end_port_range>	Указывает диапазон портов, из которого утилита `gpload` выбирает свободный порт для запуска экземпляра `gpfdist`	Нет
FILE </path/to/input_file>	Указывает местоположение файла, каталога в локальной файловой системе или именованного канала, содержащего данные для загрузки. Можно указать несколько файлов при условии, что все они используют один и тот же формат данных. Для указания нескольких файлов можно использовать подстановочные знаки (wildcards), например, `` или `[]`. При чтении автоматически распаковываются файлы с расширениями .gz* и .bz2. Пути к файлам должны быть указаны относительно каталога, из которого запускается `gpload` (также поддерживаются абсолютные пути)	Да
SSL true \| false	Указывает, что используется защищенное SSL-соединение. Если указано значение `true`, `gpload` запускает утилиту `gpfdist` с опцией `--ssl` и использует протокол GPFDISTS. Более подробную информацию можно получить в разделе Настройка SSL	Нет
CERTIFICATES_PATH </path/to/certificates>	Указывает местоположение хранилища сертификатов. Обязателен, если ключу `SSL` присвоено значение `true`; не может указываться, если ключ `SSL` не указан или ему присвоено значение `false`. Каталог, указанный в `CERTIFICATES_PATH`, должен содержать следующие файлы: server.crt — файл сертификата сервера; server.key — файл закрытого ключа сервера; root.crt — файл корневого центра сертификации. Корневой каталог (`/`) нельзя использовать в качестве значения `CERTIFICATES_PATH`	Да, если ключу `SSL` присвоено `true`
FULLY_QUALIFIED_DOMAIN_NAME true \| false	Указывает способ определения имен хостов в `gpload`: по полному доменному имени (FQDN) или локальному имени хоста. Если указано значение `true`, имена хостов определяются по полному доменному имени; в противном случае, имена определяются по локальным именам. По умолчанию применяется значение `false`. Использование полных доменных имен может потребоваться в ряде случаев. Например, если Greengage DB и приложение ETL, к которому обращается `gpload`, находятся в разных доменах	Нет
COLUMNS <field_name>: <data_type>	Указывает схему файлов данных в формате пары из имени столбца и типа данных (`field_name:data_type`). Символ разделителя (`DELIMITER`) в исходном файле разделяет два значения данных (столбца). Строка определяется символом перевода строки (`0x0a`). Если входные столбцы (`COLUMNS`) не указаны, то используется схема целевой таблицы (`TABLE`), что означает, что исходные данные должны иметь тот же порядок столбцов, их количество и формат данных, что и целевая таблица. По умолчанию сопоставление источника и целевой таблицы основано на совпадении имен столбцов, указанных в этом разделе, и имен столбцов в целевой таблице (`TABLE`). Это сопоставление по умолчанию можно переопределить с помощью раздела `MAPPING`	Нет
TRANSFORM '<transformation>'	Указывает имя трансформации, переданной `gpload`. Более подробную информацию можно получить в разделе Загрузка с помощью gpload	Нет
TRANSFORM_CONFIG '<configuration-file-path>'	Указывает местоположение файла конфигурации трансформации. Более подробную информацию можно получить в разделе Файл конфигурации трансформации	Да, если указано значение `TRANSFORM`
MAX_LINE_LENGTH <integer>	Устанавливает максимальный размер строки данных в байтах, по умолчанию `32768`. Ключ следует использовать, если в данных содержатся очень длинные строки (или при получении сообщения об ошибке `line too long`). Без необходимости ключ использовать не следует, так как это увеличивает потребление ресурсов. Допустимый диапазон значений — от 32 КБ до 256 МБ. На системах семейства Windows верхний предел составляет 1 МБ	Нет
FORMAT text \| csv	Указывает формат исходных данных: текст (`TEXT`) или значения, разделенные запятыми (`CSV`). Если значение не указано, по умолчанию применяется `TEXT`. Более подробную информацию можно получить в статье Форматирование внешних данных	Нет
DELIMITER '<delimiter_character>'	Указывает ASCII-символ, использующийся в качестве разделителя. Разделитель должен располагаться между полями, но не в начале и не в конце строки. Вы также можете указать непечатаемый ASCII-символ или Unicode-символ, например `\x1B` или `\u001B`. Для непечатаемых символов также поддерживается синтаксис экранирования строк вида `E'<код символа>'`. ASCII- или Unicode-символ должен быть заключен в одинарные кавычки, например, `E'\x1B'` или `E'\u001B'`. Для текстовых файлов по умолчанию используется знак табуляции (`0x09`). Для CSV файлов по умолчанию используется знак запятой (`,`). Более подробную информацию можно получить в разделе Форматирование столбцов	Нет
ESCAPE '<escape_character>' \| 'OFF'	Указывает символ экранирования. Для текстовых файлов по умолчанию используется знак обратной косой черты (`\`). Экранирование можно отключить, указав значение `OFF`. Для CSV файлов по умолчанию используется знак кавычек (`"`). Более подробную информацию можно получить в разделе Символы экранирования	Нет
NEWLINE 'LF' \| 'CR' \| 'CRLF'	Указывает символ переноса строки и принимает значения `LF` (символ перевода строки, `0x0A`), `CR` (символ возврата каретки, `0x0D`) или `CR`, совмещенный с `LF` (`CRLF`, `0x0D 0x0A`). Если значение не указано, используется символ переноса строки, которым заканчивается первая строка файла данных. Более подробную информацию можно получить в разделе Форматирование строк	Нет
NULL_AS '<null_string>'	Указывает строку, обозначающую null-значение — неизвестное значение колонки или поля. Для текстовых файлов по умолчанию используется строка `\N`. Для CSV файлов по умолчанию используется пустое значение, не заключенное в кавычки. Более подробную информацию можно получить в разделе Обработка NULL-значений	Нет
FILL_MISSING_FIELDS true \| false	Устанавливает значения `NULL` для пропущенных полей в конце строки или записи. Если значение не установить, в подобных случаях будет возвращена ошибка. Пустые строки, поля с ограничением `NOT NULL` и конечные разделители в любом случае вернут ошибку	Нет
FORCE_NOT_NULL ( <column_name> [, …] )	Позволяет обрабатывать значения полей как заключенные в кавычки. Так как null-значение по умолчанию — пустое значение, не заключенное в кавычки, это позволяет обрабатывать отсутствующие значения как пустые строки	Нет
QUOTE '<csv_quote_character>'	Указывает символ кавычек. По умолчанию используется знак двойных кавычек (`"`)	Нет
HEADER true \| false	Указывает на наличие заголовка в файле данных. Если используются несколько файлов с данными, то все они должны иметь заголовок. По умолчанию предполагается, что заголовок в файлах данных отсутствует	Нет
ENCODING <database_encoding>	Определяет кодировку символов исходных данных. Если значение не указано, используется клиентская кодировка по умолчанию. При изменении значения `ENCODING` в существующем управляющем файле `gpload` требуется вручную удалить таблицы, при создании которых использовалось прошлое значение кодировки. `gpload` не удаляет и не пересоздает таблицы с использованием нового значения `ENCODING`, если ключу `REUSE_TABLES` присвоено значение `true`. Более подробную информацию можно получить в разделе Кодировка символов	Нет
ERROR_LIMIT <integer>	Включает для данной загрузки режим изоляции ошибок для одной строки. При включении этого режима входные строки данных, содержащие ошибки форматирования, отклоняются до тех пор, пока на любом сегменте Greengage DB не будет превышено пороговое значение количества ошибок. Если порог не достигнут, все корректные строки загружаются, а некорректные — отклоняются либо сохраняются в лог ошибок. По умолчанию операция загрузки прерывается при первой ошибке. Обратите внимание, что изоляция ошибок для одной строки применяется только к строкам данных с ошибками формата, например, лишними или отсутствующими атрибутами, атрибутами с неправильным типом данных или неверной кодировкой. Ошибки ограничений, например, нарушения первичного ключа, все равно приводят к отмене операции загрузки	Нет
LOG_ERRORS true \| false	Указывает, сохранять ли в лог информацию об ошибках, если установлено значение `ERROR_LIMIT`. Может принимать значения `true` или `false` (по умолчанию). Если установлено значение `true`, то строки данных, содержащие ошибки форматирования, сохраняются во внутренний лог. Ошибки форматирования можно просмотреть с помощью встроенной SQL-функции `gp_read_error_log('<table_name>')`. Если при загрузке данных обнаружены ошибки форматирования, `gpload` выводит предупреждающее сообщение с именем таблицы, содержащей информацию об ошибках. Если для `LOG_ERRORS` установлено значение `true`, то для `REUSE_TABLES` также требуется установить `true`, чтобы сохранить ошибки форматирования в логах ошибок Greengage DB. В противном случае, если для `REUSE_TABLES` установлено значение `false` или этот ключ не указан, информация об ошибках удаляется после операции `gpload`. Возвращается только сводная информация об ошибках форматирования. Вы можете удалить ошибки форматирования из логов ошибок с помощью функции `gp_truncate_error_log()`	Нет
EXTERNAL	Указывает схему внешних таблиц, создаваемых `gpload`. По умолчанию используется схема из `search_path` Greengage DB	Нет
SCHEMA <schema> \| '%'	Имя схемы внешней таблицы. Если схемы с таким именем не найдено, возвращается ошибка. Если указан символ процента (`%`), используется схема таблицы, указанной для ключа `TABLE` раздела `OUTPUT`. Если в имени таблицы не указано имя схемы, используется схема по умолчанию	Да, если указано значение `EXTERNAL`
OUTPUT	Определяет целевую таблицу и значения колонок для загрузки в БД	Да
TABLE <schema.table_name>	Указывает целевую таблицу для загрузки данных	Да
MODE insert \| update \| merge	Определяет режим загрузки данных. Если значение не указано, используется режим `INSERT`. Доступны следующие режимы: `INSERT` — загружает данные в целевую таблицу путем выполнения запроса `SELECT *` к внешней таблице, созданной `gpload`, а затем вставки данных в целевую таблицу с помощью команды `INSERT`. `UPDATE` — обновляет данные в колонках, указанных в `UPDATE_COLUMNS`, если выполнены следующие условия: Значения строк в колонках, указанных в `MATCH_COLUMNS`, и в исходных данных совпадают. Опциональное логическое условие, указанное в `UPDATE_CONDITION`, принимает значение `true`. `MERGE` — добавляет новые строки и обновляет данные в колонках, указанных в `UPDATE_COLUMNS`, если выполнены следующие условия: Значения строк в колонках, указанных в `MATCH_COLUMNS`, и в исходных данных совпадают. Опциональное логическое условие, указанное в `UPDATE_CONDITION`, принимает значение `true`. Строки считаются новыми, если у значений колонок, указанных в `MATCH_COLUMNS`, нет совпадающих значений среди имеющихся данных таблицы. В таких случаях в таблицу добавляется полная строка из исходных данных. Если у значений колонок, указанных в `MATCH_COLUMNS`, несколько совпадающих значений, в таблицу добавляется только одна строка из исходных данных. Для выбора нужной строки используйте логическое условие `UPDATE_CONDITION`	Нет
MATCH_COLUMNS <target_column_name>	Указывает колонки, которые выступают в роли условий объединения для обновления данных. Для того чтобы произошло обновление данных, значения в целевых колонках должны совпадать с соответствующими значениями колонок исходных данных	Да, если `MODE` присвоено значение `UPDATE` или `MERGE`
UPDATE_COLUMNS <target_column_name>	Указывает колонки, данные в которых будут обновлены при совпадении значений строк в колонках, указанных в `MATCH_COLUMNS`, и выполнении опционального логического условия, указанного в `UPDATE_CONDITION`	Да, если `MODE` присвоено значение `UPDATE` или `MERGE`
UPDATE_CONDITION '<boolean_condition>'	Указывает логическое условие (подобное используемым в выражении `WHERE`), которое должно выполниться, чтобы произошло обновление данных	Нет
MAPPING <source_column_name> \| '<expression>'	Переопределяет принцип сопоставления столбцов источника и целевой таблицы. По умолчанию сопоставление происходит по совпадениям имен столбцов источника, указанных в ключе `COLUMNS`, и столбцов целевой таблицы, указанной в `TABLE`. Выражение указывается в виде пар исходных и целевых столбцов (`<target_column_name>: <source_column_name>`) или целевых столбцов и выражений (`<target_column_name>: '<expression>'`). В качестве выражения (`<expression>`) может выступать любое выражение, подобное используемым в списке `SELECT`: значение константы, имя столбца, вызов оператора или функции и т.д.	Нет
PRELOAD	Указывает операции, выполняемые перед загрузкой данных. В настоящее время поддерживается только операция `TRUNCATE`	Нет
TRUNCATE true \| false	Если установлено значение `true`, `gpload` удаляет все строки целевой таблицы перед загрузкой данных. Значение по умолчанию — `false`	Нет
REUSE_TABLES true \| false	Если установлено значение `true`, `gpload` не удаляет созданные им внешние и промежуточные таблицы. Эти объекты задействуются для последующих загрузок, использующих ту же спецификацию, что улучшает производительность постепенных загрузок (периодических небольших загрузок в одну и ту же целевую таблицу). Если ключу `LOG_ERRORS` присвоено значение `true`, то `REUSE_TABLES` также должно быть присвоено `true`, чтобы сохранять ошибки форматирования в журналах ошибок Greengage DB. Если `REUSE_TABLES` присвоено `false`, информация об ошибках форматирования удаляется после операции `gpload`	Нет
STAGING_TABLE <external_table_name>	Указывает имя временной внешней таблицы, которая создается при работе `gpload`. Внешняя таблица используется утилитой `gpfdist`. Ключу `REUSE_TABLES` также должно быть присвоено значение `true`. В противном случае, если `REUSE_TABLES` не указан или имеет значение `false`, `STAGING_TABLE` игнорируется. По умолчанию `gpload` создает временную внешнюю таблицу со случайно сгенерированным именем. Если `<external_table_name>` содержит точку (.), `gpload` возвращает ошибку. Если таблица существует, `gpload` использует эту таблицу. Значение `SCHEMA` в разделе `EXTERNAL` служит схемой для таблицы `<external_table_name>`. Утилита возвращает ошибку, если схема существующей таблицы не соответствует схеме таблицы, указанной в `OUTPUT`. Если ключу `SCHEMA` присвоено значение `%`, то схема для таблицы `<external_table_name>` совпадает со схемой целевой таблицы, то есть с таблицей, указанной в ключе `TABLE` раздела `OUTPUT`. Если ключ `SCHEMA` не указан, `gpload` ищет таблицу, используя схемы в `search_path` базы данных. Если таблица не найдена, внешняя таблица `<external_table_name>` создается в схеме по умолчанию (`PUBLIC`). `gpload` создает промежуточную таблицу, используя ключи распределения целевой таблицы в качестве ключей распределения для промежуточной таблицы. Если целевая таблица использует случайное распределение (`DISTRIBUTED RANDOMLY`), то значение `MATCH_COLUMNS` служит в качестве ключей распределения промежуточной таблицы	Нет
FAST_MATCH true \| false	Если установлено значение `true`, `gpload` выполняет поиск внешних таблиц для переиспользования только по базе данных. Если ключу `REUSE_TABLES` присвоено значение `false` или ключ не указан, а ключу `FAST_MATCH` присвоено значение `true`, `gpload` выводит предупреждающее сообщение	Нет
SQL	Указывает опциональные произвольные команды SQL, которые запускаются перед (`BEFORE`) и после (`AFTER`) операции загрузки данных. Один из возможных сценариев использования раздела — настройка логирования операции загрузки, как описано в примерах	Нет
BEFORE "<sql_command>"	SQL-команда, запускаемая перед операцией загрузки. Команды следует заключать в кавычки	Нет
AFTER "<sql_command>"	SQL-команда, запускаемая после операции загрузки. Команды следует заключать в кавычки	Нет

VERSION

Версия схемы управляющего файла gpload. Текущая версия — 1.0.0.1

Да

DATABASE <db_name>

База данных, к которой выполняется подключение.

Если значение не указано, по умолчанию применяется значение PGDATABASE или имя текущего пользователя системы. Указать базу данных также можно с помощью опции командной строки -d при запуске gpload

Нет

USER <db_username>

Указывает имя роли, с помощью которой выполняется подключение к базе данных.

Если значение не указано, по умолчанию используется имя текущего пользователя или применяется значение PGUSER, если оно установлено. Указать роль также можно с помощью опции командной строки -U при запуске gpload. Если пользователь запускает gpload, не являясь при этом суперпользователем, то ему должны быть выданы соответствующие привилегии, разрешающие загрузку данных

Нет

HOST <master_hostname>

Имя мастер-хоста Greengage DB.

Если значение не указано, по умолчанию используется localhost или применяется значение PGHOST, если оно установлено. Указать имя мастер-хоста также можно с помощью опции командной строки -h при запуске gpload

Нет

PORT <master_port>

Порт, прослушиваемый мастер-сервером Greengage DB.

Если значение не указано, по умолчанию используется порт 5432 или применяется значение PGPORT, если оно установлено. Указать номер порта также можно с помощью опции командной строки -p при запуске gpload

Нет

GPLOAD

Содержит спецификацию загрузки. Спецификация должна содержать разделы INPUT и OUTPUT

Да

INPUT

Определяет местоположение и формат исходных данных

Да

SOURCE

Указывает местоположение исходного файла данных.

В разделе INPUT можно указать более одного подраздела SOURCE. Каждый созданный подраздел SOURCE соответствует одному экземпляру gpfdist, запущенному на локальной машине. В каждом подразделе SOURCE должна быть указана спецификация FILE

Да

LOCAL_HOSTNAME <hostname_or_ip>

Указывает имя хоста или IP-адрес локальной машины, на которой запущен gpload.

Если на машине настроено несколько сетевых адаптеров (NIC), можно указать имя хоста или IP-адрес каждого отдельного адаптера, чтобы разрешить сетевому трафику использовать их все одновременно. По умолчанию используется только основное имя хоста или IP-адрес локальной машины

Нет

PORT <http_port>

Указывает номер порта, который использует утилита gpfdist.

Можно также использовать PORT_RANGE для указания диапазона портов. Если одновременно указаны значения PORT и PORT_RANGE, выбирается значение PORT. Если значения PORT и PORT_RANGE не указаны, по умолчанию выбирается свободный порт в диапазоне между 8000 и 9000. Если в ключе LOCAL_HOSTNAME указано несколько имен хостов, выбранный номер порта используется для всех хостов. Такая конфигурация рекомендуется в случае, когда требуется использовать несколько сетевых адаптеров для загрузки одного файла или нескольких файлов из одного каталога

Нет

PORT_RANGE <start_port_range>, <end_port_range>

Указывает диапазон портов, из которого утилита gpload выбирает свободный порт для запуска экземпляра gpfdist

Нет

FILE </path/to/input_file>

Указывает местоположение файла, каталога в локальной файловой системе или именованного канала, содержащего данные для загрузки.

Можно указать несколько файлов при условии, что все они используют один и тот же формат данных. Для указания нескольких файлов можно использовать подстановочные знаки (wildcards), например, * или []. При чтении автоматически распаковываются файлы с расширениями .gz и .bz2. Пути к файлам должны быть указаны относительно каталога, из которого запускается gpload (также поддерживаются абсолютные пути)

Да

SSL true | false

Указывает, что используется защищенное SSL-соединение.

Если указано значение true, gpload запускает утилиту gpfdist с опцией --ssl и использует протокол GPFDISTS.

Более подробную информацию можно получить в разделе Настройка SSL

Нет

CERTIFICATES_PATH </path/to/certificates>

Указывает местоположение хранилища сертификатов.

Обязателен, если ключу SSL присвоено значение true; не может указываться, если ключ SSL не указан или ему присвоено значение false.

Каталог, указанный в CERTIFICATES_PATH, должен содержать следующие файлы:

server.crt — файл сертификата сервера;
server.key — файл закрытого ключа сервера;
root.crt — файл корневого центра сертификации.

Корневой каталог (/) нельзя использовать в качестве значения CERTIFICATES_PATH

Да, если ключу SSL присвоено true

FULLY_QUALIFIED_DOMAIN_NAME true | false

Указывает способ определения имен хостов в gpload: по полному доменному имени (FQDN) или локальному имени хоста.

Если указано значение true, имена хостов определяются по полному доменному имени; в противном случае, имена определяются по локальным именам. По умолчанию применяется значение false. Использование полных доменных имен может потребоваться в ряде случаев. Например, если Greengage DB и приложение ETL, к которому обращается gpload, находятся в разных доменах

Нет

COLUMNS <field_name>: <data_type>

Указывает схему файлов данных в формате пары из имени столбца и типа данных (field_name:data_type).

Символ разделителя (DELIMITER) в исходном файле разделяет два значения данных (столбца). Строка определяется символом перевода строки (0x0a). Если входные столбцы (COLUMNS) не указаны, то используется схема целевой таблицы (TABLE), что означает, что исходные данные должны иметь тот же порядок столбцов, их количество и формат данных, что и целевая таблица. По умолчанию сопоставление источника и целевой таблицы основано на совпадении имен столбцов, указанных в этом разделе, и имен столбцов в целевой таблице (TABLE).

Это сопоставление по умолчанию можно переопределить с помощью раздела MAPPING

Нет

TRANSFORM '<transformation>'

Указывает имя трансформации, переданной gpload.

Более подробную информацию можно получить в разделе Загрузка с помощью gpload

Нет

TRANSFORM_CONFIG '<configuration-file-path>'

Указывает местоположение файла конфигурации трансформации.

Более подробную информацию можно получить в разделе Файл конфигурации трансформации

Да, если указано значение TRANSFORM

MAX_LINE_LENGTH <integer>

Устанавливает максимальный размер строки данных в байтах, по умолчанию 32768.

Ключ следует использовать, если в данных содержатся очень длинные строки (или при получении сообщения об ошибке line too long). Без необходимости ключ использовать не следует, так как это увеличивает потребление ресурсов. Допустимый диапазон значений — от 32 КБ до 256 МБ. На системах семейства Windows верхний предел составляет 1 МБ

Нет

FORMAT text | csv

Указывает формат исходных данных: текст (TEXT) или значения, разделенные запятыми (CSV). Если значение не указано, по умолчанию применяется TEXT.

Более подробную информацию можно получить в статье Форматирование внешних данных

Нет

DELIMITER '<delimiter_character>'

Указывает ASCII-символ, использующийся в качестве разделителя. Разделитель должен располагаться между полями, но не в начале и не в конце строки.

Вы также можете указать непечатаемый ASCII-символ или Unicode-символ, например \x1B или \u001B. Для непечатаемых символов также поддерживается синтаксис экранирования строк вида E'<код символа>'. ASCII- или Unicode-символ должен быть заключен в одинарные кавычки, например, E'\x1B' или E'\u001B'.

Для текстовых файлов по умолчанию используется знак табуляции (0x09).

Для CSV файлов по умолчанию используется знак запятой (,).

Более подробную информацию можно получить в разделе Форматирование столбцов

Нет

ESCAPE '<escape_character>' | 'OFF'

Указывает символ экранирования.

Для текстовых файлов по умолчанию используется знак обратной косой черты (\). Экранирование можно отключить, указав значение OFF.

Для CSV файлов по умолчанию используется знак кавычек (").

Более подробную информацию можно получить в разделе Символы экранирования

Нет

NEWLINE 'LF' | 'CR' | 'CRLF'

Указывает символ переноса строки и принимает значения LF (символ перевода строки, 0x0A), CR (символ возврата каретки, 0x0D) или CR, совмещенный с LF (CRLF, 0x0D 0x0A).

Если значение не указано, используется символ переноса строки, которым заканчивается первая строка файла данных.

Более подробную информацию можно получить в разделе Форматирование строк

Нет

NULL_AS '<null_string>'

Указывает строку, обозначающую null-значение — неизвестное значение колонки или поля.

Для текстовых файлов по умолчанию используется строка \N.

Для CSV файлов по умолчанию используется пустое значение, не заключенное в кавычки.

Более подробную информацию можно получить в разделе Обработка NULL-значений

Нет

FILL_MISSING_FIELDS true | false

Устанавливает значения NULL для пропущенных полей в конце строки или записи. Если значение не установить, в подобных случаях будет возвращена ошибка. Пустые строки, поля с ограничением NOT NULL и конечные разделители в любом случае вернут ошибку

Нет

FORCE_NOT_NULL ( <column_name> [, …] )

Позволяет обрабатывать значения полей как заключенные в кавычки. Так как null-значение по умолчанию — пустое значение, не заключенное в кавычки, это позволяет обрабатывать отсутствующие значения как пустые строки

Нет

QUOTE '<csv_quote_character>'

Указывает символ кавычек. По умолчанию используется знак двойных кавычек (")

Нет

HEADER true | false

Указывает на наличие заголовка в файле данных.

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

Нет

ENCODING <database_encoding>

Определяет кодировку символов исходных данных. Если значение не указано, используется клиентская кодировка по умолчанию.

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

Более подробную информацию можно получить в разделе Кодировка символов

Нет

ERROR_LIMIT <integer>

Включает для данной загрузки режим изоляции ошибок для одной строки.

При включении этого режима входные строки данных, содержащие ошибки форматирования, отклоняются до тех пор, пока на любом сегменте Greengage DB не будет превышено пороговое значение количества ошибок. Если порог не достигнут, все корректные строки загружаются, а некорректные — отклоняются либо сохраняются в лог ошибок. По умолчанию операция загрузки прерывается при первой ошибке.

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

Нет

LOG_ERRORS true | false

Указывает, сохранять ли в лог информацию об ошибках, если установлено значение ERROR_LIMIT.

Может принимать значения true или false (по умолчанию). Если установлено значение true, то строки данных, содержащие ошибки форматирования, сохраняются во внутренний лог.

Ошибки форматирования можно просмотреть с помощью встроенной SQL-функции gp_read_error_log('<table_name>'). Если при загрузке данных обнаружены ошибки форматирования, gpload выводит предупреждающее сообщение с именем таблицы, содержащей информацию об ошибках.

Если для LOG_ERRORS установлено значение true, то для REUSE_TABLES также требуется установить true, чтобы сохранить ошибки форматирования в логах ошибок Greengage DB. В противном случае, если для REUSE_TABLES установлено значение false или этот ключ не указан, информация об ошибках удаляется после операции gpload.

Возвращается только сводная информация об ошибках форматирования. Вы можете удалить ошибки форматирования из логов ошибок с помощью функции gp_truncate_error_log()

Нет

EXTERNAL

Указывает схему внешних таблиц, создаваемых gpload.

По умолчанию используется схема из search_path Greengage DB

Нет

SCHEMA <schema> | '%'

Имя схемы внешней таблицы. Если схемы с таким именем не найдено, возвращается ошибка. Если указан символ процента (%), используется схема таблицы, указанной для ключа TABLE раздела OUTPUT.

Если в имени таблицы не указано имя схемы, используется схема по умолчанию

Да, если указано значение EXTERNAL

OUTPUT

Определяет целевую таблицу и значения колонок для загрузки в БД

Да

TABLE <schema.table_name>

Указывает целевую таблицу для загрузки данных

Да

MODE insert | update | merge

Определяет режим загрузки данных. Если значение не указано, используется режим INSERT.

Доступны следующие режимы:

INSERT — загружает данные в целевую таблицу путем выполнения запроса SELECT * к внешней таблице, созданной gpload, а затем вставки данных в целевую таблицу с помощью команды INSERT.
UPDATE — обновляет данные в колонках, указанных в UPDATE_COLUMNS, если выполнены следующие условия:
- Значения строк в колонках, указанных в MATCH_COLUMNS, и в исходных данных совпадают.
- Опциональное логическое условие, указанное в UPDATE_CONDITION, принимает значение true.
MERGE — добавляет новые строки и обновляет данные в колонках, указанных в UPDATE_COLUMNS, если выполнены следующие условия:
- Значения строк в колонках, указанных в MATCH_COLUMNS, и в исходных данных совпадают.
- Опциональное логическое условие, указанное в UPDATE_CONDITION, принимает значение true.
Строки считаются новыми, если у значений колонок, указанных в MATCH_COLUMNS, нет совпадающих значений среди имеющихся данных таблицы. В таких случаях в таблицу добавляется полная строка из исходных данных. Если у значений колонок, указанных в MATCH_COLUMNS, несколько совпадающих значений, в таблицу добавляется только одна строка из исходных данных. Для выбора нужной строки используйте логическое условие UPDATE_CONDITION

Нет

MATCH_COLUMNS <target_column_name>

Указывает колонки, которые выступают в роли условий объединения для обновления данных. Для того чтобы произошло обновление данных, значения в целевых колонках должны совпадать с соответствующими значениями колонок исходных данных

Да, если MODE присвоено значение UPDATE или MERGE

UPDATE_COLUMNS <target_column_name>

Указывает колонки, данные в которых будут обновлены при совпадении значений строк в колонках, указанных в MATCH_COLUMNS, и выполнении опционального логического условия, указанного в UPDATE_CONDITION

Да, если MODE присвоено значение UPDATE или MERGE

UPDATE_CONDITION '<boolean_condition>'

Указывает логическое условие (подобное используемым в выражении WHERE), которое должно выполниться, чтобы произошло обновление данных

Нет

MAPPING <source_column_name> | '<expression>'

Переопределяет принцип сопоставления столбцов источника и целевой таблицы.

По умолчанию сопоставление происходит по совпадениям имен столбцов источника, указанных в ключе COLUMNS, и столбцов целевой таблицы, указанной в TABLE.

Выражение указывается в виде пар исходных и целевых столбцов (<target_column_name>: <source_column_name>) или целевых столбцов и выражений (<target_column_name>: '<expression>'). В качестве выражения (<expression>) может выступать любое выражение, подобное используемым в списке SELECT: значение константы, имя столбца, вызов оператора или функции и т.д.

Нет

PRELOAD

Указывает операции, выполняемые перед загрузкой данных. В настоящее время поддерживается только операция TRUNCATE

Нет

TRUNCATE true | false

Если установлено значение true, gpload удаляет все строки целевой таблицы перед загрузкой данных. Значение по умолчанию — false

Нет

REUSE_TABLES true | false

Если установлено значение true, gpload не удаляет созданные им внешние и промежуточные таблицы. Эти объекты задействуются для последующих загрузок, использующих ту же спецификацию, что улучшает производительность постепенных загрузок (периодических небольших загрузок в одну и ту же целевую таблицу).

Если ключу LOG_ERRORS присвоено значение true, то REUSE_TABLES также должно быть присвоено true, чтобы сохранять ошибки форматирования в журналах ошибок Greengage DB. Если REUSE_TABLES присвоено false, информация об ошибках форматирования удаляется после операции gpload

Нет

STAGING_TABLE <external_table_name>

Указывает имя временной внешней таблицы, которая создается при работе gpload. Внешняя таблица используется утилитой gpfdist. Ключу REUSE_TABLES также должно быть присвоено значение true. В противном случае, если REUSE_TABLES не указан или имеет значение false, STAGING_TABLE игнорируется.

По умолчанию gpload создает временную внешнюю таблицу со случайно сгенерированным именем. Если <external_table_name> содержит точку (.), gpload возвращает ошибку. Если таблица существует, gpload использует эту таблицу. Значение SCHEMA в разделе EXTERNAL служит схемой для таблицы <external_table_name>. Утилита возвращает ошибку, если схема существующей таблицы не соответствует схеме таблицы, указанной в OUTPUT.

Если ключу SCHEMA присвоено значение %, то схема для таблицы <external_table_name> совпадает со схемой целевой таблицы, то есть с таблицей, указанной в ключе TABLE раздела OUTPUT.

Если ключ SCHEMA не указан, gpload ищет таблицу, используя схемы в search_path базы данных. Если таблица не найдена, внешняя таблица <external_table_name> создается в схеме по умолчанию (PUBLIC). gpload создает промежуточную таблицу, используя ключи распределения целевой таблицы в качестве ключей распределения для промежуточной таблицы.

Если целевая таблица использует случайное распределение (DISTRIBUTED RANDOMLY), то значение MATCH_COLUMNS служит в качестве ключей распределения промежуточной таблицы

Нет

FAST_MATCH true | false

Если установлено значение true, gpload выполняет поиск внешних таблиц для переиспользования только по базе данных. Если ключу REUSE_TABLES присвоено значение false или ключ не указан, а ключу FAST_MATCH присвоено значение true, gpload выводит предупреждающее сообщение

Нет

SQL

Указывает опциональные произвольные команды SQL, которые запускаются перед (BEFORE) и после (AFTER) операции загрузки данных. Один из возможных сценариев использования раздела — настройка логирования операции загрузки, как описано в примерах

Нет

BEFORE "<sql_command>"

SQL-команда, запускаемая перед операцией загрузки. Команды следует заключать в кавычки

Нет

AFTER "<sql_command>"

SQL-команда, запускаемая после операции загрузки. Команды следует заключать в кавычки

Нет

Лог-файлы, создаваемые утилитой gpload, имеют следующий формат:

<timestamp>|<level>|<message>

Здесь timestamp имеет вид YYYY-MM-DD HH:MM:SS, <level> — один из уровней DEBUG, LOG, INFO, ERROR, а message — текст сообщения.

Некоторые сообщения уровня INFO могут быть особенно полезны при анализе лог-файлов (где # обозначает фактическое количество секунд, единиц данных или неудачных строк):

INFO|running time: <#.##> seconds
INFO|transferred <#.#> kB of <#.#> kB.
INFO|gpload succeeded
INFO|gpload succeeded with warnings
INFO|gpload failed
INFO|1 bad row
INFO|<#> bad rows

Если имена объектов базы данных были созданы с использованием идентификатора в двойных кавычках (идентификатор с разделителем), в управляющем файле gpload такие имена необходимо указывать в одинарных кавычках. Например, если таблица создана так:

CREATE TABLE "MyTable" ("MyColumn" text);

то в YAML-файле управляющей загрузки gpload нужно ссылаться на эти имена таблицы и столбца следующим образом:

- COLUMNS:
   - '"MyColumn"': text
OUTPUT:
   - TABLE: public.'"MyTable"'

gpinitsystem

gplogfilter

gpload

Синтаксис

Требования

Описание

Параметры

Параметры подключения

Формат управляющего файла

Формат лог-файла

Примечания

См. также