IMPORT语句将表格数据(例如CSV)导入到单个表中。

有关import SQL dumps的详细信息,请参阅Import Data

要求

在使用IMPORT之前,你应该准备:

为便于使用,我们建议使用云存储。如果没有的话,我们还提供了[轻松创建自己的文件服务器的指南](https://www.cockroachlabs.com/docs/stable/(/maintain/create-a-file-server/)

细节

导入目标

导入的表事先不能存在,必须在IMPORT语句中创建。 如果要导入的表已存在,则必须使用DROP TABLE删除它。

一次只能导入一个表。

你可以在IMPORT语句中的表名中指定目标数据库。 如果未在此处指定,则使用SQL会话中的active数据库。

创建表

你的IMPORT语句必须包含一个CREATE TABLE语句(表示你要导入的数据的schema),使用以下方法之一:

我们还建议你在CREATE TABLE语句中声明所有二级索引,虽然后续也可以添加二级索引,但在导入期间指定它们要快得多。

CSV数据

要导入的表格数据必须是有效的CSV文件,逗号分隔符可以设置为另一个单个字符。 以下几点尤其需要注意是:

CockroachDB特殊要求:

对象依赖关系

导入表时,必须注意以下规则,因为IMPORT只创建一个不存在的表:

可用存储要求

群集中的每个节点都分配了转换后的CSV数据的相等部分,因此必须有足够的临时空间来存储它。 此外,数据作为普通表保留,因此还必须有足够的空间来容纳最终的复制数据。 节点的第一个列出的/默认的store目录必须有足够的可用存储空间来保存其部分数据。

cockroach start中,如果设置--max-disk-temp-storage,它也必须大于节点将在临时空间中存储的数据部分。

导入文件位置

你可以使用远程云存储(Amazon S3,Google Cloud Platform等)存储要导入的表格数据。 或者,你可以使用从所有节点都可访问的HTTP服务器。

为简单起见,强烈建议将云/远程存储用于你要导入的数据。 虽然支持本地文件但是它们必须可以从群集中的所有节点以相同方式访问。

表用户和权限

导入的表被视为新表,因此你必须具有GRANT权限。

性能

在表格数据转换为kv数据期间使用所有节点,这意味着除了提供正常流量之外,IMPORT任务将消耗所有节点的部分CPU和RAM。

查看和控制导入job

在CockroachDB成功启动导入后,它将导入注册为job,你可以使用SHOW JOBS查看。

导入开始后,你可以使用PAUSE JOBRESUME JOBCANCEL JOB来控制它。

暂停然后恢复IMPORT作业将导致它从头开始重新启动

概要

图片

IMPORT语句不能在事务中使用。

所需权限

只有root用户才能运行IMPORT

参数

Parameter Description
table_name 要导入/创建的表的名称。
create_table_file 包含要使用的CREATE TABLE语句的纯文本文件的URL。(有关语法,请参阅此示例).
table_elem_list 要使用的表定义
file_to_import 要导入的文件的URL。
WITH kv_option 使用这些选项控制导入行为。

导入文件URL

要导入的文件的URL必须使用以下格式:

[scheme]://[host]/[path]?[parameters]
Location scheme host parameters
Amazon S3 s3 Bucket name AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
Azure azure Container name AZURE_ACCOUNT_KEY, AZURE_ACCOUNT_NAME
Google Cloud gs Bucket name AUTH (optional): can be default or implicit
HTTP http Remote host N/A
NFS/Local nodelocal File system location N/A
S3-compatible services s3 Bucket name AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,AWS_REGION, AWS_ENDPOINT

注意事项:

导入选项

你可以使用以下任何kv对作为kv_option来控制IMPORT的行为。

delimiter

如果不使用逗号作为列分隔符,则可以指定另一个Unicode字符作为分隔符。

是否必填? No
Key delimiter
Value 用于分隔行中列的unicode字符
Example 要使用制表符分隔的值: WITH delimiter = e'\ t'

comment

不要导入以此字符开头的行。

是否必填? No
Key comment
Value 标识要跳过的行的unicode字符
Example WITH comment = '#'

nullif

如果值与指定的字符串匹配,则将值转换为SQL NULL

是否必填? No
Key nullif
Value 字符串应转换为 NULL
Example 将空列用作 NULL WITH nullif = ' '

示例

使用文件中的创建表语句

> IMPORT TABLE customers
CREATE USING 'azure://acme-co/customer-create-table.sql?AZURE_ACCOUNT_KEY=hash&AZURE_ACCOUNT_NAME=acme-co'
CSV DATA ('azure://acme-co/customer-import-data.csv?AZURE_ACCOUNT_KEY=hash&AZURE_ACCOUNT_NAME=acme-co')
;

使用Statement中的Create Table Statement

> IMPORT TABLE customers (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        name TEXT,
        INDEX name_idx (name)
)
CSV DATA ('azure://acme-co/customer-import-data.csv?AZURE_ACCOUNT_KEY=hash&AZURE_ACCOUNT_NAME=acme-co')
;

导入制表符分隔文件

> IMPORT TABLE customers (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        name TEXT,
        INDEX name_idx (name)
)
CSV DATA ('azure://acme-co/customer-import-data.tsc?AZURE_ACCOUNT_KEY=hash&AZURE_ACCOUNT_NAME=acme-co')
WITH
    delimiter = e'\t'
;

跳过Commented行

> IMPORT TABLE customers (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        name TEXT,
        INDEX name_idx (name)
)
CSV DATA ('azure://acme-co/customer-import-data.tsc?AZURE_ACCOUNT_KEY=hash&AZURE_ACCOUNT_NAME=acme-co')
WITH
    comment = '#'
;

使用空白字符作为NULL

> IMPORT TABLE customers (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        name TEXT,
        INDEX name_idx (name)
)
CSV DATA ('azure://acme-co/customer-import-data.tsc?AZURE_ACCOUNT_KEY=hash&AZURE_ACCOUNT_NAME=acme-co')
WITH
    nullif = ''
;

已知限制

IMPORT有时会因“context canceled”错误而失败,或者多次重启但从不会完成。 如果发生这种情况,可能是由于磁盘冲突很大。 这可以通过将群集配置kv.bulk_io_write.max_rate设置为低于最大磁盘写入速度的值来缓解。 例如,要将其设置为10MB/s,请执行:

> SET CLUSTER SETTING kv.bulk_io_write.max_rate = '10MB';

See Also