Amazon Redshift は、パッチ 198 以降、新しい Python UDF の作成をサポートしなくなります。既存の Python UDF は、2026 年 6 月 30 日まで引き続き機能します。詳細については、[ブログ記事](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)を参照してください。
# Amazon Redshift Data API の使用
Amazon Redshift Data API は、データベースドライバー、接続、ネットワーク設定、データバッファリング、認証情報などを管理する必要がなくなるため、Amazon Redshift データウェアハウスへのアクセスを簡素化します。AWS SDK で Data API オペレーションを使用して SQL ステートメントを実行できます。Data API オペレーションの詳細については、[Amazon Redshift Data API のリファレンス](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)を参照してください。
Data API は、データベースへの永続的な接続を必要としません。代わりに、セキュア HTTP エンドポイントおよび AWS SDK との統合を利用できます。エンドポイントを使用して、接続を管理せずに SQL ステートメントを実行することができます。Data API の呼び出しは非同期です。Data API では、AWS Secrets Manager に格納された認証情報か、一時的なデータベース認証情報を使用できます。どちらの認可方法でも、API 呼び出しでパスワードを渡す必要はありません。AWS Secrets Manager の詳細については、*AWS Secrets Managerユーザーガイド*の「[AWS Secrets Manager とは](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)」を参照してください。認可に AWS IAM アイデンティティセンター を使用することもできます。
Data API を使用すると、AWS Lambda、Amazon SageMaker AI ノートブック、AWS Cloud9 などのウェブサービスベースのアプリケーションで、Amazon Redshift のデータにプログラムによってアクセスできます。これらのアプリケーションの詳細については、「[AWS Lambda](https://aws.amazon.com/lambda/)」、「[Amazon SageMaker AI](https://aws.amazon.com/sagemaker/)」、「[AWS Cloud9](https://aws.amazon.com/cloud9/)」を参照してください。
Data API の詳細については、「*AWS Big Data ブログ*」の「[Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/)」を参照してください。
## Amazon Redshift Data API の操作
Amazon Redshift データ API を使用する前に、以下の手順を確認してください。
1. データ API の呼び出し元として承認されているかどうかを確認します。認可の詳細については、「[Amazon Redshift Data API へのアクセスの認可](data-api-access.md)」を参照してください。
1. Secrets Manager から認証情報を使用して Data API を呼び出すか、一時的な認証情報を使用するか、または AWS IAM アイデンティティセンター を使用するかを決定します。詳細については、「[Amazon Redshift Data API を呼び出すときのデータベース認証用の認証情報の選択](#data-api-calling-considerations-authentication)」を参照してください。
1. 認証情報に Secrets Manager を使用する場合は、シークレットを設定します。詳細については、「[AWS Secrets Manager へのデータベース認証情報の保存](data-api-secrets.md)」を参照してください。
1. Data API を呼び出す際の考慮事項と制限事項を確認してください。詳細については、「[Amazon Redshift Data API を呼び出す際の考慮事項](#data-api-calling-considerations)」を参照してください。
1. Data API は、AWS Command Line Interface(AWS CLI) や独自のコードから、または Amazon Redshift コンソールのクエリエディタを使用して呼び出します。AWS CLI からの呼び出しの例については、「[Data API の呼び出し](data-api-calling.md)」を参照してください。
## Amazon Redshift Data API を呼び出す際の考慮事項
Data API を呼び出すときは、以下について検討します。
+ Amazon Redshift Data API は、Amazon Redshift のプロビジョニング済みクラスターと Redshift Serverless ワークグループのデータベースにアクセスできます。Redshift Data API を利用可能な AWS リージョン の一覧については、*Amazon Web Services 全般のリファレンス*の「[Redshift Data API](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html)」のエンドポイントのリストをご覧ください。
+ クエリの最大期間は 24 時間です。
+ アクティブなクエリの最大数 (`STARTED` および `SUBMITTED` クエリ) は、Amazon Redshift クラスターあたり 500 です。
+ クエリ結果の最大サイズは 500 MB (gzip 圧縮後) です。500 MB を超えるレスポンスデータが返されると、その呼び出しは終了します。
+ クエリ結果の最大保持時間は 24 時間です。
+ クエリステートメントの最大サイズは 100 KB です。
+ Data API は、次のノードタイプの単一ノードおよび複数ノードのクラスターを照会するために使用できます。
+ dc2.large
+ dc2.8xlarge
+ ra3.large
+ ra3.xlplus
+ ra3.4xlarge
+ ra3.16xlarge
+ クラスターは、Amazon VPC サービスに基づいて Virtual Private Cloud (VPC) で作成する必要があります。
+ デフォルトでは、`ExecuteStatement` または `BatchExecuteStatement` API オペレーションの実行者と同じ IAM ロールを持つユーザーは `CancelStatement`、`DescribeStatement`、`GetStatementResult`、`GetStatementResultV2`、および `ListStatements` API オペレーションで同じステートメントを操作できます。別のユーザーから同じ SQL ステートメントを操作する場合、そのユーザーは、SQL ステートメントを実行したユーザーの IAM ロールを引き受ける必要があります。ロールを割り当てる方法については、[Amazon Redshift Data API へのアクセスの認可](data-api-access.md)を参照してください。
+ `BatchExecuteStatement` API オペレーションの `Sqls` パラメータで SQL ステートメントが単一のトランザクションとして実行されます。これらは、配列の順に従って連続的に実行されます。後続の SQL ステートメントは、配列内の前のステートメントが完了するまで開始されません。SQL ステートメントが失敗した場合、1 つのトランザクションとして実行されるため、すべての作業がロールバックされます。
+ `ExecuteStatement` または `BatchExecuteStatement` API オペレーションで使用されるクライアントトークンの最大保持時間は 8 時間です。
+ Amazon Redshift でプロビジョニングされたクラスターと Redshift Serverless ワークグループがカスタマーマネージドキーを使用して暗号化されている場合、Redshift は Redshift Data API がオペレーションにキーを使用できるようにする許可を作成します。詳細については、 [Amazon Redshift Data API で AWS KMS を使用する](data-api-kms.md) を参照してください。
+ Redshift Data API の各 API には、リクエストのスロットリング前の 1 秒あたりのトランザクション割り当てがあります。クォータについては、「[Amazon Redshift Data API のクォータ](amazon-redshift-limits.md#data-api-quotas-account)」を参照してください。リクエスト率がクォータを超えると、HTTP ステータスコード: 400 の `ThrottlingException` が返されます。スロットリングに対応するには、「**AWS SDK とツールリファレンスガイド」の「[再試行動作](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)」で説明されている再試行戦略を使用します。AWS SDK によっては、この戦略が HTTP 400 エラー用に自動的に実装されています。
**注記**
AWS Step Functions では、再試行がデフォルトでは有効になっていません。Step Functions ステートマシンで Redshift データ API を呼び出す場合は、Redshift データ API コールに `ClientToken` 冪等性パラメータを含める必要があります。この `ClientToken` の値は、再試行の間も維持する必要があります。次の `ExecuteStatement` API へのリクエストの例では、`States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)` 式は、組み込み関数を使用してステートマシンが実行されるたびに一意となる `$$.Execution.Id` の UUID 部分を抽出します。詳細については、「**AWS Step Functions デベロッパーガイド」の「[組み込み関数](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html)」を参照してください。
```
{
"Database": "dev",
"Sql": "select 1;",
"ClusterIdentifier": "MyCluster",
"ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```
## Amazon Redshift Data API を呼び出すときのデータベース認証用の認証情報の選択
データ API を呼び出すと、一部の API 操作で次のいずれかの認証方法を使用します。各メソッドでは、異なるパラメータの組み合わせが必要です。
**AWS IAM アイデンティティセンター**
Data API は、AWS IAM アイデンティティセンター に登録されたシングルサインオンユーザーでアクセスできます。IAM アイデンティティセンターの設定手順については、「[信頼できる ID の伝播で Data API を使用する](data-api-trusted-identity-propagation.md)」を参照してください。
**AWS Secrets Manager**
この方法では、`username` および `password` を持つ AWS Secrets Manager が格納されるシークレットの `secret-arn` を指定します。指定されたシークレットには、指定する `database` に接続するための認証情報が含まれます。クラスターに接続するときは、データベース名も指定します。クラスター識別子 (`dbClusterIdentifier`) を指定する場合は、シークレット内に格納されているクラスター識別子と一致する必要があります。サーバーレスワークグループに接続する場合は、データベース名も指定します。詳細については、「[AWS Secrets Manager へのデータベース認証情報の保存](data-api-secrets.md)」を参照してください。
またこの方法では、データが配置されている AWS リージョン を特定する `region` 値も指定できます。
**一時的な認証情報**
この方法を実行する場合は、次のいずれかのオプションを選択します。
+ サーバーレスワークグループに接続する場合は、ワークグループ名とデータベース名を指定します。データベースユーザー名は IAM ID から取得されます。例えば、`arn:iam::123456789012:user:foo` のデータベースユーザー名は `IAM:foo` です。また、`redshift-serverless:GetCredentials` オペレーションを呼び出す許可も必要です。
+ IAM ID としてクラスターに接続するときは、クラスター識別子とデータベース名を指定します。データベースユーザー名は IAM ID から取得されます。例えば、`arn:iam::123456789012:user:foo` のデータベースユーザー名は `IAM:foo` です。また、`redshift:GetClusterCredentialsWithIAM` オペレーションを呼び出す許可も必要です。
+ データベースユーザーとしてクラスターに接続するときは、クラスター識別子、データベース名、データベースユーザー名を指定します。また、`redshift:GetClusterCredentials` オペレーションを呼び出す許可も必要です。この方法で接続するときにデータベースグループに参加する方法については、「[クラスターへの接続時にデータベースグループに参加する](data-api-dbgroups.md)」を参照してください。
またこの方法では、データが配置されている AWS リージョン を特定する `region` 値も指定できます。
## Amazon Redshift データ API を呼び出すときの JDBC データ型のマッピング
次の表は、Data API 呼び出しで指定したデータ型に Java Database Connectivity (JDBC) データ型をマッピングしたものです。
****
| JDBC データ型 | Data API のデータ型 |
| --- | --- |
| `INTEGER, SMALLINT, BIGINT` | `LONG` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY` | `BLOB` |
| `VARBINARY` | `STRING` |
| `CLOB` | `STRING` |
| その他の型 (日時に関する型も含む) | `STRING` |
文字列値は Amazon Redshift データベースに渡され、暗黙的にデータベースのデータ型に変換されます。
**注記**
現在、Data API はユニバーサル固有識別子 (UUID) の配列をサポートしていません。
## Amazon Redshift Data API を呼び出す際にパラメータを使用した SQL ステートメントを実行する
SQL ステートメントの一部にパラメータを使用して Data API オペレーションを呼び出し、データベースエンジンに送信される SQL テキストを制御できます。名前付きパラメータを使用すると、SQL テキストでハードコーディングすることなく、柔軟な方法でパラメータを渡すことができます。これらは、SQL テキストを再利用し、SQL インジェクションの問題を回避するのに役立ちます。
次の例は、AWS CLI コマンド `execute-statement` または `batch-execute-statement` の `parameters` フィールドの名前付きパラメータを示しています。
```
--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"
```
名前付きパラメータを使用する際は、次について検討します。
+ 名前付きパラメータは、SQL ステートメントの値の置換にのみ使用できます。
+ `INSERT INTO mytable VALUES(:val1)` など、INSERT ステートメントの値は置換することができます。
名前付きパラメータは任意の順序で指定でき、パラメータは SQL テキストで複数回使用できます。前の例で示したパラメータオプションでは、値 `1` および `Seattle` がテーブル列 `id` および `address` に挿入されます。SQL テキストでは、次のように名前付きパラメータを指定します。
```
--sql "insert into mytable values (:id, :address)"
```
+ `WHERE attr >= :val1`、`WHERE attr BETWEEN :val1 AND :val2`、`HAVING COUNT(attr) > :val` など、条件句の値は置換することができます。
+ `SELECT column-name`、`ORDER BY column-name`、または `GROUP BY column-name` など、SQL ステートメントの列名は置換できません。
例えば、次の SELECT ステートメントは無効な構文なので失敗します。
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
構文エラーのあるステートメントを記述 (`describe-statement` オペレーション) した場合、返される `QueryString` はパラメータ (`"QueryString": "SELECT :colname, FROM event"`) の列名を置換せず、エラーが報告されます (ERROR: syntax error at or near \\"FROM\\"\\n Position: 12)。
+ `COUNT(column-name)`、`AVG(column-name)`、または `SUM(column-name)` などの集計関数では、列名を置換できません。
+ JOIN 句の列名は置換できません。
+ SQL が実行されると、データは暗黙的にデータ型にキャストされます。データ型のキャストのついての詳細は、*Amazon Redshift データベースデベロッパーガイド*の「[データ型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)」を参照してください。
+ 値を NULL に設定することはできません。データ API では、これはリテラル文字列 `NULL` として解釈されます。次の例では、`id`がリテラル文字列 `null` に置き換えられます。SQL NULL 値ではありません。
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
+ 長さにゼロの値を設定することはできません。Data API の SQL ステートメントが失敗します。次の例では、`id`の長さをゼロの値に設定しようとしているため、SQL ステートメントは失敗します。
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
+ パラメータを使用して、SQL ステートメントにテーブル名を設定することはできません。Data API では、JDBC `PreparedStatement` のルールに従います。
+ `describe-statement` オペレーションの出力により、SQL ステートメントのクエリパラメータが返されます。
+ `execute-statement` オペレーションと `batch-execute-statement` オペレーションは、どちらもパラメータを使用した SQL ステートメントをサポートしています。`batch-execute-statement` を使用する場合、パラメータはバッチ内のすべての SQL ステートメント間で共有されます。各 SQL ステートメントは、指定されたパラメータのサブセットを参照できますが、どのパラメータも最低 1 回はどこかの SQL ステートメントで使用する必要があります。
## Amazon Redshift Data API を呼び出す際に冪等性トークンで SQL ステートメントを実行する
変異する API リクエストを行うと、通常、リクエストはオペレーションの非同期ワークフローが完了する前に結果を返します。リクエストが既に結果を返している場合でも、操作が完了する前にタイムアウトしたり、その他のサーバーの問題が発生したりすることもあります。これにより、リクエストが成功したかどうかを判断するのが難しくなり、操作を正常に完了するために複数回の再試行が行われることがあります。ただし、元のリクエストとその後の再試行が成功すると、操作は複数回完了します。つまり、意図したよりも多くのリソースを更新する可能性があります。
*冪等性*とは、API リクエストが 1 回だけ完了することを保証するものです。冪等性リクエストでは、元のリクエストが正常に完了した場合、その後の再試行は追加のアクションを実行せずに正しく完了します。データ API `ExecuteStatement` と `BatchExecuteStatement` オペレーションには、オプションの `ClientToken` 冪等性パラメータがあります。`ClientToken` は 8 時間後に期限切れになります。
**重要**
AWS SDK から `ExecuteStatement` および `BatchExecuteStatement` オペレーションを呼び出すと、再試行時に使用するクライアントトークンが自動的に生成されます。この場合、`ExecuteStatement` および `BatchExecuteStatement` オペレーションで `client-token` パラメータを使用することはお勧めしません。CloudTrail のログを表示すると `ClientToken` を確認できます。CloudTrail ログの例については、「[Amazon Redshift Data API の例](logging-with-cloudtrail.md#data-api-cloudtrail)」を参照してください。
次の `execute-statement` AWS CLI コマンドは、冪等性のオプション `client-token` パラメータを示しています。
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
次の表は、冪等性 API リクエストに対して返される一般的な応答と、再試行の推奨事項を示しています。
| 応答 | 推奨事項 | コメント |
| --- | --- | --- |
| 200 (OK) | 再試行しないでください | 元のリクエストは正しく完了しています。それ以降に再試行しても正常に戻ります。 |
| 400 シリーズ応答コード | 再試行しないでください | 次のうち、リクエストに問題があります。[See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/redshift/latest/mgmt/data-api.html)
リクエストに状態の変更処理中のリソースが含まれている場合、リクエストを再試行すると成功する可能性があります。 |
| 500 シリーズ応答コード | 再試行 | このエラーは AWS サーバー側の問題によって発生し、通常は一時的なものです。適切なバックオフ戦略でリクエストを繰り返してください。 |
Amazon Redshift 応答コードの詳細については、「*Amazon Redshift API リファレンス*」から「[一般的なエラー](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html)」を参照してください。
## Amazon Redshift Data API を呼び出す際にセッションの再利用によって SQL ステートメントを実行する
API リクエストを実行して SQL ステートメントを実行すると、通常、SQL が実行されているセッションは SQL の完了時に終了します。指定された秒数だけセッションをアクティブにするために、Data API `ExecuteStatement` および `BatchExecuteStatement` オペレーションにはオプションの `SessionKeepAliveSeconds` パラメータがあります。`SessionId` レスポンスフィールドにはセッションのアイデンティティが含まれており、後続の `ExecuteStatement` および `BatchExecuteStatement` オペレーションで使用できます。それ以降の呼び出しでは、別の `SessionKeepAliveSeconds` を指定してアイドルタイムアウト時間を変更できます。`SessionKeepAliveSeconds` が変更されていない場合、最初のアイドルタイムアウト設定は残ります。セッションの再利用を使用する場合は、次の点を考慮してください。
+ `SessionKeepAliveSeconds` の最大値は 24 時間です。
+ セッションは最大 24 時間持続します。24 時間後、セッションは強制的に閉じられ、進行中のクエリは終了します。
+ Amazon Redshift クラスターまたは Redshift Serverless ワークグループあたりのセッションの最大数は 500 です。
+ セッションごとに 1 つのクエリしか実行できません。同じセッションで次のクエリを実行するには、クエリが完了するまで待つ必要があります。つまり、指定されたセッションでクエリを並行して実行することはできません。
+ Data API は、特定のセッションのクエリをキューに入れることはできません。
`ExecuteStatement` および `BatchExecuteStatement` オペレーションの呼び出しで使用される `SessionId` を取得するには、`DescribeStatement` および `ListStatements` オペレーションを呼び出します。
次の例は、`SessionKeepAliveSeconds` および `SessionId` パラメータを使用してセッションを存続させ、再利用する方法を示しています。まず、オプションの `session-keep-alive-seconds` パラメータを `2` に設定して `execute-statement` AWS CLI コマンドを呼び出します。
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
応答にはセッションの識別子が含まれます。
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
次に、最初の呼び出しから返された `SessionId` を使用して `execute-statement` AWS CLI コマンドを呼び出します。オプションで、`session-keep-alive-seconds` パラメータを `10` に設定してアイドルタイムアウト値を変更します。
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## SQL ステートメントの結果を取得する
結果の形式に応じて異なる Data API オペレーションを使用して、SQL 結果を取得します。`ExecuteStatement` および `BatchExecuteStatement` オペレーションを呼び出すときに、結果の形式を JSON と CSV のどちらにするかを指定できます。未指定の場合は、デフォルトで JSON になります。JSON 形式で結果を取得するには、`GetStatementResult` オペレーションを使用します。CSV 形式で結果を取得するには、`GetStatementResultV2` オペレーションを使用します。
JSON 形式で返される結果は、各列に関するメタデータを含むレコードです。各レコードは JSON 形式です。例えば、`GetStatementResult` からのレスポンスは次のようになります。
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "{{}}",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows": {{}}
}
```
CSV 形式で返される結果は、各列に関するメタデータを含むレコードです。結果は 1 MB のチャンクで返され、各チャンクには任意の数の行が CSV 形式で含まれます。各リクエストは、最大 15 MB 分の結果を返します。結果が 15 MB を上回る場合は、結果の取得を続行できるように、次のページトークンが返されます。例えば、`GetStatementResultV2` からのレスポンスは次のようになります。
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "{{}}",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows": {{}}
}
```