版本：Nightly

COPY

COPY TABLE

COPY TO

COPY TO 被用来将表的内容导出到文件中，其语法如下：

COPY tbl TO '/xxx/xxx/output.parquet' WITH (FORMAT = 'parquet');

命令以 COPY 关键字开始，后面跟着要导出数据的表名（本例中为 tbl）。 TO 指定导出数据的文件路径和名称（本例中为 /xxx/xxx/output.parquet）。

NOTE

导出的文件会生成在执行该查询的 GreptimeDB 服务端节点上，而不是发起 SQL 的客户端机器上。请确保路径在服务端可访问且可写，或使用 CONNECTION 导出到 S3、GCS、Azure Blob Storage 等云存储服务。

在单机部署模式下，本地文件路径受限于 storage.copy_root 目录（默认为 <data_home>/copy）；在分布式部署模式下，本地文件访问被完全禁止。详情请参阅迁移本地 SQL 文件访问。

例如，可以使用自定义时间戳和日期格式导出数据到 CSV 或 JSON 文件：

COPY tbl TO '/path/to/file.csv' WITH (
  FORMAT = 'csv',
  TIMESTAMP_FORMAT = '%Y/%m/%d %H:%M:%S',
  DATE_FORMAT = '%Y-%m-%d'
);

COPY tbl TO '/path/to/file.json' WITH (
  FORMAT = 'json',
  TIMESTAMP_FORMAT = '%Y/%m/%d %H:%M:%S',
  DATE_FORMAT = '%Y-%m-%d'
);

也可以将数据导出为压缩的 CSV 或 JSON 文件：

COPY tbl TO '/path/to/file.csv.gz' WITH (
  FORMAT = 'csv',
  COMPRESSION_TYPE = 'gzip'
);

NOTE

使用压缩时，请确保文件扩展名与压缩类型匹配：gzip 使用 .gz，zstd 使用 .zst，bzip2 使用 .bz2，xz 使用 .xz。

`WITH` 选项

WITH 可以添加一些选项，比如文件的 FORMAT 用来指定导出文件的格式。本例中的格式为 Parquet，它是一种用于大数据处理的列式存储格式。Parquet 为大数据分析高效地压缩和编码列式数据。

选项	描述	是否必需
`FORMAT`	目标文件格式，例如 JSON, CSV, Parquet	是
`START_TIME`/`END_TIME`	需要导出数据的时间范围，时间范围为左闭右开	可选
`COMPRESSION_TYPE`	导出文件的压缩算法。支持的值：`gzip`、`zstd`、`bzip2`、`xz`。仅支持 CSV 和 JSON 格式。	可选
`TIMESTAMP_FORMAT`	导出 CSV 或 JSON 格式时自定义时间戳列的格式。使用 strftime 格式说明符（例如 `'%Y-%m-%d %H:%M:%S'`）。支持 CSV 和 JSON 格式。	可选
`DATE_FORMAT`	导出 CSV 或 JSON 格式时自定义日期列的格式。使用 strftime 格式说明符（例如 `'%Y-%m-%d'`）。支持 CSV 和 JSON 格式。	可选
`TIME_FORMAT`	导出 CSV 或 JSON 格式时自定义时间列的格式。使用 strftime 格式说明符（例如 `'%H:%M:%S'`）。支持 CSV 和 JSON 格式。	可选

`CONNECTION` 选项

COPY TO 支持导出数据到云存储上。详情请参考连接 S3、连接 GCS 或连接 Azure Blob Storage。

COPY FROM

COPY FROM 被用来将文件中的数据导入到表中，其语法如下：

COPY [<db>.]<table_name>
FROM { '<path>/[<filename>]' }
[ [ WITH ]
 (
   [ FORMAT =  { 'CSV' | 'JSON' | 'PARQUET' | 'ORC' } ]
   [ PATTERN = '<regex_pattern>' ]
 )
]
[LIMIT NUM]

命令以 COPY 关键字开始，后面跟着要导入数据的表名。

`WITH` 选项

FORMAT 指定导入文件的格式，本例中为 Parquet。

选项 PATTERN 允许使用通配符（如 *）指定匹配某种模式的多个输入文件。例如，你可以使用以下语法导入目录（必须是绝对路径）"/path/to/folder" 中文件名包含 parquet 的所有文件：

COPY tbl FROM '/path/to/folder/' WITH (FORMAT = 'parquet', PATTERN = '.*parquet.*');

例如，如果你只有一个文件需要导入，可以使用下方的语法：

COPY tbl FROM '/path/to/folder/xxx.parquet' WITH (FORMAT = 'parquet');

也可以从压缩的 CSV 或 JSON 文件导入数据：

