从存储桶导入数据

使用 COPY INTO 可将对象存储桶中的文件导入 Databend。从 Amazon S3 通过 SQL 导入时，请从本教程开始。本教程使用一个 Parquet 示例文件。其他格式请参阅输入输出文件格式。

任务路径：准备 S3 数据 → 选择认证方式 → 连接并验证 → 导入示例数据。

备注

本教程介绍通过 SQL 导入。如需通过 Cloud 控制台定时导入，请参阅 Amazon S3 集成任务。如需使用 S3 事件通知，请参阅 Amazon SQS (S3) 集成任务。

准备 S3 数据

配置访问权限前，请准备以下内容：

• 一个 S3 存储桶及其 AWS 区域。本教程使用 us-east-2 区域的 databend-toronto。请替换为您的实际配置。
• 所选认证方式需要的 AWS 权限。IAM 角色需要创建策略和角色，访问密钥需要创建策略、IAM 用户和访问密钥。如无此权限，请让 AWS 管理员执行这些任务。不要使用 AWS 根用户访问密钥。
• 在 Databend 中创建 Connection、Stage 和表的权限。

下载 books.parquet。该文件包含两条记录：

books.parquet

Transaction Processing,Jim Gray,1992
Readings in Database Systems,Michael Stonebraker,2004

将文件上传到存储桶中的 load/books.parquet。请保持对象为私有。无需关闭 S3 的“阻止公共访问”。

AWS 操作请参阅创建存储桶和上传对象。

选择认证方式

选择一种认证方式完成配置。两种方式共用下方的 Stage、验证查询和导入 SQL。

方式	适用场景	配置及下一步
IAM 角色（Databend Cloud 推荐）	使用 AWS 临时凭证，无需在 Databend 中保存访问密钥。	完成 AWS IAM 角色授权后，返回创建 Connection 和 Stage，选择 IAM 角色。
访问密钥	角色访问不适合您的部署时，使用 IAM 用户的访问密钥。	完成配置访问密钥后，在创建 Connection 和 Stage中选择访问密钥。

Connection 保存可复用的认证参数，Stage 指定 S3 位置。创建 Connection 不是一种独立的 AWS 认证方式。

配置访问密钥

使用 IAM 角色时，请跳过此任务。如果已有权限合适的 IAM 用户和访问密钥，可直接创建 Connection 和 Stage。

创建只读策略、IAM 用户和访问密钥

创建只读权限策略

在 AWS IAM 控制台中，进入策略 → 创建策略 → JSON。

