Help Center > > Developer Guide> Data Import> Using a gsql Meta-Command to Import Data

Using a gsql Meta-Command to Import Data

Updated at: Sep 17, 2021 GMT+08:00

The gsql tool of GaussDB(DWS) provides the \copy meta-command to import data.

\copy Command

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

Table 1 \copy meta-command



\copy { table [ ( column_list ) ] |

( query ) } { from | to } { filename |

stdin | stdout | pstdin | pstdout }

[ with ] [ binary ] [ oids ] [ delimiter

[ as ] 'character' ] [ null [ as ] 'string' ]

[ csv [ header ] [ quote [ as ]

'character' ] [ escape [ as ] 'character' ]

[ force quote column_list | * ] [ force

not null column_list ] ]

You can run this command to import or export data after logging in to the database on any gsql client. Different from the COPY statement in SQL, this command performs read/write operations on local files rather than files on database servers. The accessibility and permissions of the local files are restricted to local users.


\copy only applies to small-batch data import with uniform formats but poor error tolerance capability. GDS or COPY is preferred for data import.

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 multi-characters such as '$^&';, and invisible characters such as 0x07, 0x08, and 0x1b.

    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.
    • Invisible characters are recommended as quote values, such as 0x07, 0x08, and 0x1b.
  • 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.


  1. Create a target table, a.
    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.

      SELECT * FROM a;
      (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.
      \copy a FROM '/home/omm/2.csv' WITH (delimiter',',IGNORE_EXTRA_DATA 'on');

Did you find this page helpful?

Submit successfully!

Thank you for your feedback. Your feedback helps make our documentation better.

Failed to submit the feedback. Please try again later.

Which of the following issues have you encountered?

Please complete at least one feedback item.

Content most length 200 character

Content is empty.

OK Cancel