Привет, Я DocuDroid!
Оценка ИИ поиска
Спасибо за оценку нашего ИИ поиска!
Мы будем признательны, если вы поделитесь своими впечатлениями, чтобы мы могли улучшить наш ИИ поиск для вас и других читателей.
GitHub

Форматирование внешних данных

Антон Монаков

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

Greengage DB поддерживает следующие форматы данных: текст с разделителями (TEXT), значения, разделенные запятыми (CSV), а также бинарный формат. Вы можете использовать другие форматы, определив собственный формат или протокол.

Предварительные требования

Для выполнения примеров из этого раздела подключитесь к мастер-хосту Greengage DB как gpadmin с помощью psql, как описано в статье Подключение к Greengage DB с использованием psql. Затем создайте тестовую базу данных suppliers и подключитесь к ней.

DROP DATABASE IF EXISTS suppliers;
CREATE DATABASE suppliers;
\c suppliers

Затем создайте таблицу suppliers:

CREATE TABLE suppliers
(
    id INTEGER,
    name VARCHAR,
    city VARCHAR,
    country VARCHAR
)
    DISTRIBUTED RANDOMLY;

Указание формата данных

Формат данных определяется с помощью различных выражений для описания форматирования.

Выражение Описание Применимость

HEADER

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

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

Внешняя таблица, COPY, gpload

NEWLINE

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

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

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

Внешняя таблица, COPY, gpload

DELIMITER

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

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

По умолчанию используется знак табуляции (0x09).

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

Внешняя таблица, COPY, gpload

NULL

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

По умолчанию используется строка \N.

При использовании с утилитой gpload указывайте выражение как NULL_AS.

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

Внешняя таблица, COPY, gpload

ESCAPE

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

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

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

Внешняя таблица, COPY, gpload

FILL MISSING FIELDS

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

Внешняя таблица, COPY

ENCODING

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

Внешняя таблица, COPY, gpload

Выражение Описание Применимость

HEADER

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

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

Внешняя таблица, COPY, gpload

NEWLINE

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

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

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

Внешняя таблица, COPY, gpload

QUOTE

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

Внешняя таблица, COPY, gpload

DELIMITER

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

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

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

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

Внешняя таблица, COPY, gpload

NULL

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

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

При использовании с утилитой gpload указывайте выражение как NULL_AS.

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

Внешняя таблица, COPY, gpload

FORCE NOT NULL

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

При использовании с командой COPY или утилитой gpload указывайте выражение как FORCE_NOT_NULL

Внешняя таблица, COPY, gpload

FORCE_NULL

Сопоставляет значения указанных столбцов с null-строкой. При совпадении значение устанавливается в NULL, даже если оно заключено в кавычки. По умолчанию, когда null-строка пуста, заключенная в кавычки пустая строка преобразуется в NULL

COPY

FORCE QUOTE

Заключает в кавычки все отличные от NULL значения в указанных колонках.

Если в качестве значения указан символ *, все отличные от NULL значения заключаются в кавычки во всех колонках. Значения NULL в кавычки не заключаются.

При использовании с командой COPY указывайте выражение как FORCE_QUOTE

Внешняя таблица, COPY

ESCAPE

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

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

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

Внешняя таблица, COPY, gpload

FILL MISSING FIELDS

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

Внешняя таблица, 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. В качестве разделителя используется символ вертикальной черты (|).

  1. В каталоге /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
  2. Очистите таблицу suppliers:

    TRUNCATE TABLE suppliers;
  3. Выполните команду COPY FROM. В выражении WITH укажите TEXT в качестве формата данных, включите пропуск заголовка (HEADER), а в качестве разделителя (DELIMITER) укажите символ вертикальной черты (|):

    COPY suppliers FROM '/tmp/suppliers.txt'
    WITH (FORMAT TEXT, HEADER, DELIMITER '|');
  4. Выполните запрос к таблице 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.

  1. В каталоге /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
  2. Очистите таблицу suppliers:

    TRUNCATE TABLE suppliers;
  3. Выполните команду COPY FROM. В выражении WITH укажите TEXT в качестве формата данных, включите пропуск заголовка (HEADER), а в качестве null-строки (NULL) укажите N/A:

    COPY suppliers FROM '/tmp/suppliers.txt'
    WITH (FORMAT TEXT, DELIMITER ',', HEADER, NULL 'N/A');
  4. Выполните запрос к таблице 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. В качестве символа разделителя используется запятая (,).

  1. В каталоге /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
  2. Очистите таблицу suppliers:

    TRUNCATE TABLE suppliers;
  3. Выполните команду COPY FROM. В выражении WITH укажите TEXT в качестве формата данных, включите пропуск заголовка (HEADER), а в качестве разделителя (DELIMITER) укажите запятую (,):

    COPY suppliers FROM '/tmp/suppliers.txt'
    WITH (FORMAT TEXT, HEADER, DELIMITER ',');
  4. Выполните запрос к таблице 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.

  1. В каталоге /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
  2. Очистите таблицу suppliers:

    TRUNCATE TABLE suppliers;
  3. Выполните команду COPY FROM. В выражении WITH укажите CSV в качестве формата данных и включите пропуск заголовка (HEADER):

    COPY suppliers FROM '/tmp/suppliers.csv'
    WITH (FORMAT CSV, HEADER);
  4. Выполните запрос к таблице 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;