mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-12-15 02:41:59 +00:00
9.4 KiB
9.4 KiB
sidebar_position | sidebar_label |
---|---|
7 | S3 |
S3 表引擎
这个引擎提供与Amazon S3生态系统的集成。这个引擎类似于HDFS引擎,但提供了 S3 特有的功能。
创建表
CREATE TABLE s3_engine_table (name String, value UInt32)
ENGINE = S3(path, [aws_access_key_id, aws_secret_access_key,] format, [compression])
引擎参数
path
— 带有文件路径的 Bucket url。在只读模式下支持以下通配符:*
,?
,{abc,def}
和{N..M}
其中N
,M
是数字,'abc'
,'def'
是字符串. 更多信息见下文.format
— 文件的格式.aws_access_key_id
,aws_secret_access_key
- AWS 账号的长期凭证. 你可以使用凭证来对你的请求进行认证.参数是可选的. 如果没有指定凭据, 将从配置文件中读取凭据. 更多信息参见 使用 S3 来存储数据.compression
— 压缩类型. 支持的值:none
,gzip/gz
,brotli/br
,xz/LZMA
,zstd/zst
. 参数是可选的. 默认情况下,通过文件扩展名自动检测压缩类型.
示例
- 创建
s3_engine_table
表:
CREATE TABLE s3_engine_table (name String, value UInt32) ENGINE=S3('https://storage.yandexcloud.net/my-test-bucket-768/test-data.csv.gz', 'CSV', 'gzip');
- 填充文件:
INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);
- 查询数据:
SELECT * FROM s3_engine_table LIMIT 2;
┌─name─┬─value─┐
│ one │ 1 │
│ two │ 2 │
└──────┴───────┘
虚拟列
_path
— 文件路径._file
— 文件名.
有关虚拟列的更多信息,见 这里.
实施细节
- 读取和写入可以是并行的
- 以下是不支持的:
ALTER
和SELECT...SAMPLE
操作.- 索引.
- 复制.
路径中的通配符
path
参数可以使用类 bash 的通配符来指定多个文件。对于正在处理的文件应该存在并匹配到整个路径模式。 文件列表的确定是在 SELECT
的时候进行(而不是在 CREATE
的时候)。
*
— 替代任何数量的任何字符,除了/
以及空字符串。?
— 代替任何单个字符.{some_string,another_string,yet_another_one}
— 替代'some_string', 'another_string', 'yet_another_one'
字符串.{N..M}
— 替换 N 到 M 范围内的任何数字,包括两个边界的值. N 和 M 可以以 0 开头,比如000..078
带 {}
的结构类似于 远程 表函数。
示例
- 假设我们在 S3 上有几个 CSV 格式的文件,URI如下:
- ‘https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_1.csv’
- ‘https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_2.csv’
- ‘https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_3.csv’
- ‘https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_1.csv’
- ‘https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_2.csv’
- ‘https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_3.csv’
有几种方法来创建由所有六个文件组成的数据表:
第一种方式:
CREATE TABLE table_with_range (name String, value UInt32) ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}', 'CSV');
另一种方式:
CREATE TABLE table_with_question_mark (name String, value UInt32) ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_?', 'CSV');
表由两个目录中的所有文件组成(所有文件应满足查询中描述的格式和模式)。
CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/*', 'CSV');
如果文件列表中包含有从零开头的数字范围,请对每个数字分别使用带括号的结构,或者使用?
。
示例
使用文件file-000.csv
, file-001.csv
, … , file-999.csv
来创建表:
CREATE TABLE big_table (name String, value UInt32) ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV');
虚拟列
_path
— 文件路径._file
— 文件名.
另请参阅
S3 相关的设置
以下设置可以在查询执行前设置,也可以放在配置文件中。
s3_max_single_part_upload_size
- 使用单文件上传至 S3 的对象的最大文件大小。默认值是64Mb
。s3_min_upload_part_size
- 使用S3多文件块上传时,文件块的最小文件大小。默认值是512Mb
。s3_max_redirects
- 允许的最大S3重定向跳数。默认值是10
。s3_single_read_retries
- 单次读取时的最大尝试次数。默认值是4
。
安全考虑:如果恶意用户可以指定任意的 S3 网址,s3_max_redirects
参数必须设置为零,以避免SSRF攻击;或者,必须在服务器配置中指定remote_host_filter
。
基于 Endpoint 的设置
在配置文件中可以为给定的端点指定以下设置(将通过URL的准确前缀来匹配)。
endpoint
- 指定一个端点的前缀。必要参数。access_key_id
和secret_access_key
- 用于指定端点的登陆凭据。可选参数。use_environment_credentials
- 如果设置为true
,S3客户端将尝试从环境变量和Amazon EC2元数据中为指定的端点获取证书。可选参数,默认值是false
。region
- 指定S3的区域名称。可选参数。use_insecure_imds_request
- 如果设置为true
,S3客户端将使用不安全的 IMDS 请求,同时从Amazon EC2 元数据获取证书。可选参数,默认值是false
。header
- 添加指定的HTTP头到给定端点的请求中。可选参数,可以使用多次此参数来添加多个值。server_side_encryption_customer_key_base64
- 如果指定,需要指定访问 SSE-C 加密的 S3 对象所需的头信息。可选参数。max_single_read_retries
- 单次读取时的最大尝试次数。默认值是4
。可选参数。
示例:
<s3>
<endpoint-name>
<endpoint>https://storage.yandexcloud.net/my-test-bucket-768/</endpoint>
<!-- <access_key_id>ACCESS_KEY_ID</access_key_id> -->
<!-- <secret_access_key>SECRET_ACCESS_KEY</secret_access_key> -->
<!-- <region>us-west-1</region> -->
<!-- <use_environment_credentials>false</use_environment_credentials> -->
<!-- <use_insecure_imds_request>false</use_insecure_imds_request> -->
<!-- <header>Authorization: Bearer SOME-TOKEN</header> -->
<!-- <server_side_encryption_customer_key_base64>BASE64-ENCODED-KEY</server_side_encryption_customer_key_base64> -->
<!-- <max_single_read_retries>4</max_single_read_retries> -->
</endpoint-name>
</s3>
用法
假设我们在 S3 上有几个 CSV 格式的文件,URI 如下:
- 'https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_1.csv'
- 'https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_2.csv'
- 'https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_3.csv'
- 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_1.csv'
- 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_2.csv'
- 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_3.csv'
- 有几种方式来制作由所有六个文件组成的表格,其中一种方式如下:
CREATE TABLE table_with_range (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}', 'CSV');
- 另一种方式:
CREATE TABLE table_with_question_mark (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_?', 'CSV');
- 表由两个目录中的所有文件组成(所有文件应满足查询中描述的格式和模式):
CREATE TABLE table_with_asterisk (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/*', 'CSV');
!!! warning "Warning"
如果文件列表中包含有从0开头的数字范围,请对每个数字分别使用带括号的结构,或者使用?
.
- 从文件
file-000.csv
,file-001.csv
, … ,file-999.csv
创建表:
CREATE TABLE big_table (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV');