redshift-guide

Amazon Redshift 指南

Redshift 并非 PostgreSQL（请先阅读）

Redshift 使用 PostgreSQL 的网络协议，并且在表层语法上有很多相似之处，因此 LLM 会假设 PostgreSQL 的行为也适用——但事实往往并非如此。两者在系统表（pg_catalog 并不完整）、DDL（没有索引、没有序列）、函数（string_agg、在表上使用 SUBSTR、仅限主节点的函数）、类型（text 列会变为 VARCHAR(256)）和比较语义（尾随空格、约束不强制执行）等方面都存在差异。请假设两者存在差异，并对照下方参考资料进行验证——不要凭 PostgreSQL 的惯常用法作答。 PostgreSQL 与 Redshift 的常见差异见 references/redshift-sql-syntax.md。

配合 AWS MCP 服务 使用效果最佳——它会在沙盒化且带有审计日志的环境中运行下方的 AWS CLI 和 Redshift Data API 调用。这里的所有指南都是纯 AWS CLI 和 SQL，无需该服务也能使用。

步骤 0：Serverless 还是 Provisioned？

回答问题前，先确认这一点——API、系统表和功能各不相同。若问题中说明了类型，则据此判断；若未说明，请询问。SELECT version() 无法识别类型。

• Serverless — 通过 workgroup（和 namespace）识别。Data API 调用使用 --workgroup-name；用户会说“workgroup”或“Serverless”。
• Provisioned — 通过 cluster 识别。Data API 调用使用 --cluster-identifier；用户会说“cluster”。

目标	系统视图	凭证 API
Provisioned	SYS_、所有 SVV_ + STL_、STV_、SVL_、SVCS_（仅限单可用区 — Multi-AZ 上已禁用）	redshift:GetClusterCredentials
Serverless	SYS_ + 部分 SVV_（仅此而已，不包含 STL/STV/SVL/SVCS）	redshift-serverless:GetCredentials

关键事实

• SHOW 命令是主要的元数据接口 — SHOW DATABASES、SHOW SCHEMAS、SHOW TABLES、SHOW COLUMNS、SHOW TABLE、SHOW VIEW。不要默认使用 pg_catalog 或 information_schema。→ 针对元数据/发现问题以及任何“relation does not exist”报告，加载 references/redshift-sql-metadata.md — 其中包含诊断流程。
• SYS_ 视图是首选系统视图 — 它们在所有环境中都可用。STL_、STV_、SVL_ 和 SVCS_ 仅在预置的单 AZ 集群中提供，某些 SVV_ 视图在 Serverless 上不受支持。→ 针对任何系统视图或监控问题，加载 references/redshift-sql-metadata.md。
• 用于调试 COPY 的是 sys_load_error_detail（不要用仅在预置的单 AZ 集群中提供的 stl_load_errors）。
• DATEADD/DATEDIFF — 参数顺序是单位在前：DATEADD(day, -30, GETDATE())、DATEDIFF(day, start, end)。
• APPROXIMATE COUNT(DISTINCT col) — Redshift 专有，误差约为 2%，在大型数据集上比精确的 COUNT(DISTINCT) 快得多。
• MERGE ... REMOVE DUPLICATES — 当源表和目标表的架构相同时，可简化去重操作。
• COPY 应使用 IAM_ROLE（命名空间角色，而非调用方角色）+ 支持使用 MANIFEST 指定明确的文件列表 + 使用 MAXERROR 容忍错误。
• SUBSTR() 仅可在领导节点上使用 — 用于字面量时有效，但用于表列时会报错（SUBSTR() function is not supported (Hint: use SUBSTRING instead)）。用于列时请使用 SUBSTRING()。
• UNIQUE / PRIMARY KEY / FOREIGN KEY 仅作信息性声明 — 不会强制执行（允许重复行且不会报错）。它们只是优化器提示；请在应用程序中或通过 MERGE 保证数据完整性。NOT NULL 会强制执行。
• SHOW VIEW <schema.name> 会返回普通视图、物化视图或延迟绑定视图的定义。物化视图的新鲜度：SVV_MV_INFO（is_stale）。
• 聚合函数不支持 FILTER (WHERE ...) — 这是 PostgreSQL 专有语法，Redshift 会拒绝。请改用 COUNT(CASE WHEN cond THEN 1 END) / SUM(CASE WHEN cond THEN x END)。这适用于你生成的所有查询，包括根据参考示例编写的查询。
• TOP N 和 LIMIT N 均可使用（但 TOP N PERCENT 不可用）。text 列会变成 VARCHAR(256) — 请使用 VARCHAR(max) 或指定长度。
• Iceberg 表使用 CREATE TABLE ... USING ICEBERG（不要使用 STORED AS ICEBERG 或 TABLE_FORMAT=ICEBERG）。
• Datashare 支持读写操作 — 生产者授予写入权限后，消费者即可写入。遇到 datashare 写入的“permission denied”时，应视为缺少授权，而非不支持该操作。→ 加载 references/redshift-sql-metadata.md，了解相关要求和限制。
• 存储：先确定空间占用来源，再采取补救措施，切勿条件反射式地执行 VACUUM。 磁盘空间不足通常不是数据增长导致的 — 应先排除临时查询溢出（临时块）和每个节点/切片的数据倾斜，因为集群平均值会掩盖单个已满节点。在 RA3/Serverless 上，本地占用较高表示的是缓存，并非空间不足；托管存储有可用空间也无法避免节点本地磁盘已满。仅凭 SVV_TABLE_INFO.unsorted 会产生误导 — 是否排序应以 vacuum_sort_benefit 为依据。“存储在增长 / 是什么导致增长”与“存储占用很高”是不同的问题：前者需要查看数月趋势（使用 CloudWatch，而非某个时间点的快照）；单表归因始终不完整，且各表占用之和永远不等于集群总量。→ 加载 references/redshift-storage-utilization.md 以归因空间占用，然后加载 references/redshift-storage-remediation.md 采取行动。

