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 — ワークグループ（および名前空間）で識別します。Data API の呼び出しでは --workgroup-name を指定します。ユーザーが「workgroup」または「Serverless」と言及します。
• Provisioned — クラスターで識別します。Data API の呼び出しでは --cluster-identifier を指定します。ユーザーが「cluster」と言及します。

対象	システムビュー	認証情報 API
Provisioned	SYS_、すべての SVV_、STL_、STV_、SVL_、SVCS_（単一 AZ のみ — 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> は、通常のビュー、マテリアライズドビュー、または遅延バインディングビューの定義を返します。MV の鮮度は 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 でローカル使用量が高い場合は、容量不足ではなくキャッシュです。また、マネージドストレージに空きがあっても、ノードローカルの Disk Full は発生します。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 specific、COPY、UNLOAD

セキュリティに関する考慮事項

接続、読み込み、エクスポートを行うものを生成する際は、以下のデフォルトを適用してください。詳細は、記載されている参照ファイルを確認してください。

• 転送中： Data API は HTTPS のみを使用します。JDBC/ODBC では require_ssl パラメーターを設定し、sslmode=verify-full で接続してサーバー証明書を検証してください。
• 保存時： クラスター／名前空間の暗号化を有効にしたままにし、UNLOAD に ENCRYPTED KMS_KEY_ID '<arn>' を追加してください。UNLOAD はクエリ結果を 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 の対象を特定のバケットとプレフィックス（s3:GetObject を arn:aws:s3:::<bucket>/<prefix>/* に対して許可）に限定し、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 への監査ログ記録では、KMS ではなく S3 管理キーのみがサポートされます）が対象です。Serverless では監査ログの送信先として CloudWatch のみがサポートされています。
• ネットワーク： PubliclyAccessible=false を維持し、VPC エンドポイント経由で接続してください。ポート 5439 を 0.0.0.0/0 または ::/0 に公開しないでください。インバウンドルールの対象は、特定の CIDR または参照先のセキュリティグループに限定してください。
• 機密データ： Data API の結果は 24 時間保持され、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" — *「増加しているのか、何が原因なのか？」*のセクションで回答する、時間経過に伴う増加についての質問：4つに分ける（本当に容量が逼迫しているのか、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" を含む（AWS Backup の動作を説明するもので、Redshift の手動スナップショットの課金方式を説明するものではない AWS Backup 独自の増分コピーのドキュメントではなく、必ず S16 のタイプ別 × プラットフォーム別マトリックスに基づいて回答する）。"cluster unavailable / stuck after hitting 100% storage"（まず PercentageDiskSpaceUsed を CloudWatch で確認して容量の逼迫を確かめる。クラスター停止中は 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 秒を超える可能性がある処理には上限付きループを維持してください。 Serverless では --workgroup-name、プロビジョンドでは --cluster-identifier を指定します。