httpfs 扩展支持使用 S3 API 在对象存储服务器上读取/写入/globbing 文件。S3 提供了一个标准 API 来读取和写入远程文件（而早于 S3 的常规 http 服务器不提供通用的写入 API）。DuckDB 符合 S3 API，该 API 现在在行业存储提供商中很常见。

Platforms

httpfs 文件系统已通过 AWS S3、Minio、Google Cloud 和 lakeFS 进行测试。其他实现 S3 API 的服务（如 Cloudflare R2）也应该可以工作，但可能不支持所有功能。

下表显示了每个httpfs功能所需的S3 API部分。

配置和认证

配置和验证S3端点的首选方法是使用secrets。有多种秘密提供者可供选择。

在0.10.0版本之前，DuckDB没有Secrets manager。因此，S3端点的配置和认证是通过变量处理的。请参阅S3 API的旧版认证方案。

CONFIG Provider

默认提供者，CONFIG（即用户配置），允许通过手动提供密钥来访问S3存储桶。例如：

CREATE SECRET secret1 (
    TYPE S3,
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    REGION 'us-east-1'
);

提示 如果您遇到IO错误（Connection error for HTTP HEAD），请通过ENDPOINT 's3.⟨your-region⟩.amazonaws.com'显式配置端点。

现在，要使用上述密钥进行查询，只需查询任何以s3://为前缀的文件：

SELECT *
FROM 's3://my-bucket/file.parquet';

CREDENTIAL_CHAIN Provider

CREDENTIAL_CHAIN 提供者允许使用 AWS SDK 提供的机制自动获取凭证。例如，要使用 AWS SDK 默认提供者：

CREATE SECRET secret2 (
    TYPE S3,
    PROVIDER CREDENTIAL_CHAIN
);

再次，要使用上述密钥查询文件，只需查询任何以s3://为前缀的文件。

DuckDB also allows specifying a specific chain using the CHAIN keyword. This takes a semicolon-separated list (a;b;c) of providers that will be tried in order. For example:

CREATE SECRET secret3 (
    TYPE S3,
    PROVIDER CREDENTIAL_CHAIN,
    CHAIN 'env;config'
);

CHAIN 的可能值如下：

• config
• sts
• sso
• env
• instance
• process

CREDENTIAL_CHAIN 提供程序还允许覆盖自动获取的配置。例如，要自动加载凭据，然后覆盖区域，请运行：

CREATE SECRET secret4 (
    TYPE S3,
    PROVIDER CREDENTIAL_CHAIN,
    CHAIN 'config',
    REGION 'eu-west-1'
);

S3 密钥参数概述

以下是可用于CONFIG和CREDENTIAL_CHAIN提供者的支持参数的完整列表：

平台特定的秘密类型

R2 Secrets

虽然Cloudflare R2使用常规的S3 API，但DuckDB有一个特殊的Secret类型，R2，以使其配置更简单：

CREATE SECRET secret5 (
    TYPE R2,
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    ACCOUNT_ID 'my_account_id'
);

注意添加了ACCOUNT_ID，它用于为您生成正确的端点URL。还要注意，对于R2，Secrets也可以同时使用CONFIG和CREDENTIAL_CHAIN提供者。最后，R2 secrets仅在使用的URL以r2://开头时可用，例如：

SELECT *
FROM read_parquet('r2://some/file/that/uses/r2/secret/file.parquet');

GCS 密钥

虽然Google Cloud Storage通过S3 API被DuckDB访问，但DuckDB有一个特殊的Secret类型，GCS，以使其配置更简单：

CREATE SECRET secret6 (
    TYPE GCS,
    KEY_ID 'my_key',
    SECRET 'my_secret'
);

请注意，上述密钥将自动配置正确的Google Cloud Storage端点。还要注意，对于GCS，密钥也可以使用CONFIG和CREDENTIAL_CHAIN提供者。最后，GCS密钥仅在使用的URL以gcs://或gs://开头时可用，例如：

SELECT *
FROM read_parquet('gcs://some/file/that/uses/gcs/secret/file.parquet');

阅读

从S3读取文件现在变得如此简单：

SELECT *
FROM 's3://bucket/file.extension';

Partial Reading

httpfs 扩展支持从 S3 存储桶进行部分读取。

读取多个文件

多个文件也是可能的，例如：

SELECT *
FROM read_parquet([
    's3://bucket/file1.parquet',
    's3://bucket/file2.parquet'
]);

Globbing

文件globbing是通过ListObjectV2 API调用实现的，允许使用类似文件系统的通配符模式来匹配多个文件，例如：

SELECT *
FROM read_parquet('s3://bucket/*.parquet');

此查询匹配存储桶根目录中所有具有Parquet扩展的文件。

支持多种匹配功能，例如 * 用于匹配任意数量的任意字符，? 用于匹配任意单个字符，或 [0-9] 用于匹配字符范围内的单个字符：

SELECT count(*) FROM read_parquet('s3://bucket/folder*/100?/t[0-9].parquet');

使用通配符时的一个有用特性是filename选项，它添加了一个名为filename的列，该列编码了特定行源自的文件：

SELECT *
FROM read_parquet('s3://bucket/*.parquet', filename = true);

例如可能导致：

Hive 分区

DuckDB 还提供了对 Hive 分区方案 的支持，该方案在使用 HTTP(S) 和 S3 端点时可用。

Writing

写入S3使用多部分上传API。这使得DuckDB能够以高速稳健地上传文件。写入S3适用于CSV和Parquet：

COPY table_name TO 's3://bucket/file.extension';

分区复制到 S3 也有效：

COPY table TO 's3://my-bucket/partitioned' (
    FORMAT PARQUET,
    PARTITION_BY (part_col_a, part_col_b)
);

对现有文件/目录执行自动检查，目前相当保守（在S3上会增加一些延迟）。要禁用此检查并强制写入，添加了一个OVERWRITE_OR_IGNORE标志：

COPY table TO 's3://my-bucket/partitioned' (
    FORMAT PARQUET,
    PARTITION_BY (part_col_a, part_col_b),
    OVERWRITE_OR_IGNORE true
);

写入文件的命名方案如下所示：

s3://my-bucket/partitioned/part_col_a=⟨val⟩/part_col_b=⟨val⟩/data_⟨thread_number⟩.parquet

Configuration

S3上传存在一些额外的配置选项，尽管默认值应该足以满足大多数用例。