Форматирование внешних данных
При загрузке или выгрузке данных с помощью команды COPY, внешней таблицы или утилиты gpload вы можете указать формат данных.
Greengage DB поддерживает следующие форматы данных: текст с разделителями (TEXT
), значения, разделенные запятыми (CSV
), а также бинарный формат.
Вы можете использовать другие форматы, определив собственный формат или протокол.
Указание формата данных
Формат данных определяется с помощью различных выражений для описания форматирования.
Выражение | Описание | Применимость |
---|---|---|
HEADER |
Указывает на наличие заголовка в файле данных. Если используются несколько файлов с данными, то все они должны иметь заголовок. По умолчанию предполагается, что заголовок в файлах данных отсутствует |
Внешняя таблица, COPY, gpload |
NEWLINE |
Указывает символ переноса строки и принимает значения Если значение не указано, используется символ переноса строки, которым заканчивается первая строка файла данных. Более подробную информацию можно получить в разделе Форматирование строк |
Внешняя таблица, COPY, gpload |
DELIMITER |
Указывает ASCII-символ, использующийся в качестве разделителя. Разделитель должен располагаться между полями, но не в начале и не в конце строки. Вы также можете указать непечатаемый ASCII-символ или Unicode-символ, например По умолчанию используется знак табуляции ( Более подробную информацию можно получить в разделе Форматирование столбцов |
Внешняя таблица, COPY, gpload |
NULL |
Указывает строку, обозначающую null-значение — неизвестное значение колонки или поля. По умолчанию используется строка При использовании с утилитой Более подробную информацию можно получить в разделе Обработка NULL-значений |
Внешняя таблица, COPY, gpload |
ESCAPE |
Указывает символ экранирования. По умолчанию используется знак обратной косой черты ( Более подробную информацию можно получить в разделе Символы экранирования |
Внешняя таблица, COPY, gpload |
FILL MISSING FIELDS |
Устанавливает значения |
Внешняя таблица, COPY |
ENCODING |
Определяет кодировку символов исходных данных. Если значение не указано, используется клиентская кодировка по умолчанию. Более подробную информацию можно получить в разделе Кодировка символов |
Внешняя таблица, COPY, gpload |
Выражение | Описание | Применимость |
---|---|---|
HEADER |
Указывает на наличие заголовка в файле данных. Если используются несколько файлов с данными, то все они должны иметь заголовок. По умолчанию предполагается, что заголовок в файлах данных отсутствует |
Внешняя таблица, COPY, gpload |
NEWLINE |
Указывает символ переноса строки и принимает значения Если значение не указано, используется символ переноса строки, которым заканчивается первая строка файла данных. Более подробную информацию можно получить в разделе Форматирование строк |
Внешняя таблица, COPY, gpload |
QUOTE |
Указывает символ кавычек. По умолчанию используется знак двойных кавычек ( |
Внешняя таблица, COPY, gpload |
DELIMITER |
Указывает ASCII-символ, использующийся в качестве разделителя. Разделитель должен располагаться между полями, но не в начале и не в конце строки. Вы также можете указать непечатаемый ASCII-символ или Unicode-символ, например По умолчанию используется знак запятой ( Более подробную информацию можно получить в разделе Форматирование столбцов |
Внешняя таблица, COPY, gpload |
NULL |
Указывает строку, обозначающую null-значение — неизвестное значение колонки или поля. По умолчанию используется пустое значение, не заключенное в кавычки. При использовании с утилитой Более подробную информацию можно получить в разделе Обработка NULL-значений |
Внешняя таблица, COPY, gpload |
FORCE NOT NULL |
Позволяет обрабатывать значения полей как заключенные в кавычки. Так как null-значение по умолчанию — пустое значение, не заключенное в кавычки, это позволяет обрабатывать отсутствующие значения как пустые строки. При использовании с командой |
Внешняя таблица, COPY, gpload |
FORCE_NULL |
Сопоставляет значения указанных столбцов с null-строкой.
При совпадении значение устанавливается в |
COPY |
FORCE QUOTE |
Заключает в кавычки все отличные от Если в качестве значения указан символ При использовании с командой |
Внешняя таблица, COPY |
ESCAPE |
Указывает символ экранирования. По умолчанию используется знак кавычек ( Более подробную информацию можно получить в разделе Символы экранирования |
Внешняя таблица, COPY, gpload |
FILL MISSING FIELDS |
Устанавливает значения |
Внешняя таблица, COPY |
ENCODING |
Определяет кодировку символов исходных данных. Если значение не указано, используется клиентская кодировка по умолчанию. Более подробную информацию можно получить в разделе Кодировка символов |
Внешняя таблица, COPY, gpload |
В команде CREATE EXTERNAL TABLE, COPY или в управляющем файле утилиты gpload
используйте выражения для описания форматирования следующим образом:
CREATE [[READABLE] | WRITABLE] EXTERNAL [WEB] TABLE <table_name>
LOCATION ('<protocol>://<location>) | EXECUTE '<command>'
FORMAT 'TEXT'
[( [HEADER]
[DELIMITER [AS] '<delimiter>' | 'OFF']
[NULL [AS] '<null string>']
[ESCAPE [AS] '<escape>' | 'OFF']
[NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF']
[FILL MISSING FIELDS] )]
| 'CSV'
[( [HEADER]
[QUOTE [AS] '<quote>']
[DELIMITER [AS] '<delimiter>']
[NULL [AS] '<null string>']
[FORCE NOT NULL <column> [, ...]]
[ESCAPE [AS] '<escape>']
[NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF']
[FILL MISSING FIELDS] )]
| 'CUSTOM' (Formatter=<<formatter_specifications>>)
COPY <table_name> [(<column_name> [, ...])]
TO | FROM {'<filename>' | PROGRAM '<command>' | {STDIN | STDOUT}}
[ [ WITH ]
(
FORMAT TEXT | CSV | BINARY,
DELIMITER '<delimiter_character>',
NULL '<null string>',
HEADER [ <boolean> ],
QUOTE '<quote_character>',
NEWLINE '<newline_character>',
ESCAPE '<escape_character>',
FORCE_QUOTE { ( <column_name> [, ...] ) \| * },
FORCE_NOT_NULL ( <column_name> [, ...] ),
FORCE_NULL ( <column_name> [, ...] ),
ENCODING '<encoding_name>'
FILL MISSING FIELDS
) ]
...
GPLOAD:
INPUT:
- SOURCE:
LOCAL_HOSTNAME:
- <hostname_or_ip>
PORT: <http_port>
FILE:
- </path/to/input_file>
- COLUMNS:
- <field_name>: <data_type>
- 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>
...
Форматирование строк
Для работы с Greengage DB строки данных должны быть разделены символом LF
(символ перевода строки, 0x0A
), CR
(символ возврата каретки, 0x0D
) или CR
, совмещенным с LF
(CRLF
, 0x0D 0x0A
).
Символ переноса строки устанавливается с помощью выражения NEWLINE
при указании формата данных.
Если значение не указано, выбирается символ переноса строки, использованный в конце первой строки данных.
В операционных системах UNIX, Linux и macOS используется символ LF
, а в операционных системах семейства Windows — CRLF
.
Форматирование столбцов
Столбцы данных должны быть разделены символом-разделителем.
Разделитель по умолчанию — знак горизонтальной табуляции TAB (0x09
) для текстовых файлов и запятая (0x2C
) для CSV-файлов.
Односимвольный разделитель можно установить с помощью выражения DELIMITER
при указании формата данных.
Символ-разделитель должен находиться между любыми двумя полями значений данных, но не в начале или конце строки.
Пример
В данном примере для копирования содержимого файла suppliers.txt в таблицу suppliers
используется команда COPY
.
В качестве разделителя используется символ вертикальной черты (|
).
-
В каталоге /tmp мастер-хоста создайте файл suppliers.txt:
#!/bin/bash cat > /tmp/suppliers.txt <<EOF id|name|city|country 1|Sunrise Corp|Los Angeles|USA 2|Blue Sky Co|Toronto|Canada 3|Green Leaf LLC|Berlin|Germany 4|Red Rock Group|Sydney|Australia 5|Golden Gate Solutions|Tokyo|Japan EOF
-
Очистите таблицу
suppliers
:TRUNCATE TABLE suppliers;
-
Выполните команду
COPY FROM
. В выраженииWITH
укажитеTEXT
в качестве формата данных, включите пропуск заголовка (HEADER
), а в качестве разделителя (DELIMITER
) укажите символ вертикальной черты (|
):COPY suppliers FROM '/tmp/suppliers.txt' WITH (FORMAT TEXT, HEADER, DELIMITER '|');
-
Выполните запрос к таблице
suppliers
:SELECT * FROM suppliers;
Вывод должен выглядеть следующим образом:
id | name | city | country ----+-----------------------+-------------+----------- 1 | Sunrise Corp | Los Angeles | USA 2 | Blue Sky Co | Toronto | Canada 3 | Green Leaf LLC | Berlin | Germany 4 | Red Rock Group | Sydney | Australia 5 | Golden Gate Solutions | Tokyo | Japan
Обработка NULL-значений
NULL
обозначает неизвестное значение поля.
Для указания строки, представляющей null-значения, используйте выражение NULL
при указании формата данных.
В качестве значения NULL
может выступать произвольная строка, например, пустая строка, если не требуется разделять null-значения и пустые строки.
В текстовых файлах по умолчанию используется строка \N
, а в CSV-файлах — пустое значение, не заключенное в кавычки.
Пример
В данном примере для копирования содержимого файла suppliers.txt в таблицу suppliers
используется команда COPY
.
Значения некоторых полей данных в файле отсутствуют и представлены строкой N/A
.
-
В каталоге /tmp мастер-хоста создайте файл suppliers.txt:
#!/bin/bash cat > /tmp/suppliers.txt <<EOF id,name,city,country 1,Sunrise Corp,Los Angeles,USA 2,Blue Sky Co,N/A,N/A 3,Green Leaf LLC,Berlin,Germany 4,Red Rock Group,Sydney,N/A 5,Golden Gate Solutions,N/A,Japan EOF
-
Очистите таблицу
suppliers
:TRUNCATE TABLE suppliers;
-
Выполните команду
COPY FROM
. В выраженииWITH
укажитеTEXT
в качестве формата данных, включите пропуск заголовка (HEADER
), а в качестве null-строки (NULL
) укажитеN/A
:COPY suppliers FROM '/tmp/suppliers.txt' WITH (FORMAT TEXT, DELIMITER ',', HEADER, NULL 'N/A');
-
Выполните запрос к таблице
suppliers
:SELECT * FROM suppliers;
Вывод должен выглядеть следующим образом:
id | name | city | country ----+-----------------------+-------------+--------- 1 | Sunrise Corp | Los Angeles | USA 2 | Blue Sky Co | | 3 | Green Leaf LLC | Berlin | Germany 4 | Red Rock Group | Sydney | 5 | Golden Gate Solutions | | Japan
Символы экранирования
В Greengage DB символы, указанные в качестве разделителя (DELIMITER
) и переноса строки (NEWLINE
), считаются зарезервированными.
Если эти символы встречаются в данных, их необходимо экранировать.
Если в данных встречается символ экранирования, он должен быть продублирован.
Указать символ экранирования можно с помощью выражения ESCAPE
при указании формата данных.
Символы экранирования в текстовых файлах
По умолчанию в текстовых файлах в качестве символа экранирования используется символ обратной косой черты (\
).
Символ экранирования можно использовать для экранирования восьмеричных и шестнадцатеричных последовательностей.
При загрузке в Greengage DB экранированное значение преобразуется в соответствующий символ.
Например, чтобы загрузить символ амперсанда (&
), экранируйте его эквивалентное шестнадцатеричное (\x26
) или восьмеричное представление (\046
).
Если входные данные (например, данные веб-логов) содержат много символов обратной косой черты, можно отключить экранирование с помощью выражения ESCAPE
, как показано ниже:
COPY suppliers FROM '/tmp/suppliers.txt'
WITH (FORMAT TEXT, HEADER, ESCAPE 'OFF');
Пример
В данном примере для копирования содержимого файла suppliers.txt в таблицу suppliers
используется команда COPY
.
В качестве символа разделителя используется запятая (,
).
-
В каталоге /tmp мастер-хоста создайте файл suppliers.txt. Обратите внимание, что символ запятой встречается в данных, поэтому экранируется с помощью символа экранирования по умолчанию — обратной косой черты (
\
). Символ обратной косой черты также встречается в данных, в этом случае экранирование дублируется:#!/bin/bash cat > /tmp/suppliers.txt <<'EOF' id,name,city,country 1,Acme Inc.,New York,USA 2,Comma\, Inc.,London,GB 3,Backslash \\ Ltd.,Paris,France EOF
-
Очистите таблицу
suppliers
:TRUNCATE TABLE suppliers;
-
Выполните команду
COPY FROM
. В выраженииWITH
укажитеTEXT
в качестве формата данных, включите пропуск заголовка (HEADER
), а в качестве разделителя (DELIMITER
) укажите запятую (,
):COPY suppliers FROM '/tmp/suppliers.txt' WITH (FORMAT TEXT, HEADER, DELIMITER ',');
-
Выполните запрос к таблице
suppliers
:SELECT * FROM suppliers;
Вывод должен выглядеть следующим образом:
id | name | city | country ----+------------------+----------+--------- 1 | Acme Inc. | New York | USA 2 | Comma, Inc. | London | GB 3 | Backslash \ Ltd. | Paris | France
Символы экранирования в файлах CSV
По умолчанию в качестве символа экранирования для файлов в формате CSV используется символ, указанный в качестве значения QUOTE
(по умолчанию двойные кавычки ("
)).
В файлах CSV все символы являются значимыми.
Если значение в кавычках окружено пробелами или любыми символами, отличными от значения DELIMITER
, то эти символы включаются в значение.
Это может привести к ошибкам при импорте данных из системы, которая дополняет строки CSV пробелами до фиксированной ширины.
В этом случае перед импортом данных обработайте файл CSV, удалив завершающие пробелы.
Пример
В данном примере для копирования содержимого файла suppliers.csv в таблицу suppliers
используется команда COPY
.
-
В каталоге /tmp мастер-хоста создайте файл suppliers.csv. Обратите внимание, что значение, содержащее символ запятой, заключено в кавычки. Символы кавычек, содержащиеся в значениях, экранируются с помощью символа экранирование по умолчанию (
"
), при этом само поле также заключается в кавычки. С помощью кавычек также сохраняются пробелы, содержащиеся в данных:#!/bin/bash cat > /tmp/suppliers.csv <<EOF id,name,city,country 1,Acme Inc.,New York,USA 2,"Comma, Inc.",London,GB 3,"""Quotes"" Ltd.",Paris,France 4," Space GmbH",Berlin,Germany EOF
-
Очистите таблицу
suppliers
:TRUNCATE TABLE suppliers;
-
Выполните команду
COPY FROM
. В выраженииWITH
укажитеCSV
в качестве формата данных и включите пропуск заголовка (HEADER
):COPY suppliers FROM '/tmp/suppliers.csv' WITH (FORMAT CSV, HEADER);
-
Выполните запрос к таблице
suppliers
:SELECT * FROM suppliers;
Вывод должен выглядеть следующим образом:
id | name | city | country ----+---------------+----------+--------- 1 | Acme Inc. | New York | USA 2 | Comma, Inc. | London | GB 3 | "Quotes" Ltd. | Paris | France 4 | Space GmbH | Berlin | Germany
Кодировка символов
Системы кодирования символов связывают каждый символ из набора символов с чем-либо еще, например, с последовательностью чисел или байтов, для обеспечения передачи и хранения данных. Greengage DB поддерживает различные кодировки. Вы можете установить кодировку сервера при инициализации базы данных; по умолчанию используется UTF-8.
Клиентские приложения могут использовать все поддерживаемые кодировки, но некоторые из них не поддерживаются для использования на сервере в качестве серверной кодировки. При загрузке или вставке данных в Greengage DB данные преобразуются из указанной клиентской кодировки в серверную кодировку. При отправке данных обратно в клиентское приложение данные преобразуются из серверной кодировки в указанную клиентскую кодировку.
Файлы данных должны использовать кодировку символов, поддерживаемую Greengage DB, иначе при загрузке в Greengage DB возникнут ошибки.
При работе в операционных системах семейства Windows обрабатывайте файлы данных с помощью команды dos2unix
, чтобы убрать Windows-специфичные символы перед загрузкой в Greengage DB.
При изменении значения ENCODING
в управляющем файле gpload необходимо вручную удалить все внешние таблицы, которые были созданы с использованием предыдущей конфигурации ENCODING
.
Утилита gpload
не удаляет и не пересоздает внешние таблицы c использованием нового значения ENCODING
, если параметру REUSE_TABLES
присвоено значение true
.
Кодировку на стороне клиента можно сменить в рамках текущей сессии с помощью параметра конфигурации client_encoding
следующим образом:
SET client_encoding TO 'latin1';
Для просмотра текущей кодировки на стороне клиента выполните следующую команду:
SHOW client_encoding;
Вывод должен выглядеть следующим образом:
client_encoding ----------------- UTF8
Для возвращения кодировки на стороне клиента по умолчанию выполните команду RESET
:
RESET client_encoding;