COPY tbl FROM '/path/to/file.csv.gz' WITH (
  FORMAT = 'csv',
  COMPRESSION_TYPE = 'gzip'
);

导入 CSV 数据时，可以设置 SKIP_BAD_RECORDS = 'true' 跳过解析或类型转换错误的行并继续导入：

COPY tbl FROM '/path/to/file.csv' WITH (
  FORMAT = 'csv',
  SKIP_BAD_RECORDS = 'true'
);

选项	描述	是否必需
`FORMAT`	目标文件格式，例如 JSON, CSV, Parquet, ORC	是
`PATTERN`	使用正则匹配文件，例如 `*_today.parquet`	可选
`COMPRESSION_TYPE`	导入文件的压缩算法。支持的值：`gzip`、`zstd`、`bzip2`、`xz`。仅支持 CSV 和 JSON 格式。	可选
`HEADERS`	CSV 文件是否包含表头。支持的值：`true`、`false`。默认值为 `true`。	可选
`SKIP_BAD_RECORDS`	导入 CSV 时是否跳过解析或类型转换错误的行。支持的值：`true`、`false`。默认值为 `false`。仅支持 CSV 格式。	可选
`STRICT_HEADERS`	导入前是否根据表结构校验 CSV 表头。支持的值：`true`、`false`。默认值为 `false`。仅支持 CSV 格式，且要求 `HEADERS = 'true'`。	可选

NOTE

默认情况下，CSV 会按包含表头的方式解析，并按列名匹配表字段。

如果要导入不包含表头的 CSV 文件，请设置 HEADERS = 'false'。此时会按目标表的字段顺序进行位置映射。你可以使用 SHOW CREATE TABLE <table_name> 查看表字段顺序。

STRICT_HEADERS 选项

默认的表头匹配是宽松的：表里没有的 CSV 列会被忽略，CSV 里没有的表字段则走正常的插入和默认值处理。

设置 STRICT_HEADERS = 'true' 会在读取数据之前先校验表头。出现以下任一情况都会导入失败：

CSV 里有表中不存在的列；
表中有 CSV 里没有的列；
CSV 表头里有重复的列名。

COPY monitor FROM 'monitor.csv' WITH (FORMAT = 'CSV', STRICT_HEADERS = 'true');

不匹配时会一次性报出三类问题：

ERROR:  CSV header mismatch in path: monitor.csv, unknown columns: ["extra"], missing columns: [], duplicate columns: []

注意

缺列检查针对表的全部列，包括可空列和有默认值的列。CSV 少了其中任何一列都会被拒绝。

STRICT_HEADERS = 'true' 不能和 HEADERS = 'false' 同时使用——无表头的 CSV 没有表头可校验，这个组合会返回 strict_headers=true requires headers=true。

Connection 选项

COPY FROM 同样支持从云存储上导入数据。详情请参考连接 S3、连接 GCS 或连接 Azure Blob Storage。

LIMIT 选项

可以通过 LIMIT 手动限制一次插入的最大行数。

连接 S3

你可以从 S3 导入/导出数据

-- COPY FROM
COPY tbl FROM '<URL>' WITH (FORMAT = 'parquet') CONNECTION(REGION = 'us-west-2');

-- COPY TO
COPY tbl TO '<URL>' WITH (FORMAT = 'parquet') CONNECTION(REGION = 'us-west-2');

URL

注意：你应该使用 S3://bucket/key-name 指定文件。下方的例子展示了正确的格式：

S3://my-bucket/data.parquet

另一种方式是使用 Virtual-hosted–style（ENABLE_VIRTUAL_HOST_STYLE 需要设置成 true），例如：

https://bucket-name.s3.region-code.amazonaws.com/key-name

NOTE

可以在 S3 控制台上点击 Copy S3 URI 或者 COPY URL 直接获取对应的 URL/HTTP 前缀或者完整路径。

选项

你可以设置这些 CONNECTION 选项：

选项	描述	是否必需
`REGION`	AWS region 名称，例如 `us-west-2`	是
`ENDPOINT`	The bucket endpoint，例如 `s3.us-west-2.amazonaws.com`	可选
`ACCESS_KEY_ID`	用于连接 AWS S3 兼容的对象存储的访问密钥 ID	可选
`SECRET_ACCESS_KEY`	用于连接 AWS S3 兼容的对象存储的秘密访问密钥	可选
`ENABLE_VIRTUAL_HOST_STYLE`	如果你使用 virtual hosting 的方式来定位 bucket，将该选项设置为 "true"	可选
`SESSION_TOKEN`	用于连接 AWS S3 服务的临时凭证。	可选