将以下策略粘贴到编辑器中。将 databend-toronto 和 load/ 替换为您的存储桶和前缀。将策略保存为 databend-s3-user-read。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetBucketRegion",
      "Effect": "Allow",
      "Action": "s3:GetBucketLocation",
      "Resource": "arn:aws:s3:::databend-toronto"
    },
    {
      "Sid": "ListLoadPrefix",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::databend-toronto",
      "Condition": {
        "StringLike": {
          "s3:prefix": ["load/", "load/*"]
        }
      }
    },
    {
      "Sid": "ReadLoadObjects",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::databend-toronto/load/*"
    }
  ]
}

此策略仅允许列出和读取指定前缀，不允许上传或删除。如需访问 KMS 加密对象或写入数据，请参阅附加权限。

创建 IAM 用户

在 IAM 控制台中，进入用户 → 创建用户，使用以下配置：

配置项	值
用户名	databend-s3-reader
AWS 管理控制台访问	不启用
权限	直接附加策略 → databend-s3-user-read

检查配置后，选择创建用户。

创建并保存访问密钥

在用户详情页中，进入安全凭证 → 访问密钥 → 创建访问密钥。

将使用案例设为第三方服务，按向导完成密钥创建。将访问密钥 ID 和秘密访问密钥保存到您组织批准使用的密钥管理工具中。

注意

AWS 仅在创建时显示秘密访问密钥。不要将真实密钥放入截图、代码仓库、支持工单或共享 SQL 示例。SQL 客户端和工作表可能保留语句文本。输入凭证时，请遵循您组织的密钥管理规范。

创建 Connection 和 Stage

打开 Databend Cloud 工作表，或通过 BendSQL 连接。在下方选择认证方式，并将示例值替换为您的实际配置。

IAM 角色

使用 AWS IAM 角色授权中准备的客户 IAM 角色 ARN 和匹配的外部 ID。不要将 Databend Cloud 主体 ARN 填入 ROLE_ARN。

CREATE CONNECTION s3_books_conn
    STORAGE_TYPE = 's3'
    ROLE_ARN = 'arn:aws:iam::987654321987:role/databend-docs-s3-role'
    EXTERNAL_ID = 'my-external-id-123'
    REGION = 'us-east-2';

访问密钥

使用配置访问密钥中获取的 IAM 用户访问密钥。

CREATE CONNECTION s3_books_conn
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-access-key-id>'
    SECRET_ACCESS_KEY = '<your-secret-access-key>'
    REGION = 'us-east-2';

为已授权的前缀创建一个 Stage。两种认证方式使用相同的 SQL：

CREATE STAGE s3_books_stage
    URL = 's3://databend-toronto/load/'
    CONNECTION = (CONNECTION_NAME = 's3_books_conn');

请保留 Stage URL 末尾的 /。访问范围由 AWS 策略强制限制。仅设置 Connection 名称和 Stage URL 不会将凭证的权限限制在该路径内。

验证 S3 访问

列出 Stage 中的文件：

LIST @s3_books_stage;

结果应包含 books.parquet。读取文件以检查对象访问权限：

SELECT title::VARCHAR AS title,
       author::VARCHAR AS author,
       date::VARCHAR AS date
FROM @s3_books_stage/books.parquet
LIMIT 2;

结果应包含两条示例记录。列举用于检查 s3:ListBucket，读取还会检查 s3:GetObject 及所需的 KMS 解密权限。导入前，请先修复认证或权限错误。

角色代入错误请参阅 IAM 角色故障排查。其他错误请参阅下方的故障排查。

导入示例数据

在您有相应权限的数据库中创建测试表：

CREATE TABLE books
(
    title VARCHAR,
    author VARCHAR,
    date VARCHAR
);

导入并检查结果

仅导入示例文件，并保持源文件删除功能关闭：

COPY INTO books
FROM @s3_books_stage
FILES = ('books.parquet')
FILE_FORMAT = (TYPE = 'PARQUET')
PURGE = FALSE;

检查已导入的数据：

SELECT * FROM books ORDER BY title;

预期记录：

title                       |author             |date|
----------------------------+-------------------+----+
Readings in Database Systems|Michael Stonebraker|2004|
Transaction Processing      |Jim Gray           |1992|

故障排查

现象	检查项
AssumeRole 失败，或 STS 返回 AccessDenied	检查角色 ARN、受信任的 Databend 主体和外部 ID。参阅 IAM 角色故障排查。
InvalidAccessKeyId 或 SignatureDoesNotMatch	检查访问密钥 ID 和秘密访问密钥。确认密钥处于有效状态。复制时不要添加空白字符。
LIST 返回 AccessDenied	检查存储桶 ARN 的 s3:ListBucket 权限和 s3:prefix 条件。检查存储桶策略、组织策略或端点策略是否存在显式拒绝。
列举成功，但读取失败	检查对象 ARN 的 s3:GetObject 权限。对于 KMS 加密对象，还需检查 kms:Decrypt 和 KMS 密钥策略。
未显示任何文件	检查文件是否位于 load/books.parquet，以及 Stage URL 是否以 /load/ 结尾。
出现端点或区域错误	将 REGION 设为存储桶所在的 AWS 区域。
SQL 提示权限不足	检查当前 Databend 角色及其 Connection、Stage 或表权限。这些权限与 AWS 权限相互独立。

轮换凭证或清理资源

Stage 通常会在创建时复制 Connection 参数。替换 Connection 不会更新这些已保存的参数。修改角色、外部 ID 或访问密钥后，请使用新的 Connection 参数重新创建受影响的 Stage。撤销旧配置前，请先验证访问。详情请参阅 CREATE CONNECTION。

运行以下语句可移除 Databend 测试对象：

DROP TABLE books;
DROP STAGE s3_books_stage;
DROP CONNECTION s3_books_conn;

这些命令不会删除 S3 对象、停用 AWS 密钥或撤销 IAM 角色访问权限。请单独清理测试专用的 AWS 资源。角色权限撤销请参阅维护或移除访问权限。

相关文档

任务	文档
配置 AWS 角色权限和信任关系	使用 AWS IAM 角色进行认证
查询 Connection 参数和权限要求	CREATE CONNECTION
查询 Stage 语法和文件格式选项	CREATE STAGE
查询导入选项和错误处理	COPY INTO