本文详解在 Polars 中通过 storage_options 正确配置 AWS 凭据（含 Session Token）以安全、可靠地读取 S3 上的 Parquet 文件，避免 403 Forbidden 等权限错误。
本文详解在 polars 中通过 `storage_options` 正确配置 aws 凭据（含 session token）以安全、可靠地读取 s3 上的 parquet 文件，避免 403 forbidden 等权限错误。
在使用 Polars 读取 AWS S3 上的 Parquet 文件时，仅传递 aws_access_key_id 和 aws_secret_access_key 往往不够——尤其当你的 AWS Profile 使用了基于角色的临时凭证（如通过 aws sts assume-role 或 SSO 登录获取）时，必须显式传入 aws_session_token，否则将触发 ComputeError: Client error with status 403 Forbidden。这是因为 Polars 的底层对象存储客户端（object_store）不自动解析本地 ~/.aws/credentials 或 ~/.aws/config 中的 profile 配置，也无法隐式加载 session token。
✅ 推荐做法：使用 boto3 获取完整冻结凭证
以下代码展示了最健壮、跨环境兼容的写法，适用于 IAM 用户密钥、角色扮演（AssumeRole）、SSO 登录等多种认证场景：
import polars as pl
import boto3
# 指定本地 AWS Profile 名称（需已通过 aws-cli 配置）
profile_name = "my-prod-profile"
s3_path = "s3://my-s3-bucket/data/output.parquet"
# 创建 boto3 session 并提取完整凭证（含 token）
session = boto3.Session(profile_name=profile_name)
credentials = session.get_credentials().get_frozen_credentials()
# 构建 storage_options —— 必须包含三项核心凭证 + region
storage_options = {
"aws_access_key_id": credentials.access_key,
"aws_secret_access_key": credentials.secret_key,
"aws_session_token": credentials.token, # ⚠️ 关键！不可省略
"aws_region": session.region_name or "us-east-1", # 建议显式指定
}
# 使用 read_parquet（立即执行）或 scan_parquet（惰性执行）
df = pl.read_parquet(s3_path, storage_options=storage_options)
# 或：lf = pl.scan_parquet(s3_path, storage_options=storage_options).collect()
⚠️ 注意事项与最佳实践
- 不要硬编码凭证：始终优先使用 boto3.Session(profile_name=...) 动态获取凭证，而非手动设置环境变量或明文密钥。
- aws_session_token 是必需的：若 credentials.token 为 None（例如使用长期 IAM 密钥），可安全省略该字段；但只要 profile 启用了 MFA、SSO 或 AssumeRole，token 就一定存在且必须传递。
- Region 必须匹配：aws_region 应与 S3 bucket 所在区域一致，否则可能引发签名错误（SignatureDoesNotMatch）。
-
惰性 vs 立即加载：
- pl.read_parquet()：直接返回 DataFrame，适合小到中等规模数据；
- pl.scan_parquet()：返回 LazyFrame，支持链式过滤/投影下推（pushdown），大幅提升大文件处理效率，推荐用于生产 ETL 流程。
-
替代方案（高级用户）：若希望完全复用 AWS CLI 配置（包括 credential_process 或 sso），可改用 polars 0.20.20+ 版本支持的 anonymous=False + 自动凭据链（需确保 AWS_PROFILE 环境变量已设，且 boto3 可访问）：
import os os.environ["AWS_PROFILE"] = "my-prod-profile" # 仅当未显式传 storage_options 时生效 df = pl.read_parquet("s3://bucket/key.parquet") # Polars 会尝试自动加载但该方式透明性低、调试困难，生产环境仍强烈推荐显式传参。
✅ 验证是否成功
运行后可通过以下方式快速验证连接与权限：
print(df.schema) # 查看列结构 print(df.head(3)) # 预览前 3 行 print(df.estimated_size()) # 查看内存估算（确认已实际加载）
若仍报错，请检查：
- S3 路径是否拼写正确（注意 s3://bucket-name/prefix/file.parquet 格式）；
- IAM Policy 是否授予 s3:GetObject 权限（及 s3:ListBucket，若需自动解析目录）；
- Bucket 是否启用了 Block Public Access？是否位于 VPC Endpoint 内而缺少相应策略？
掌握这一模式后，你不仅能稳定读取 Parquet，还可无缝迁移到 Delta Lake、NDJSON、CSV 等其他 S3 支持格式——只需替换 read_parquet 为对应函数即可。