安全防护措施

阻止： DROP DATABASE、没有 WHERE 的 DELETE、publicly-accessible=true、GRANT ALL ON ALL 先警告，再确认： RESIZE、RESTORE、对大型表执行 VACUUM、ALTER PASSWORD、WLM 配置更改、TRUNCATE / DROP TABLE——TRUNCATE 会强制隐式 COMMIT，且无法回滚（还会提交同一事务中其他待处理的工作），因此在继续前，请明确指出目标表，并说明这些行无法恢复；仅当用户已明确表示临时表/暂存表可丢弃时，才将其视为常规操作 确认： CREATE、特定 GRANT、COPY、UNLOAD

安全注意事项

生成任何用于连接、加载或导出的内容时，都应采用以下默认设置。详情 见注明的参考文件。

• 传输中： Data API 仅支持 HTTPS。对于 JDBC/ODBC，请设置 require_ssl 参数，并使用 sslmode=verify-full 连接，以验证服务器证书。
• 静态数据： 保持集群/命名空间加密处于启用状态，并在 UNLOAD 中添加 ENCRYPTED KMS_KEY_ID '<arn>'——它会将查询结果写入 S3，数据因此位于 Redshift 自身加密范围之外。→ references/redshift-sql-ddl-copy.md
• 凭证： 优先使用 SecretArn（Secrets Manager）或 IAM Identity Center；DbUser 也可以接受，因为它会签发临时凭证。切勿将数据库密码写入 代码、环境变量或 SQL 文本中。→ references/redshift-sql-recipes-load-api.md
• 最小权限： 将命名空间 IAM_ROLE 的权限限定于特定存储桶和前缀 （对 arn:aws:s3:::<bucket>/<prefix>/* 授予 s3:GetObject），不要使用 s3:* 或托管的 完全访问策略；并在其信任策略中同时添加 aws:SourceArn（ 集群/命名空间 ARN）和 aws:SourceAccount 条件——仅设置 SourceArn 仍会允许账户中的其他 资源代入该角色。应按对象授予权限，而不是使用 GRANT ALL ON ALL。
• 审计： CloudTrail 会记录 redshift-data:* API 调用，但不记录执行的 SQL； 为此，请启用 Redshift 审计日志（useractivitylog、connectionlog、userlog）。 两者都会记录查询文本和用户活动，因此请加密所有正在使用的目标位置： CloudWatch Logs 日志组（aws logs associate-kms-key）、CloudTrail 跟踪 （SSE-KMS）以及审计日志 S3 存储桶（SSE-S3——S3 审计日志仅支持 S3 托管密钥，不支持 KMS）。Serverless 仅支持将审计日志发送到 CloudWatch。
• 网络： 保持 PubliclyAccessible=false，并通过 VPC 端点连接。不要将端口 5439 开放给 0.0.0.0/0 或 ::/0——请将入站规则限制为 特定 CIDR 或引用安全组。
• 敏感数据： Data API 结果会保留 24h，且 sys_load_error_detail 可能会 回显被拒绝行的片段，因此应将语句 ID 和加载错误输出视为敏感信息。
• 延伸阅读： Amazon Redshift 中的安全性 了解这些默认设置背后的完整指南。

路由表

必须遵守： 当问题符合下方某一行时，回答前必须加载并阅读引用的文件。

提供故障排除步骤前，先询问目标是预置集群还是 Serverless—— 除非问题已说明是哪一种；若已说明，则直接按其说明处理，不要再次确认。

用户意图	路由至
"CREATE TABLE"、"DISTKEY/SORTKEY"、"ENCODE"、"IDENTITY"、"COPY"、"UNLOAD"、"IAM_ROLE"、"Iceberg table"	references/redshift-sql-ddl-copy.md
"LISTAGG"、"DATEADD/DATEDIFF"、"NVL/DECODE"、"type mapping"、"text type"、"VARBYTE"、"recursive CTE"	references/redshift-sql-functions-types.md
"QUALIFY"、"PIVOT/UNPIVOT"、"MERGE"、"TOP N"、"SUBSTR error"、"UNIQUE/PK not enforced"、"trailing blanks"、"leader-node function"、"JSON"、"SUPER"、"PartiQL"、"nested/semi-structured data"	references/redshift-sql-extensions-semantics.md
"system view"、"SVV_/SYS_"、"SHOW commands"、"STL vs SYS"、"list tables"、"distkey/sortkey lookup"、"datashare discovery"、"2-part vs 3-part"、"permission denied"、"GRANT"、"privileges"、"relation/table does not exist"	references/redshift-sql-metadata.md
"how do I write SQL"、"PostgreSQL vs Redshift"、"which SQL reference"、一般方言问题	references/redshift-sql-syntax.md（包含 6 篇 SQL 参考资料的索引，以及 PostgreSQL 与 Redshift 的故障对照表）
"COPY failed"、"load error"、"Data API poll"、"async query"、"Data API throttle"	references/redshift-sql-recipes-load-api.md
"materialized view"、"MV refresh"、"AUTO REFRESH"、"stale view"	references/redshift-sql-materialized-views.md
"disk full" / 错误 1016 / 34507、"PercentageDiskSpaceUsed"、"storage grew"、"what's consuming space"、"ghost rows"、"tombstone"、"spill to disk"、"managed storage vs local SSD"、"datashare cache"、"one node full / storage skew"、"Serverless storage inflation"、"what is driving the storage increase" / "storage keeps climbing" / "grew N% per month" / "which tables are growing" / "is vacuum missing"——这是关于随时间增长的问题，应由 "Is it growing, and what is driving it?" 一节解答：将问题拆分为四部分（是否真的接近满载、是否存在 vacuum 积压、VACUUM 能释放多少空间、是什么因素推动了趋势），使用 CloudWatch 查看数月趋势，通过 SYS_VACUUM_HISTORY 按表归因，并明确说明哪些内容无法通过客户侧视图归因；任何关于快照 / 备份 / 恢复点计费或成本的问题——包括 "AWS Backup"、"cross-region snapshot copy"、"backup billed at full size"、"why is snapshot storage this expensive"、"incremental so it should be cheaper"（依据 S16 中按类型 × 平台划分的矩阵作答，绝不可依据 AWS Backup 自身的增量复制文档，因为该文档描述的是 AWS Backup 的行为，而不是 Redshift 手动快照的计量方式）；"cluster unavailable / stuck after hitting 100% storage"（先确认空间是否已满——检查 CloudWatch 中的 PercentageDiskSpaceUsed，因为集群停机时无法访问 SQL 视图；并排除非存储原因，避免直接认定为磁盘问题）——先归因空间占用	references/redshift-storage-utilization.md
"VACUUM won't finish / times out"、"which VACUUM mode — DELETE ONLY / SORT ONLY / FULL / RECLUSTER"、"vacuum_sort_benefit"、"unsorted"、"reclaim space"、"deep copy"、"auto-vacuum CPU"、"distribution key skew"、"recovering a cluster stuck or unavailable at ~100% storage — headroom plus escalation"、"resize failed and stuck in canceling-resize"——采取处理措施	references/redshift-storage-remediation.md
"slow Redshift query"、"query was fast now slow"、"why is my query slow"、"query performance"、"time decomposition"、"queue vs execution time"、"planning/compile time"、"result cache hit / false fast"、"EXPLAIN plan"、"DS_BCAST_INNER / broadcast / nested loop / merge join"、"stale statistics / ANALYZE / bad row estimate"、"function on join key / plan flip"、"distribution skew / skew_rows / one slice"、"did the query change / query hash"、"row multiplication / join fan-out / DISTINCT slow"、"sys_query_history / sys_query_detail"	references/redshift-sql-query-performance.md
"ready-to-run performance query"、"which SQL to run"、"diagnostic queries"、"execution step / skew / spill"、"plan diff between runs"、"svv_table_info table health"、"auto-analyze / auto-vacuum history"、"lock wait / transaction history"	references/redshift-sql-query-performance-queries.md
"connection timed out/refused"、"SSO/federated login fails"、"Response signature invalid"、"assumeRoleWithSAML"、"RedshiftDbUser principal tag"、"sts:TagSession AccessDenied"、"IAM Identity Center region"、"connection limit exceeded"、"ODBC/JDBC driver"、"ODBC 1.x EOL/CVE"、"SSL error/certificate verify failed"、"permission denied to query database created from datashare"、"SYSLOG ACCESS/system-table row visibility"、"GetClusterCredentials AccessDenied"	references/redshift-auth-authorization.md
不符合上述情况的常规 Redshift 问题	直接依据常识作答
Aurora、RDS、DynamoDB、Athena（非 Redshift）	**拒绝。**说明此技能仅适用于 Amazon Redshift。不要提供其他数据库服务的指导。

Data API 快速参考

→ **在回答任何 Data API、COPY 错误或异步查询问题前，都要加载 references/redshift-sql-recipes-load-api.md。**该文件包含有界轮询循环、HasResultSet 和 ResourceNotFoundException 处理方式、各目标对应的参数以及身份验证选项。

Data API 调用默认是异步的——请使用长轮询（--wait-time-seconds，1–30），而不是盲目休眠；对于耗时可能超过 30 秒的任务，请使用有界循环。 无服务器版使用 --workgroup-name，预置版使用 --cluster-identifier。