Using a gsql Meta-Command to Import Data

\copy Command

For details about the \copy command, see Table 1.

Parameter Description

• table

  Specifies the name (possibly schema-qualified) of an existing table.

  Value range: an existing table name

• column_list

  Specifies an optional list of columns to be copied.

  Value range: any field in the table. If the column list is not specified, all columns in the table will be copied.

• query

  Specifies that the results will be copied.

  Valid value: a SELECT or VALUES command in parentheses.

• filename

  Specifies the absolute path of a file. To run the \copy command, the user must have the write permission for this path.

• stdin

  Specifies that input comes from the client application.

• stdout

  Specifies that output goes to the client application.

• pstdin

  Specifies that input comes from the gsql client.

• pstout
• Specifies that output goes to the gsql client.
• binary

  Specifies that data is stored and read in binary mode instead of text mode. In binary mode, you cannot declare DELIMITER, NULL, or CSV. After specifying BINARY, CSV, FIXED and TEXT cannot be specified through option or copy_option.

• oid

  Specifies the internal OID to be copied for each row.

  

  An error is raised if OIDs are specified for a table that does not have OIDs, or in the case of copying a query.

  Valid value: true, on, false, and off.

  Default value: false

• delimiter [ as ] 'character'
  Specifies the character that separates columns within each row (line) of the file.

  

  • A delimiter cannot be \r or \n.
  • A delimiter cannot be the same as the null value. The delimiter of CSV data cannot be same as the quote value.
  • The delimiter of TEXT data cannot contain any of the following characters: \.abcdefghijklmnopqrstuvwxyz0123456789
  • The data length of a single row should be less than 1 GB. A row that has many columns using long delimiters cannot contain much valid data.
  • You are advised to use multi-characters and invisible characters for delimiters. For example, you can use the multiple-character delimiter "$^&" and invisible delimiters, such as E'\x07', E'\x08', and E'\x1b'.

  Value range: a multi-character delimiter within 10 bytes.

  Default value:

  • A tab character in TEXT format
  • A comma (,) in CSV format
  • No delimiter in FIXED format
• null [ as ] 'string'

  Specifies that a string represents a null value in a data file.

  Value range:

  • A null value cannot be \r or \n. The maximum length is 100 characters.
  • A null value cannot be the same as the delimiter or quote value.

  Default value:

  • An empty string without quotation marks in CSV format
  • \N in TEXT format
• header

  Specifies whether a data file contains a table header. header is available only for CSV and FIXED files.

  In data import scenarios, if header is on, the first row of the data file will be identified as the header and ignored. If header is off, the first row will be identified as a data row.

  If header is on, fileheader must be specified. fileheader specifies the content in the header. If header is off, the exported file does not contain a header.

  Valid value: true, on, false, and off.

  Default value: false

• quote [ as ] 'character'

  Specifies the quote character for a CSV file.

  Default value: double quotation mark ("").

  

  • The quote value cannot be the same as the delimiter or null value.
  • The quote value must be a single-byte character.
  • You are advised to use invisible characters as quotes, for example, E'\x07', E'\x08', and E'\x1b'.
• escape [ as ] 'character'

  This option is allowed only when using CSV format. This must be a single one-byte character.

  Default value: double quotation mark (""). If the value is the same as the quote value, it will be replaced with \0.

• force quote column_list | *

  In CSV COPY TO mode, forces quoting to be used for all not-null values in each specified column. NULL will not be quoted.

  Value range: an existing column.

• force not null column_list

  In CSV COPY FROM mode, processes each specified column as though it were quoted and hence not a null value.

  Value range: an existing column.

Examples

1. Create a target table, a.

   1	CREATE TABLE a(a int);

2. Import data.
   1. Copy data from stdin to table a.

      \copy a from stdin;

      When the >> characters are displayed, enter data. Enter a backslash and a period (\.) to end your input.

      Enter data to be copied followed by a newline.
      End with a backslash and a period on a line by itself.
      >> 1
      >> 2
      >> \.

      Query data imported to table a.

      1 2 3 4 5 6

      SELECT * FROM a; a --- 1 2 (2 rows)

   2. Copy data from a local file to table a. Assume that the local file is /home/omm/2.csv.
      • Commas (,) are used as delimiters.
      • If the number of columns defined in the source data file is greater than that in a foreign table, extra columns will be ignored during import.

      1	\copy a FROM '/home/omm/2.csv' WITH (delimiter',',IGNORE_EXTRA_DATA 'on');