COPY — copy data between a file and a table
COPYtable_name[ (column_name[, ...] ) ] FROM { 'filename' } [ [ WITH ] (option[, ...] ) ] whereoptioncan be one of: FORMATformat_nameDELIMITER 'delimiter_character' NULL 'null_string' HEADER [boolean] QUOTE 'quote_character' ESCAPE 'escape_character' FORCE_NOT_NULL (column_name[, ...] ) FORCE_NULL (column_name[, ...] )
COPY moves data between
Hyper tables and standard file-system
files. COPY FROM copies
data from a file to a table, appending the data to
whatever is in the table already.
If a column list is specified, each field in the file is inserted, in order, into the specified column. Table columns not specified in the COPY FROM column list will receive their default values.
COPY with a file name instructs the
Hyper server to directly read from a file. The file must be accessible by the
Hyper user (the user ID the server
runs as) and the name must be specified from the viewpoint of the
server.
table_nameThe name (optionally database- or schema-qualified) of an existing table.
column_nameAn optional list of columns to be copied. If no column list is specified, all columns of the table will be copied.
filename
The path name of the input output file. An input file name can be
an absolute or relative path. Windows users might need to use an E'' string and
double any backslashes used in the path name.
boolean
Specifies whether the selected option should be turned on or off.
You can write TRUE, ON, or
1 to enable the option, and FALSE,
OFF, or 0 to disable it. The
boolean value can also
be omitted, in which case TRUE is assumed.
FORMAT
Selects the data format to be read or written:
text,
csv (Comma-Separated Values), or
parquet (Apache Parquet; if the experimental_external_format_parquet setting is enabled).
The default is text.
DELIMITER
Specifies the character that separates columns within each row
(line) of the file. The default is a tab character in text format,
a comma in CSV format.
This must be a single one-byte character.
NULL
Specifies the string that represents a null value. The default is
\N (backslash-N) in text format, and an unquoted empty
string in CSV format. You might prefer an
empty string even in text format for cases where you don't want to
distinguish nulls from empty strings.
HEADER
Specifies that the file contains a header line with the names of each
column in the file. On output, the first line contains the column
names from the table, and on input, the first line is ignored.
This option is allowed only when using CSV format.
QUOTE
Specifies the quoting character to be used when a data value is quoted.
The default is double-quote.
This must be a single one-byte character.
This option is allowed only when using CSV format.
ESCAPE
Specifies the character that should appear before a
data character that matches the QUOTE value.
The default is the same as the QUOTE value (so that
the quoting character is doubled if it appears in the data).
This must be a single one-byte character.
This option is allowed only when using CSV format.
FORCE_NOT_NULL
Do not match the specified columns' values against the null string.
In the default case where the null string is empty, this means that
empty values will be read as zero-length strings rather than nulls,
even when they are not quoted.
This option is allowed only in COPY FROM, and only when
using CSV format.
FORCE_NULL
Match the specified columns' values against the null string, even
if it has been quoted, and if a match is found set the value to
NULL. In the default case where the null string is empty,
this converts a quoted empty string into NULL.
This option is allowed only in COPY FROM, and only when
using CSV format.
Files named in a COPY command are read directly by the server, not by the client application. Therefore,
they must reside on or be accessible to the database server machine,
not the client. They must be accessible to and readable
by the Hyper user (the user ID the
server runs as), not the client.
COPY FROM currently only accepts data encoded in UTF-8 without a byte order mark.
COPY FROM will invoke any check
constraints on the destination table.
COPY input and output is affected by
date_style.
COPY stops operation at the first error.
FORCE_NULL and FORCE_NOT_NULL can be used
simultaneously on the same column. This results in converting only quoted
null strings to null values while unquoted null strings remain unchanged.
When the text format is used,
the data read or written is a text file with one line per table row.
Columns in a row are separated by the delimiter character.
The column values themselves are strings generated by the
output function, or acceptable to the input function, of each
attribute's data type. The specified null string is used in
place of columns that are null.
COPY FROM will raise an error if any line of the
input file contains more or fewer columns than are expected.
Backslash characters (\) can be used in the
COPY data to quote data characters that might
otherwise be taken as row or column delimiters. In particular, the
following characters must be preceded by a backslash if
they appear as part of a column value: backslash itself,
newline, carriage return, and the current delimiter character.
COPY FROM matches
the input against the null string before removing backslashes. Therefore,
a null string such as \N cannot be confused with
the actual data value \N (which would be represented
as \\N).
The following special backslash sequences are recognized by
COPY FROM:
| Sequence | Represents |
|---|---|
\b | Backspace (ASCII 8) |
\f | Form feed (ASCII 12) |
\n | Newline (ASCII 10) |
\r | Carriage return (ASCII 13) |
\t | Tab (ASCII 9) |
\v | Vertical tab (ASCII 11) |
\digits | Backslash followed by one to three octal digits specifies the character with that numeric code |
\xdigits | Backslash x followed by one or two hex digits specifies
the character with that numeric code |
It is strongly recommended that applications generating COPY data convert
data newlines and carriage returns to the \n and
\r sequences respectively. At present it is
possible to represent a data carriage return by a backslash and carriage
return, and to represent a data newline by a backslash and newline.
However, these representations might not be accepted in future releases.
They are also highly vulnerable to corruption if the COPY file is
transferred across different machines (for example, from Unix to Windows
or vice versa).
This format option is used for importing the Comma
Separated Value (CSV) file format used by many other
programs, such as spreadsheets. Instead of the escaping rules used by
Hyper's standard text format, it
produces and recognizes the common CSV escaping mechanism.
The values in each record are separated by the DELIMITER
character. If the value contains the delimiter character, the
QUOTE character, the NULL string, a carriage
return, or line feed character, then the whole value is prefixed and
suffixed by the QUOTE character, and any occurrence
within the value of a QUOTE character or the
ESCAPE character is preceded by the escape character.
The CSV format has no standard way to distinguish a
NULL value from an empty string.
Hyper's COPY handles this by quoting.
A NULL is output as the NULL parameter string
and is not quoted, while a non-NULL value matching the
NULL parameter string is quoted. For example, with the
default settings, a NULL is written as an unquoted empty
string, while an empty string data value is written with double quotes
(""). Reading values follows similar rules. You can
use FORCE_NOT_NULL to prevent NULL input
comparisons for specific columns. You can also use
FORCE_NULL to convert quoted null string data values to
NULL.
In CSV format, all characters are significant. A quoted value
surrounded by white space, or any characters other than
DELIMITER, will include those characters. This can cause
errors if you import data from a system that pads CSV
lines with white space out to some fixed width. If such a situation
arises you might need to preprocess the CSV file to remove
the trailing white space, before importing the data into
Hyper.
CSV format will recognize CSV files with quoted values containing embedded carriage returns and line feeds. Thus the files are not strictly one line per table row like text-format files.
The parquet format option causes the data to be read in the Apache Parquet format.
The parquet option is experimental.
It is only available if the experimental_external_format_parquet setting is enabled.
There is no COPY statement in the SQL standard.