示例
创建表
引擎参数
path— 包含文件路径的存储桶 URL。在readonly模式下支持以下通配符：*、**、?、{abc,def}和{N..M}，其中N、M表示数字，'abc'、'def'表示字符串。更多信息请参见下文。NOSIGN- 如果提供此关键字来代替凭证，则所有请求都不会签名。format— 文件的格式。aws_access_key_id,aws_secret_access_key- AWS 账户用户的长期凭证。你可以使用它们对请求进行身份验证。该参数是可选的。如果未指定凭证，则会使用配置文件中的凭证。更多信息请参见 Using S3 for Data Storage。compression— 压缩类型。支持的值：none、gzip/gz、brotli/br、xz/LZMA、zstd/zst。该参数是可选的。默认情况下，会根据文件扩展名自动检测压缩类型。partition_strategy– 可选值：WILDCARD或HIVE。WILDCARD要求路径中包含{_partition_id}，它会被替换为分区键。HIVE不允许使用通配符，假定该路径是表根路径，并生成 Hive 风格的分区目录，以 Snowflake IDs 作为文件名、文件格式作为扩展名。默认值为file_like_engine_default_partition_strategy设置 (在早于26.6的compatibility设置下为WILDCARD，否则为HIVE) 。partition_columns_in_data_file- 仅与HIVE分区策略一起使用。用于告知 ClickHouse 是否应在数据文件中包含分区列。默认为false。storage_class_name- 可选值：STANDARD或INTELLIGENT_TIERING，可用于指定 AWS S3 Intelligent Tiering。extra_credentials- 可选。用于在 ClickHouse Cloud 中传递用于基于角色的访问控制的role_arn。配置步骤请参见 Secure S3。
数据缓存
S3 表引擎支持将数据缓存在本地磁盘上。
有关文件系统缓存的配置选项和用法，请参见本节。
缓存依据存储对象的 path 和 ETag 确定，因此 ClickHouse 不会读取陈旧的缓存版本。
要启用缓存，请使用设置 filesystem_cache_name = '<name>' 和 enable_filesystem_cache = 1。
- 将以下部分添加到 ClickHouse 配置文件中：
- 复用 ClickHouse 的
storage_configuration部分中的缓存配置 (以及相应的缓存存储) ，此处有说明
PARTITION BY
PARTITION BY —— 可选。在大多数情况下，你不需要分区键；即使需要，通常也无需使用比按月更细的分区键。分区不会加快查询速度 (与 ORDER BY 表达式不同) 。绝不要使用粒度过细的分区。不要按客户标识符或名称对数据进行分区 (应改为将客户标识符或名称作为 ORDER BY 表达式中的第一列) 。
如果按月分区，请使用 toYYYYMM(date_column) 表达式，其中 date_column 是一个 Date 类型的日期列。这里的分区名称采用 "YYYYMM" 格式。
分区策略
WILDCARD：将文件路径中的 {_partition_id} 通配符替换为实际分区键。不支持读取。仅在 compatibility 设置早于 26.6 时默认选用；否则默认值为 HIVE (请参见 file_like_engine_default_partition_strategy 设置) 。
HIVE 在读写时采用 Hive 风格分区。读取通过递归 glob 模式实现，等同于 SELECT * FROM s3('table_root/**.parquet')。
写入会按以下格式生成文件：<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>。
注意：使用 HIVE 分区策略时，use_hive_partitioning 设置不生效。
HIVE 分区策略示例：
查询分区数据
ENGINE 配置中的 S3 端点将参数标记 {_partition_id} 用作 S3 对象 (文件名) 的一部分，而 SELECT 查询则是针对这些生成的对象名进行查询 (例如 test_3.csv) 。
如示例所示，目前尚不直接支持从已分区的 S3 表中查询，
但可以通过使用 S3 表函数查询各个分区来实现。将
分区数据写入 S3 的主要用途，是为了便于将这些数据传输到另一个
ClickHouse 系统中 (例如，从本地系统迁移到 ClickHouse
Cloud) 。由于 ClickHouse 数据集通常非常庞大，而网络
可靠性有时也并不理想，因此按子集传输数据更为合理，
这也正是分区写入的意义所在。
创建表
插入数据
查询分区 3
查询分区 1 中的数据
查询分区 45 中的数据
限制
Select * from p，但如上所述，这条查询会失败；请使用前面的查询语句。
插入数据
s3_truncate_on_insert 和 s3_create_new_file_on_insert 设置。更多详情请参见这里。
虚拟列
_path— 文件路径。类型：LowCardinality(String)。_file— 文件名。类型：LowCardinality(String)。_size— 文件大小 (以字节为单位) 。类型：Nullable(UInt64)。如果大小未知，则值为NULL。_time— 文件的最后修改时间。类型：Nullable(DateTime)。如果时间未知，则值为NULL。_etag— 文件的 ETag。类型：LowCardinality(String)。如果 ETag 未知，则值为NULL。_tags— 文件的标签。类型：Map(String, String)。如果不存在标签，则值为空映射 `’。
实现细节
- 读写可并行进行
- 不支持：
ALTER和SELECT...SAMPLE操作。- 索引。
- 可以进行 Zero-copy 复制，但官方不提供支持。
Zero-copy 复制尚不能用于生产环境在 ClickHouse 22.8 及更高版本中，Zero-copy 复制默认已禁用。不建议在生产环境中使用此功能。
path 中的通配符
path 参数可使用类似 bash 的通配符来指定多个文件。要处理某个文件，该文件必须存在，并且与整个路径模式完全匹配。文件列表是在执行 SELECT 时确定的 (而不是在 CREATE 时) 。
*— 匹配任意数量的任意字符 (/除外) ，也可匹配空字符串。**— 匹配任意数量的任意字符 (包括/) ，也可匹配空字符串。?— 匹配任意单个字符。{some_string,another_string,yet_another_one}— 匹配字符串'some_string'、'another_string'、'yet_another_one'中的任意一个。{N..M}— 匹配从 N 到 M 范围内的任意数字，包含两个边界值。N 和 M 可以带前导零，例如000..078。
{} 的构造与 remote 表函数类似。
如果文件列表包含带前导零的数字范围，请为每一位分别使用大括号构造，或使用
?。file-000.csv、file-001.csv、…、file-999.csv：
- ‘https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some_folder/some_file_1.csv'
- ‘https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some_folder/some_file_2.csv'
- ‘https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some_folder/some_file_3.csv'
- ‘https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another_folder/some_file_1.csv'
- ‘https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another_folder/some_file_2.csv'
- ‘https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another_folder/some_file_3.csv'
- 指定文件后缀的范围：
- 取出所有以
some_file_为前缀的文件 (两个文件夹中都不应有带此前缀的其他文件) ：
- 取两个文件夹中的所有文件 (所有文件都应符合查询中描述的格式和 schema) ：
存储设置
- s3_truncate_on_insert - 允许在插入前先截断文件。默认禁用。
- s3_create_new_file_on_insert - 如果 format 带有 suffix，则允许在每次 insert 时创建新文件。默认禁用。
- s3_skip_empty_files - 允许在读取时跳过空文件。默认启用。
S3 相关设置
s3_max_single_part_upload_size— 使用单段上传向 S3 上传对象时，对象的最大大小。默认值为32Mb。s3_min_upload_part_size— 通过 S3 Multipart upload 进行分段上传时，单个分段的最小大小。默认值为16Mb。s3_max_redirects— 允许的 S3 重定向跳转最大次数。默认值为10。s3_single_read_retries— 单次读取的最大重试次数。默认值为4。s3_max_put_rps— 触发限流前，每秒允许的最大 PUT 请求速率。默认值为0(无限制) 。s3_max_put_burst— 达到每秒请求数限制前，可同时发出的最大请求数。默认情况下 (值为0) 等于s3_max_put_rps。s3_max_get_rps— 触发限流前，每秒允许的最大 GET 请求速率。默认值为0(无限制) 。s3_max_get_burst— 达到每秒请求数限制前，可同时发出的最大请求数。默认情况下 (值为0) 等于s3_max_get_rps。s3_upload_part_size_multiply_factor- 每当单次写入到 S3 已上传s3_multiply_parts_count_threshold个分段时，就将s3_min_upload_part_size乘以该系数。默认值为2。s3_upload_part_size_multiply_parts_count_threshold- 每当上传到 S3 的分段数达到该数值时，s3_min_upload_part_size就会乘以s3_upload_part_size_multiply_factor。默认值为500。s3_max_inflight_parts_for_one_file- 限制单个对象可并发执行的 PUT 请求数量。该数量应加以限制。值0表示无限制。默认值为20。每个正在传输的分段都会占用一个大小为s3_min_upload_part_size的缓冲区，前s3_upload_part_size_multiply_factor个分段如此；如果文件足够大，缓冲区还会更大，参见upload_part_size_multiply_factor。在默认设置下，对于小于8G的文件，单个上传文件的占用不会超过320Mb。文件更大时，占用也会更高。
s3_max_redirects 设为零，以避免 SSRF 攻击；或者，必须在服务器配置中指定 remote_host_filter。
基于端点的设置
endpoint— 指定端点前缀。必填。access_key_idandsecret_access_key— 指定用于该端点的凭据。可选。use_environment_credentials— 如果设为true，S3 客户端会尝试从环境变量和 Amazon EC2 元数据中获取该端点的凭据。可选，默认值为false。region— 指定 S3 区域名称。可选。use_insecure_imds_request— 如果设为true，S3 客户端在从 Amazon EC2 元数据获取凭据时会使用不安全的 IMDS 请求。可选，默认值为false。expiration_window_seconds— 用于检查基于过期时间的凭据是否已过期的宽限期。可选，默认值为120。no_sign_request- 忽略所有凭据，使请求不带签名。适用于访问公共存储桶。header— 向发往该端点的请求添加指定的 HTTP 请求头。可选，可指定多次。access_header- 在没有来自其他来源的凭据时，向发往该端点的请求添加指定的 HTTP 请求头。server_side_encryption_customer_key_base64— 如果指定，将设置访问使用 SSE-C 加密的 S3 对象所需的请求头。可选。server_side_encryption_kms_key_id- 如果指定，将设置访问使用 SSE-KMS encryption 的 S3 对象所需的请求头。如果指定空字符串，将使用 AWS 托管的 S3 密钥。可选。server_side_encryption_kms_encryption_context- 如果与server_side_encryption_kms_key_id一起指定，将设置给定的 SSE-KMS 加密上下文请求头。可选。server_side_encryption_kms_bucket_key_enabled- 如果与server_side_encryption_kms_key_id一起指定，将设置用于为 SSE-KMS 启用 S3 存储桶 key 的请求头。可选，可为true或false，默认不设置 (与存储桶级别设置一致) 。max_single_read_retries— 单次读取的最大重试次数。默认值为4。可选。max_put_rps,max_put_burst,max_get_rpsandmax_get_burst- 用于特定端点而非按查询应用的 throttling 设置 (见上文说明) 。可选。
处理归档文件
- ‘https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip'
- ‘https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip'
- ‘https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip'
ClickHouse 支持三种归档格式：
ZIP
TAR
7Z
虽然 ZIP 和 TAR 归档可以从任何受支持的存储位置访问，但 7Z 归档只能在安装了 ClickHouse 的本地文件系统上读取。
访问公共存储桶
403 错误码。
可以使用 NOSIGN 关键字来避免此问题，强制客户端忽略所有凭证，并且不对请求进行签名。
优化性能
s3 函数性能的详细信息，请参阅详细指南。
基于角色的访问控制
extra_credentials 参数传入 roleARN：
role_arn 一起提供可选的 external_id。它会作为 AWS STS AssumeRole 调用中的 ExternalId 参数传递，使该角色的信任策略可以要求提供一个共享密钥，以缓解混淆代理问题：