连接 GCS

你可以从 Google Cloud Storage (GCS) 导入/导出数据：

-- COPY FROM
COPY tbl FROM 'gcs://<bucket>/<path>' WITH (FORMAT = 'parquet') CONNECTION(SCOPE = 'https://www.googleapis.com/auth/devstorage.read_write');

-- COPY TO
COPY tbl TO 'gcs://<bucket>/<path>' WITH (FORMAT = 'parquet') CONNECTION(SCOPE = 'https://www.googleapis.com/auth/devstorage.read_write');

URL

使用 gcs://bucket/path 指定文件或目录，例如：

gcs://my-bucket/data.parquet

选项

选项	描述	是否必需
`SCOPE`	GCS 访问范围，例如 `https://www.googleapis.com/auth/devstorage.read_write`	可选
`CREDENTIAL`	JSON 格式的服务账号凭证内容	可选
`ENDPOINT`	GCS 服务的 Endpoint	可选

连接 Azure Blob Storage

你可以从 Azure Blob Storage 导入/导出数据：

-- COPY FROM
COPY tbl FROM 'azblob://<container>/<path>' WITH (FORMAT = 'parquet') CONNECTION(ACCOUNT_NAME = 'my-account', ACCOUNT_KEY = 'my-key');

-- COPY TO
COPY tbl TO 'azblob://<container>/<path>' WITH (FORMAT = 'parquet') CONNECTION(ACCOUNT_NAME = 'my-account', ACCOUNT_KEY = 'my-key');

URL

使用 azblob://container/path 指定文件或目录，例如：

azblob://my-container/data.parquet

选项

选项	描述	是否必需
`ACCOUNT_NAME`	Azure 存储账号名称	可选
`ACCOUNT_KEY`	Azure 存储账号密钥	可选
`ENDPOINT`	Azure Blob Storage 服务的 Endpoint	可选
`SAS_TOKEN`	Azure Blob Storage 的共享访问签名（SAS）令牌	可选

COPY 查询结果

你可以使用 COPY 语句将查询结果导出到文件中。语法如下：

COPY (<QUERY>) TO '<PATH>' WITH (FORMAT = { 'CSV' | 'JSON' | 'PARQUET' });

选项	描述	是否必需
`QUERY`	要执行的 SQL SELECT 语句	是
`PATH`	输出文件的路径	是
`FORMAT`	输出文件格式：'CSV'、'JSON' 或 'PARQUET'	是
`COMPRESSION_TYPE`	导出文件的压缩算法。支持的值：`gzip`、`zstd`、`bzip2`、`xz`。仅支持 CSV 和 JSON 格式。	可选
`TIMESTAMP_FORMAT`	导出 CSV 或 JSON 格式时自定义时间戳列的格式。使用 strftime 格式说明符。支持 CSV 和 JSON 格式。	可选
`DATE_FORMAT`	导出 CSV 或 JSON 格式时自定义日期列的格式。使用 strftime 格式说明符。支持 CSV 和 JSON 格式。	可选
`TIME_FORMAT`	导出 CSV 或 JSON 格式时自定义时间列的格式。使用 strftime 格式说明符。支持 CSV 和 JSON 格式。	可选

PostgreSQL `COPY ... TO STDOUT`

当你通过 PostgreSQL 协议连接时，可以使用 COPY (<QUERY>) TO STDOUT 将查询结果流式传输到客户端。这在你希望由 PostgreSQL 客户端（例如 psql）处理输出，而不是在 GreptimeDB 服务端写文件时很有用。选项部分同时支持 PostgreSQL 兼容的 WITH (...) 和直接使用 (...) 两种写法。

COPY (SELECT * FROM tbl WHERE host = 'host1') TO STDOUT;
COPY (SELECT * FROM tbl WHERE host = 'host1') TO STDOUT WITH (FORMAT csv);
COPY (SELECT * FROM tbl WHERE host = 'host1') TO STDOUT (FORMAT binary);

FORMAT 支持 PostgreSQL 文本格式（省略时默认使用）、csv 和 binary。
COPY ... TO STDOUT 仅在 PostgreSQL 协议下支持导出查询结果，也就是 COPY (<QUERY>)。

例如，在 psql 中可以使用 \copy 将流式结果保存到客户端本地文件：

\copy (SELECT * FROM tbl WHERE host = 'host1') TO '/tmp/file.csv' WITH (FORMAT csv)

例如，以下语句将查询结果导出到 CSV 文件中：

COPY (SELECT * FROM tbl WHERE host = 'host1') TO '/path/to/file.csv' WITH (FORMAT = 'csv');

也可以将查询结果导出为压缩文件：

COPY (SELECT * FROM tbl WHERE host = 'host1') TO '/path/to/file.json.gz' WITH (
  FORMAT = 'json',
  COMPRESSION_TYPE = 'gzip'
);

也可以在导出到 CSV 或 JSON 时指定自定义日期和时间格式：

COPY (SELECT * FROM tbl WHERE host = 'host1') TO '/path/to/file.csv' WITH (
  FORMAT = 'csv',
  TIMESTAMP_FORMAT = '%m-%d-%Y %H:%M:%S',
  DATE_FORMAT = '%Y/%m/%d'
);

COPY (SELECT * FROM tbl WHERE host = 'host1') TO '/path/to/file.json' WITH (
  FORMAT = 'json',
  TIMESTAMP_FORMAT = '%m-%d-%Y %H:%M:%S',
  DATE_FORMAT = '%Y/%m/%d'
);

COPY DATABASE

COPY 语句除可以导入/导出表之外，也可以导入/导出指定的数据库，其语法如下：

COPY DATABASE <db_name>
  [TO | FROM] '<PATH>'
  WITH (
    FORMAT =  { 'CSV' | 'JSON' | 'PARQUET' }
    START_TIME = "<START TIMESTAMP>",
    END_TIME = "<END TIMESTAMP>",
    PARALLELISM = <number>
  )
  [CONNECTION(
    REGION = "<REGION NAME>",
    ENDPOINT = "<ENDPOINT>",
    ACCESS_KEY_ID = "<ACCESS KEY>",
    SECRET_ACCESS_KEY = "<SECRET KEY>",
    ENABLE_VIRTUAL_HOST_STYLE = "[true | false]",
  )]

选项	描述	是否必需
`FORMAT`	目标文件格式，例如 JSON, CSV, Parquet	是
`START_TIME`/`END_TIME`	需要导出数据的时间范围，时间范围为左闭右开	可选
`PARALLELISM`	并行处理的表数量。例如，数据库包含 30 个表且 `PARALLELISM` 设置为 8 时，将同时处理 8 个表。默认值为 CPU 核心总数，最小值为 1。	可选

当导入/导出表时，<PATH> 参数必须以 / 结尾；

COPY DATABASE 同样可以通过 CONNECTION 参数将数据导入/导出的路径指向 S3、GCS、Azure Blob Storage 等对象存储

示例

-- 将 public 数据库中所有数据导出到 /tmp/export/ 目录下
COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet');

-- 使用 4 个并行操作导出所有表数据
COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet', PARALLELISM=4);

-- 将 public 数据库中时间范围在 2022-04-11 08:00:00 到 2022-04-11 09:00:00 之间的数据导出到 /tmp/export/ 目录下
COPY DATABASE public TO '/tmp/export/' WITH (FORMAT='parquet', START_TIME='2022-04-11 08:00:00', END_TIME='2022-04-11 09:00:00');

-- 从 /tmp/export/ 目录恢复 public 数据库的数据
COPY DATABASE public FROM '/tmp/export/' WITH (FORMAT='parquet');

-- 使用 8 个并行操作导入数据
COPY DATABASE public FROM '/tmp/export/' WITH (FORMAT='parquet', PARALLELISM=8);

Windows 平台上的路径

请注意，在 Windows 平台上执行 COPY/COPY DATABASE 语句时，请使用 / 代替 <PATH> 中的 \，如 C:/some_dir/output.parquet。

-- 下列语句将会报错
COPY tbl TO 'C:\xxx\xxx\output.parquet' WITH (FORMAT = 'parquet');

-- 下列语句能够正常执行
COPY tbl TO 'C:/xxx/xxx/output.parquet' WITH (FORMAT = 'parquet');

COPY

COPY TABLE​

COPY TO​

WITH 选项​

CONNECTION 选项​

COPY FROM​

WITH 选项​

STRICT_HEADERS 选项​

Connection 选项​

LIMIT 选项​

连接 S3​

URL​

选项​

连接 GCS​

URL​

选项​

连接 Azure Blob Storage​

URL​

选项​

COPY 查询结果​

PostgreSQL COPY ... TO STDOUT​

COPY DATABASE​

示例​

Windows 平台上的路径​

COPY TABLE

COPY TO

`WITH` 选项

`CONNECTION` 选项

COPY FROM

`WITH` 选项

STRICT_HEADERS 选项

Connection 选项

LIMIT 选项

连接 S3

URL

选项

连接 GCS

URL

选项

连接 Azure Blob Storage

URL

选项

COPY 查询结果

PostgreSQL `COPY ... TO STDOUT`

COPY DATABASE

示例

Windows 平台上的路径