# PartiQL: Amazon DynamoDB 用の SQL 互換クエリ言語 Amazon DynamoDB は SQL 互換のクエリ言語である [PartiQL](https://partiql.org/) をサポートしており、Amazon DynamoDB でデータの選択、挿入、更新、および削除を行うことができます。PartiQL を使用すると、AWS マネジメントコンソール、NoSQL Workbench、AWS Command Line Interface、および PartiQL 用の DynamoDB API を使用して、DynamoDB テーブルと簡単にやり取りを行い、アドホッククエリを実行できます。 PartiQL オペレーションは、他の DynamoDB データプレーンオペレーションと同様の可用性、レイテンシー、パフォーマンスを提供します。 次のセクションでは、PartiQL の DynamoDB 実装について説明します。 **Topics** + [PartiQL とは何ですか?](#ql-reference.what-is) + [Amazon DynamoDB での PartiQL](#ql-reference.what-is) + [開始方法](ql-gettingstarted.md) + [データ型](ql-reference.data-types.md) + [ステートメント](ql-reference.statements.md) + [関数](ql-functions.md) + [演算子](ql-operators.md) + [トランザクション](ql-reference.multiplestatements.transactions.md) + [バッチオペレーション](ql-reference.multiplestatements.batching.md) + [IAM ポリシー](ql-iam.md) ## PartiQL とは何ですか? *PartiQL* は、構造化データ、半構造化データ、ネストされたデータを含む複数のデータストア間で、SQL 互換のクエリアクセスを提供します。PartiQL は、Amazon 内で広く使用されており、現在、DynamoDB を含む多くの AWS のサービスの一部として利用できます。 PartiQL の仕様とコアクエリ言語のチュートリアルについては、[PartiQL ドキュメント](https://partiql.org/docs.html)を参照してください。 **注記** Amazon DynamoDB は、[PartiQL](https://partiql.org/) クエリ言語の*サブセット*をサポートしています。 Amazon DynamoDB では、[Amazon ion](http://amzn.github.io/ion-docs/) データ形式または Amazon Ion リテラルはサポートしていません。 ## Amazon DynamoDB での PartiQL DynamoDB で PartiQL クエリを実行するには、次を使用します。 + DynamoDB コンソール + NoSQL Workbench + AWS Command Line Interface (AWS CLI) + DynamoDB API これらの方法を使用して DynamoDB にアクセスする方法については、「[DynamoDB へのアクセス](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AccessingDynamoDB.html)」を参照してください。 # DynamoDB 用の PartiQL の開始方法 このセクションでは、Amazon DynamoDB コンソール、AWS Command Line Interface (AWS CLI)、および DynamoDB API から DynamoDB 用の PartiQL を使用する方法について説明します。 次の例では、「[DynamoDB の開始方法](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)」チュートリアルで、DynamoDB テーブルを定義していることが前提です。 DynamoDB コンソール、AWS Command Line Interface、または DynamoDB API を使用して DynamoDB にアクセスする方法については、「[DynamoDB へのアクセス](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AccessingDynamoDB.html)」を参照してください。 [NoSQL Workbench](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html) を[ダウンロード](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.settingup.html)して、[DynamoDB 用の PartiQL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.html) ステートメントを構築するには、DynamoDB [Operation Builder](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.querybuilder.operationbuilder.html) 用の NoSQL Workbench の右上にある **[PartiQL operations]** (PartiQL オペレーション) を選択します。 ------ #### [ Console ] ![\[Music テーブルに対してクエリオペレーションを実行した結果を示す PartiQL エディタインターフェイス。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/partiqlgettingstarted.png) 1. AWS マネジメントコンソール にサインインして DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開きます。 1. コンソール左側のナビゲーションペインで、[**PartiQL エディター**] を選択します。 1. [**Music**] テーブルを選択します。 1. **[Query table]** (クエリテーブル) を選択します。このアクションで生成したクエリは、完全なテーブルスキャンを実行しません。 1. `partitionKeyValue` を文字列型の値である `Acme Band` に置換します。`sortKeyValue` を文字列型の値である `Happy Day` に置換します。 1. [**実行**] ボタンを選択します。 1. **[Table view]** (テーブルビュー) または **[JSON view]** (JSON ビュー) ボタンを選択すると、クエリの結果を確認できます。 ------ #### [ NoSQL workbench ] ![\[NoSQL Workbench インターフェイス。Music テーブルに対して実行できる PartiQL SELECT ステートメントを示します。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/workbench/partiql.single.png) 1. [**PartiQL ステートメント**] を選択します。 1. 次の PartiQL [[SELECT statement]](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html) (SELECT ステートメント) を入力します。 ``` SELECT * FROM Music WHERE Artist=? and SongTitle=? ``` 1. `Artist` および `SongTitle` パラメータの値を指定するには 1. [**オプションのリクエストパラメータ**] を選択します。 1. [**新しいパラメータの追加**] を選択します。 1. 属性タイプとして **[string]** (文字列型) を選択し、値に `Acme Band` を選択します。 1. ステップ b とステップ c を繰り返し、**[string]** (文字列型) のタイプと `PartiQL Rocks` の値を選択します。 1. コードを生成する場合は、[**Generate code (コードの生成)**] を選択します。 表示されたタブから目的の言語を選択します。これで、このコードをコピーしてアプリケーションで使用できるようになります。 1. オペレーションをすぐに実行する場合は、[**実行**] をクリックします。 ------ #### [ AWS CLI ] 1. INSERT PartiQL ステートメントを使用して、`Music` テーブルに項目を作成します。 ``` aws dynamodb execute-statement --statement "INSERT INTO Music \ VALUE \ {'Artist':'Acme Band','SongTitle':'PartiQL Rocks'}" ``` 1. SELECT PartiQL ステートメントを使用して、Music テーブルから項目を取得します。 ``` aws dynamodb execute-statement --statement "SELECT * FROM Music \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` 1. UPDATE PartiQL ステートメントを使用して、`Music` テーブルの項目を更新します。 ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET AwardsWon=1 \ SET AwardDetail={'Grammys':[2020, 2018]} \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` `Music` テーブルに、項目のリスト値を追加します。 ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` `Music` テーブルから項目のリスト値を削除します。 ``` aws dynamodb execute-statement --statement "UPDATE Music \ REMOVE AwardDetail.Grammys[2] \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` `Music` テーブルに、項目の新しいマップメンバーを追加します。 ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET AwardDetail.BillBoard=[2020] \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` `Music` テーブルに、項目の新しい文字列セットの属性を追加します。 ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET BandMembers =<<'member1', 'member2'>> \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` `Music` テーブルで、項目の文字列セットの属性を更新します。 ``` aws dynamodb execute-statement --statement "UPDATE Music \ SET BandMembers =set_add(BandMembers, <<'newmember'>>) \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` 1. DELETE PartiQL ステートメントを使用して、`Music` テーブルから項目を削除します。 ``` aws dynamodb execute-statement --statement "DELETE FROM Music \ WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" ``` ------ #### [ Java ] ``` import java.util.ArrayList; import java.util.List; import com.amazonaws.AmazonClientException; import com.amazonaws.AmazonServiceException; import software.amazon.dynamodb.AmazonDynamoDB; import software.amazon.dynamodb.AmazonDynamoDBClientBuilder; import software.amazon.dynamodb.model.AttributeValue; import software.amazon.dynamodb.model.ConditionalCheckFailedException; import software.amazon.dynamodb.model.ExecuteStatementRequest; import software.amazon.dynamodb.model.ExecuteStatementResult; import software.amazon.dynamodb.model.InternalServerErrorException; import software.amazon.dynamodb.model.ItemCollectionSizeLimitExceededException; import software.amazon.dynamodb.model.ProvisionedThroughputExceededException; import software.amazon.dynamodb.model.RequestLimitExceededException; import software.amazon.dynamodb.model.ResourceNotFoundException; import software.amazon.dynamodb.model.TransactionConflictException; public class DynamoDBPartiQGettingStarted { public static void main(String[] args) { // Create the DynamoDB Client with the region you want AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-1"); try { // Create ExecuteStatementRequest ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest(); List parameters= getPartiQLParameters(); //Create an item in the Music table using the INSERT PartiQL statement processResults(executeStatementRequest(dynamoDB, "INSERT INTO Music value {'Artist':?,'SongTitle':?}", parameters)); //Retrieve an item from the Music table using the SELECT PartiQL statement. processResults(executeStatementRequest(dynamoDB, "SELECT * FROM Music where Artist=? and SongTitle=?", parameters)); //Update an item in the Music table using the UPDATE PartiQL statement. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist=? and SongTitle=?", parameters)); //Add a list value for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) where Artist=? and SongTitle=?", parameters)); //Remove a list value for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music REMOVE AwardDetail.Grammys[2] where Artist=? and SongTitle=?", parameters)); //Add a new map member for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music set AwardDetail.BillBoard=[2020] where Artist=? and SongTitle=?", parameters)); //Add a new string set attribute for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET BandMembers =<<'member1', 'member2'>> where Artist=? and SongTitle=?", parameters)); //update a string set attribute for an item in the Music table. processResults(executeStatementRequest(dynamoDB, "UPDATE Music SET BandMembers =set_add(BandMembers, <<'newmember'>>) where Artist=? and SongTitle=?", parameters)); //Retrieve an item from the Music table using the SELECT PartiQL statement. processResults(executeStatementRequest(dynamoDB, "SELECT * FROM Music where Artist=? and SongTitle=?", parameters)); //delete an item from the Music Table processResults(executeStatementRequest(dynamoDB, "DELETE FROM Music where Artist=? and SongTitle=?", parameters)); } catch (Exception e) { handleExecuteStatementErrors(e); } } private static AmazonDynamoDB createDynamoDbClient(String region) { return AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); } private static List getPartiQLParameters() { List parameters = new ArrayList(); parameters.add(new AttributeValue("Acme Band")); parameters.add(new AttributeValue("PartiQL Rocks")); return parameters; } private static ExecuteStatementResult executeStatementRequest(AmazonDynamoDB client, String statement, List parameters ) { ExecuteStatementRequest request = new ExecuteStatementRequest(); request.setStatement(statement); request.setParameters(parameters); return client.executeStatement(request); } private static void processResults(ExecuteStatementResult executeStatementResult) { System.out.println("ExecuteStatement successful: "+ executeStatementResult.toString()); } // Handles errors during ExecuteStatement execution. Use recommendations in error messages below to add error handling specific to // your application use-case. private static void handleExecuteStatementErrors(Exception exception) { try { throw exception; } catch (ConditionalCheckFailedException ccfe) { System.out.println("Condition check specified in the operation failed, review and update the condition " + "check before retrying. Error: " + ccfe.getErrorMessage()); } catch (TransactionConflictException tce) { System.out.println("Operation was rejected because there is an ongoing transaction for the item, generally " + "safe to retry with exponential back-off. Error: " + tce.getErrorMessage()); } catch (ItemCollectionSizeLimitExceededException icslee) { System.out.println("An item collection is too large, you\'re using Local Secondary Index and exceeded " + "size limit of items per partition key. Consider using Global Secondary Index instead. Error: " + icslee.getErrorMessage()); } catch (Exception e) { handleCommonErrors(e); } } private static void handleCommonErrors(Exception exception) { try { throw exception; } catch (InternalServerErrorException isee) { System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage()); } catch (RequestLimitExceededException rlee) { System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " + "retrying. Error: " + rlee.getErrorMessage()); } catch (ProvisionedThroughputExceededException ptee) { System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " + "Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " + ptee.getErrorMessage()); } catch (ResourceNotFoundException rnfe) { System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage()); } catch (AmazonServiceException ase) { System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " + "service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " + "configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage()); } catch (AmazonClientException ace) { System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " + "service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+ "Error: " + ace.getMessage()); } catch (Exception e) { System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage()); } } } ``` ------ ## パラメータ化されたステートメントの使用 PartiQL ステートメント文字列に値を直接埋め込む代わりに、疑問符 (`?`) プレースホルダーを使用して、`Parameters` フィールドに値を個別に指定できます。各 `?` は、指定された順序で、対応するパラメータ値に置き換えられます。 パラメータ化されたステートメントを使用すると、ステートメント構造がデータ値から分離され、ステートメントの読み取りと再利用が容易になるため、ベストプラクティスです。また、ステートメント文字列の属性値を手動でフォーマットしたりエスケープしたりする必要もなくなります。 パラメータ化されたステートメントは `ExecuteStatement`、`BatchExecuteStatement`、および `ExecuteTransaction` オペレーションでサポートされています。 次の例では、パーティションキーとソートキーのパラメータ化された値を使用して、`Music` テーブルから項目を取得します。 ------ #### [ AWS CLI parameterized ] ``` aws dynamodb execute-statement \ --statement "SELECT * FROM \"Music\" WHERE Artist=? AND SongTitle=?" \ --parameters '[{"S": "Acme Band"}, {"S": "PartiQL Rocks"}]' ``` ------ #### [ Java parameterized ] ``` List parameters = new ArrayList<>(); parameters.add(new AttributeValue("Acme Band")); parameters.add(new AttributeValue("PartiQL Rocks")); ExecuteStatementRequest request = new ExecuteStatementRequest() .withStatement("SELECT * FROM Music WHERE Artist=? AND SongTitle=?") .withParameters(parameters); ExecuteStatementResult result = dynamoDB.executeStatement(request); ``` ------ #### [ Python parameterized ] ``` response = dynamodb_client.execute_statement( Statement="SELECT * FROM Music WHERE Artist=? AND SongTitle=?", Parameters=[ {'S': 'Acme Band'}, {'S': 'PartiQL Rocks'} ] ) ``` ------ **注記** 前の開始方法セクションの Java の例では、全体にわたってパラメータ化されたステートメントを使用しています。`getPartiQLParameters()` メソッドはパラメータリストを構築し、各ステートメントはインライン値の代わりに `?` プレースホルダーを使用します。 # DynamoDB の PartiQL データ型 次の表に、DynamoDB 用の PartiQL で使用できるデータ型を、一覧で表示します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/ql-reference.data-types.html) ## 例 次のデータ型を挿入する方法を、次のステートメントで示します。`String`、`Number`、`Map`、`List`、`Number Set` および `String Set`。 ``` INSERT INTO TypesTable value {'primarykey':'1', 'NumberType':1, 'MapType' : {'entryname1': 'value', 'entryname2': 4}, 'ListType': [1,'stringval'], 'NumberSetType':<<1,34,32,4.5>>, 'StringSetType':<<'stringval','stringval2'>> } ``` 次のステートメントでは、`Map`、`List`、`Number Set` および `String Set` の型に、新しい要素を挿入する方法を示しています。また、`Number` 型の値を変更する方法も示しています。 ``` UPDATE TypesTable SET NumberType=NumberType + 100 SET MapType.NewMapEntry=[2020, 'stringvalue', 2.4] SET ListType = LIST_APPEND(ListType, [4, <<'string1', 'string2'>>]) SET NumberSetType= SET_ADD(NumberSetType, <<345, 48.4>>) SET StringSetType = SET_ADD(StringSetType, <<'stringsetvalue1', 'stringsetvalue2'>>) WHERE primarykey='1' ``` 次のステートメントでは、`Map`、`List`、`Number Set` および `String Set` の型から要素を削除する方法を示しています。また、`Number` 型の値を変更する方法も示しています。 ``` UPDATE TypesTable SET NumberType=NumberType - 1 REMOVE ListType[1] REMOVE MapType.NewMapEntry SET NumberSetType = SET_DELETE( NumberSetType, <<345>>) SET StringSetType = SET_DELETE( StringSetType, <<'stringsetvalue1'>>) WHERE primarykey='1' ``` 詳細については、「[DynamoDB のデータ型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)」を参照してください。 # DynamoDB 用の PartiQL ステートメント Amazon DynamoDB は、次の PartiQL ステートメントをサポートしています。 **注記** DynamoDB はすべての PartiQL ステートメントをサポートしているわけではありません。 このリファレンスでは、AWS CLI シェルまたは API で手動で実行する PartiQL ステートメントについて、ベーシックな構文と使用例を示します。 *データ操作言語* (DML) は、DynamoDB テーブル内のデータを管理するために使用する、PartiQL ステートメントのセットです。DML ステートメントを使用して、テーブル内のデータを追加、変更、または削除します。 次の DML ステートメントとクエリ言語ステートメントがサポートされています。 + [DynamoDB 用の PartiQL select ステートメント](ql-reference.select.md) + [DynamoDB 用の PartiQL 更新ステートメント](ql-reference.update.md) + [DynamoDB 用の PartiQL 挿入ステートメント](ql-reference.insert.md) + [DynamoDB 用の PartiQL 削除ステートメント](ql-reference.delete.md) [DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md) および [DynamoDB 用の PartiQL を使用してバッチ操作を実行する](ql-reference.multiplestatements.batching.md) は、DynamoDB 用の PartiQL でもサポートされています。 # DynamoDB 用の PartiQL select ステートメント Amazon DynamoDB では、`SELECT` ステートメントを使用して、テーブルからデータを取得します。 `SELECT` ステートメントを使用すると、パーティションキーを持つ等価条件または IN 条件が WHERE 句で指定されていない場合、完全なテーブルスキャンになることがあります。スキャンオペレーションは、すべての項目でリクエストされた値を調べるので、大きなテーブルまたはインデックスに対してプロビジョニングされたスループットを 1 回のオペレーションで使い果たすことがあります。 PartiQL で完全なテーブルスキャンを避けたい場合は、次のようにします。 + 完全なテーブルスキャンが行われないように、[WHERE 句の条件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html#ql-reference.select.parameters)を適切に設定していることを確かめながら、`SELECT` ステートメントを作成します。 + DynamoDB デベロッパーガイドの [例: DynamoDB 用の PartiQL で ステートメントの選択を許可し、テーブル全体のスキャンを行うステートメントを拒否する](ql-iam.md#access-policy-ql-iam-example6) に記載されているように、IAM ポリシーを使用して、完全なテーブルスキャンを無効にします。 詳細については、「DynamoDB デベロッパーガイド」の「[データのクエリとスキャンのベストプラクティス](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html)」を参照してください。 **Topics** + [構文](#ql-reference.select.syntax) + [パラメータ](#ql-reference.select.parameters) + [例](#ql-reference.select.examples) ## 構文 ``` SELECT expression [, ...] FROM table[.index] [ WHERE condition ] [ [ORDER BY key [DESC|ASC] , ...] ``` ## パラメータ ***expression*** (必須) `*` ワイルドカードからの射影、または結果セットからの 1 つ以上の属性名かドキュメントパスの射影リスト。式には、[DynamoDB での PartiQL 関数の使用](ql-functions.md) への呼び出し、または [DynamoDB での PartiQL 算術演算子、比較演算子、論理演算子](ql-operators.md) によって変更されたフィールドで構成できます。 ***テーブル*\$1** (必須) クエリするテーブル名。 *** インデックス*** (オプション) クエリを実行するインデックスの名前です。 インデックスにクエリを実行するときは、テーブル名とインデックス名に二重引用符を追加する必要があります。 ``` SELECT * FROM "TableName"."IndexName" ``` ***condition*** (オプション) クエリの選択条件。 `SELECT` ステートメントによって、完全なテーブルスキャンが行われないようにするには、`WHERE` 句の条件がパーティションキーを指定する必要があります。等価演算子または IN 演算子を使用します。 例えば、`OrderID` パーティションキーと、`Address` を含むその他の非キー属性がある `Orders` テーブルがある場合、次のステートメントは完全なテーブルスキャンを実行しません。 ``` SELECT * FROM "Orders" WHERE OrderID = 100 SELECT * FROM "Orders" WHERE OrderID = 100 and Address='some address' SELECT * FROM "Orders" WHERE OrderID = 100 or OrderID = 200 SELECT * FROM "Orders" WHERE OrderID IN [100, 300, 234] ``` ただし、次の `SELECT` ステートメントを実行すると、完全なテーブルスキャンが行われます。 ``` SELECT * FROM "Orders" WHERE OrderID > 1 SELECT * FROM "Orders" WHERE Address='some address' SELECT * FROM "Orders" WHERE OrderID = 100 OR Address='some address' ``` ***key*** (任意) 返ってきた結果の並び替えに使用するハッシュキーまたはソートキー。デフォルトの順序は昇順 (`ASC`) です。返ってきた結果を降順に並べる場合は、`DESC` を指定します。 **注記** `WHERE` 句を省略すると、テーブル内のすべての項目が取得されます。 ## 例 次のクエリは、`Orders` テーブルでパーティションキーと `OrderID` を指定し、等価演算子を使用することで、存在する場合に項目を 1 つ返します。 ``` SELECT OrderID, Total FROM "Orders" WHERE OrderID = 1 ``` 次のクエリは、OR 演算子を使用することで、特定のパーティションキーと `OrderID`、値を持つ `Orders` テーブルから、すべての項目を返します。 ``` SELECT OrderID, Total FROM "Orders" WHERE OrderID = 1 OR OrderID = 2 ``` 次のクエリは、IN 演算子を使用することで、特定のパーティションキーと `OrderID`、値を持つ `Orders` テーブルから、すべての項目を返します。返ってきた結果は、`OrderID` キー属性の値によって、降順に並べられます。 ``` SELECT OrderID, Total FROM "Orders" WHERE OrderID IN [1, 2, 3] ORDER BY OrderID DESC ``` 次のクエリは、`Total` が非キー属性である場合に、`Total` が 500 以上である `Orders` テーブルからすべての項目を返す、完全なテーブルスキャンを示します。 ``` SELECT OrderID, Total FROM "Orders" WHERE Total > 500 ``` 次のクエリは、IN 演算子と非キー属性である `Total` を使用して、特定の `Total` 範囲の順序で、`Orders` テーブルからすべての項目を返す、完全なテーブルスキャンを示します。 ``` SELECT OrderID, Total FROM "Orders" WHERE Total IN [500, 600] ``` 次のクエリは、BETWEEN 演算子と非キー属性である `Total` を使用して、特定の `Total` 範囲の順序で、`Orders` テーブルからすべての項目を返す、完全なテーブルスキャンを示します。 ``` SELECT OrderID, Total FROM "Orders" WHERE Total BETWEEN 500 AND 600 ``` 次のクエリは、WHERE 句の条件で `CustomerID` パーティションキーと `MovieID` ソートキーを指定し、SELECT 句でドキュメントのパスを使用することで、firestick デバイスで視聴を開始した最初の日付を返します。 ``` SELECT Devices.FireStick.DateWatched[0] FROM WatchList WHERE CustomerID= 'C1' AND MovieID= 'M1' ``` 次のクエリは、テーブル全体のスキャンを示しています。このスキャンでは、WHERE 句の条件でドキュメントのパスを使用し、2019 年 12 月 24 日以降に初めて firestick デバイスを使用した項目のリストを返します。 ``` SELECT Devices FROM WatchList WHERE Devices.FireStick.DateWatched[0] >= '12/24/19' ``` # DynamoDB 用の PartiQL 更新ステートメント `UPDATE` ステートメントを使用して、Amazon DynamoDB テーブルの項目内にある、1 つ以上の属性の値を変更します。 **注記** 一度に更新できる項目は 1 つだけです。1 つの DynamoDB PartiQL ステートメントを発行して、複数の項目を更新することはできません。複数項目の更新については、「[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md)」または「[DynamoDB 用の PartiQL を使用してバッチ操作を実行する](ql-reference.multiplestatements.batching.md)」を参照してください。 **Topics** + [構文](#ql-reference.update.syntax) + [パラメータ](#ql-reference.update.parameters) + [戻り値](#ql-reference.update.return) + [例](#ql-reference.update.examples) ## 構文 ``` UPDATE table [SET | REMOVE] path [= data] […] WHERE condition [RETURNING returnvalues] ::= [ALL OLD | MODIFIED OLD | ALL NEW | MODIFIED NEW] * ``` ## パラメータ ***テーブル*\$1** (必須) 修正されるデータを含んでいるテーブル。 ***パス*** (必須) 作成または変更される属性名、またはドキュメントパス。 ***data*** (必須) 属性値またはオペレーションの結果。 SET で使用するためにサポートされている操作は、次の通りです。 + LIST\$1APPEND: List 型に値を追加します。 + SET\$1ADD: 数値または文字列セットに値を追加します。 + SET\$1DELETE: 数値または文字列セットから値を削除します。 ***condition*** (必須) 修正される項目の選択条件。この条件は、単一のプライマリキー値を解決する必要があります。 ***returnvalues*** (オプション) 属性が更新される前か、更新された後に、表示された項目の属性を取得したい場合に、`returnvalues` を使用します。有効な値は以下のとおりです。 + `ALL OLD *`: 更新操作の前に表示されていた項目について、すべての属性を返します。 + `MODIFIED OLD *`: 更新操作の前に表示されていた属性について、更新された属性だけを返します。 + `ALL NEW *`: 更新操作の後に表示される項目について、すべての属性を返します。 + `MODIFIED NEW *`: `UpdateItem` 操作の後に表示される属性について、更新された属性だけを返します。 ## 戻り値 `returnvalues` パラメータが指定されない限り、このステートメントは値を返しません。 **注記** UPDATE ステートメントの WHERE 句が、DynamoDB テーブルのどの項目も true と評価しない場合、`ConditionalCheckFailedException` が返ります。 ## 例 既存の項目の属性値を更新します。属性が存在しない場合は、作成されます。 次のクエリは、数値型の属性 (`AwardsWon`) とマップ型の属性 (`AwardDetail`) を追加して、`"Music"` テーブルの項目を更新します。 ``` UPDATE "Music" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' ``` `RETURNING ALL OLD *` を追加すると、`Update` 操作の前に表示されていた属性を返すことができます。 ``` UPDATE "Music" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' RETURNING ALL OLD * ``` 以下が返されます。 ``` { "Items": [ { "Artist": { "S": "Acme Band" }, "SongTitle": { "S": "PartiQL Rocks" } } ] } ``` `RETURNING ALL NEW *` を追加すると、`Update` 操作の後に表示されていた属性を返すことができます。 ``` UPDATE "Music" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' RETURNING ALL NEW * ``` 以下が返されます。 ``` { "Items": [ { "AwardDetail": { "M": { "Grammys": { "L": [ { "N": "2020" }, { "N": "2018" } ] } } }, "AwardsWon": { "N": "1" } } ] } ``` 次のクエリは、`"Music"` テーブルの項目を、`AwardDetail.Grammys` リストに追加して更新します。 ``` UPDATE "Music" SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016]) WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' ``` 次のクエリは、`"Music"` テーブルの項目を、`AwardDetail.Grammys` リストから削除して更新します。 ``` UPDATE "Music" REMOVE AwardDetail.Grammys[2] WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' ``` 次のクエリは、`"Music"` テーブルで `AwardDetail` マップに `BillBoard` を追加して、項目を更新します。 ``` UPDATE "Music" SET AwardDetail.BillBoard=[2020] WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' ``` 次のクエリは、`"Music"` テーブルで、文字列セットの属性 `BandMembers` を追加して、項目を更新します。 ``` UPDATE "Music" SET BandMembers =<<'member1', 'member2'>> WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' ``` 次のクエリは、`"Music"` テーブルで文字列セットの属性 `BandMembers` に `newbandmember` を追加して、項目を更新します。 ``` UPDATE "Music" SET BandMembers =set_add(BandMembers, <<'newbandmember'>>) WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks' ``` # DynamoDB 用の PartiQL 削除ステートメント `DELETE` ステートメントを使用して、Amazon DynamoDB テーブルにある項目を削除します。 **注記** 一度に削除できる項目は 1 つだけです。1 つの DynamoDB PartiQL ステートメントを発行して、複数の項目を削除することはできません。複数のアイテムの削除については、「[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md)」または「[DynamoDB 用の PartiQL を使用してバッチ操作を実行する](ql-reference.multiplestatements.batching.md)」を参照してください。 **Topics** + [構文](#ql-reference.delete.syntax) + [パラメータ](#ql-reference.delete.parameters) + [戻り値](#ql-reference.delete.return) + [例](#ql-reference.delete.examples) ## 構文 ``` DELETE FROM table WHERE condition [RETURNING returnvalues] ::= ALL OLD * ``` ## パラメータ ***テーブル*\$1** (必須) 削除する項目を含む DynamoDB テーブル。 ***condition*** (必須) 削除する項目の選択基準。この条件は、単一のプライマリキー値を解決する必要があります。 ***returnvalues*** (オプション) 削除される前に表示された、項目の属性を取得したい場合には、`returnvalues` を使用します。有効な値は以下のとおりです。 + `ALL OLD *`: 古い項目の内容が返されます。 ## 戻り値 `returnvalues` パラメータが指定されない限り、このステートメントは値を返しません。 **注記** DynamoDB テーブルに、DELETE が発行された項目と同じプライマリキーを持つ項目が無い場合、削除した項目を 0 としたうえで、SUCCESS を返します。テーブルに同じプライマリキーを持つ項目があるが、DELETE ステートメントの WHERE 句の条件で false と評価された場合、`ConditionalCheckFailedException` が返されます。 ## 例 次のクエリは、`"Music"` テーブルの項目を削除します。 ``` DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks' ``` `RETURNING ALL OLD *` を追加すると、削除されたデータを返すことができます。 ``` DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks' RETURNING ALL OLD * ``` `Delete` ステートメントは、以下を返すようになりました。 ``` { "Items": [ { "Artist": { "S": "Acme Band" }, "SongTitle": { "S": "PartiQL Rocks" } } ] } ``` # DynamoDB 用の PartiQL 挿入ステートメント `INSERT` ステートメントを使用して、Amazon DynamoDB のテーブルに項目を追加します。 **注記** 一度に挿入できる項目は 1 つだけです。1 つの DynamoDB PartiQL ステートメントを発行して、複数の項目を挿入することはできません。複数の項目の挿入については、「[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md)」または「[DynamoDB 用の PartiQL を使用してバッチ操作を実行する](ql-reference.multiplestatements.batching.md)」を参照してください。 **Topics** + [構文](#ql-reference.insert.syntax) + [パラメータ](#ql-reference.insert.parameters) + [戻り値](#ql-reference.insert.return) + [例](#ql-reference.insert.examples) ## 構文 項目を 1 つ挿入します。 ``` INSERT INTO table VALUE item ``` ## パラメータ ***テーブル*\$1** (必須) データを挿入するテーブル。このテーブルは既存であることが必要です。 ***item*** (必須) 有効な DynamoDB 項目は [PartiQL タプル](https://partiql.org/docs.html)。*1 つ*の項目のみ指定する必要があります。また、項目の各属性名は大文字と小文字が区別され、PartiQL では*一重*引用符 (`'...'`) で示されます。 文字列値は、PartiQL では*一重*引用符 (`'...'`) で示されます。 ## 戻り値 このステートメントは値を返しません。 **注記** DynamoDB テーブルに、挿入される項目と同じプライマリキーを持つ項目が既にある場合、`DuplicateItemException` が返されます。 ## 例 ``` INSERT INTO "Music" value {'Artist' : 'Acme Band','SongTitle' : 'PartiQL Rocks'} ``` # DynamoDB での PartiQL 関数の使用 Amazon DynamoDB の PartiQL は、次の SQL 標準関数の組み込みバージョンをサポートしています。 **注記** このリストに含まれていない SQL 関数は、DynamoDB で現在サポートされていません。 ## 集計関数 + [Amazon DynamoDB 用の PartiQL で SIZE 関数を使用する](ql-functions.size.md) ## 条件関数 + [DynamoDB 用の PartiQL での EXISTS 関数の使用](ql-functions.exists.md) + [DynamoDB 用の PartiQL で ATTRIBUTE\$1TYPE 関数を使用する](ql-functions.attribute_type.md) + [DynamoDB 用の PartiQL で BEGINS\$1WITH 関数を使用する](ql-functions.beginswith.md) + [DynamoDB 用の PartiQL で CONTAINS 関数を使用する](ql-functions.contains.md) + [DynamoDB 用の PartiQL で MISSING 関数を使用する](ql-functions.missing.md) # DynamoDB 用の PartiQL での EXISTS 関数の使用 EXISTS を使用して、`ConditionCheck` が [TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems) API で実行するのと同じ機能を実行できます。EXISTS 関数は、トランザクションでのみ使用できます。 値が指定されると、値が空でないコレクションである場合に `TRUE` を返します。それ以外の場合は `FALSE` を返します。 **注記** この関数は、トランザクション操作でのみ使用できます。 ## 構文 ``` EXISTS ( statement ) ``` ## 引数 *statement* (必須) 関数が評価する SELECT ステートメント。 SELECT 文では、完全なプライマリキーと他の条件を、1 つ指定する必要があります。 ## 戻り型 `bool` ## 例 ``` EXISTS( SELECT * FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks') ``` # DynamoDB 用の PartiQL で BEGINS\$1WITH 関数を使用する 指定した属性が特定の部分文字列から始まる場合、`TRUE` を返します。 ## 構文 ``` begins_with(path, value ) ``` ## 引数 *パス* (必須) 使用する属性名またはドキュメントのパス。 *value* (必須) 検索対象の文字列。 ## 戻り型 `bool` ## 例 ``` SELECT * FROM "Orders" WHERE "OrderID"=1 AND begins_with("Address", '7834 24th') ``` # DynamoDB 用の PartiQL で MISSING 関数を使用する 指定した属性が項目に含まれていない場合、`TRUE` を返します。この関数では、等価演算子および不等価演算子のみを使用できます。 ## 構文 ``` attributename IS | IS NOT MISSING ``` ## 引数 *attributename* (必須) 検索対象の属性名。 ## 戻り型 `bool` ## 例 ``` SELECT * FROM Music WHERE "Awards" is MISSING ``` # DynamoDB 用の PartiQL で ATTRIBUTE\$1TYPE 関数を使用する 指定したパスの属性が特定のデータ型のものである場合、`TRUE` を返します。 ## 構文 ``` attribute_type( attributename, type ) ``` ## 引数 *attributename* (必須) 使用する属性名。 *type* (必須) チェックする属性タイプ。有効な値のリストについては、DynamoDB の「[attribute\$1type](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)」を参照してください。 ## 戻り型 `bool` ## 例 ``` SELECT * FROM "Music" WHERE attribute_type("Artist", 'S') ``` # DynamoDB 用の PartiQL で CONTAINS 関数を使用する パスで指定した属性が次のいずれかである場合、`TRUE` を返します。 + 特定の部分文字列を含む文字列型。 + 特定の要素を含むセット型。 詳細については、DynamoDB の「[contains](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) 関数」を参照してください。 ## 構文 ``` contains( path, substring ) ``` ## 引数 *パス* (必須) 使用する属性名またはドキュメントのパス。 *substring* (必須) チェックする対象の属性の部分文字列またはセットのメンバー。詳細については、DynamoDB の「[contains](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) 関数」を参照してください。 ## 戻り型 `bool` ## 例 ``` SELECT * FROM "Orders" WHERE "OrderID"=1 AND contains("Address", 'Kirkland') ``` # Amazon DynamoDB 用の PartiQL で SIZE 関数を使用する 属性のサイズを表す数値をバイト単位で返します。Size で使用できる有効なデータ型は、次の通りです。詳細については、DynamoDB の「[size](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) 関数」を参照してください。 ## 構文 ``` size( path) ``` ## 引数 *パス* (必須) 属性名またはドキュメントのパス。 サポートされているタイプについては、DynamoDB の「[size](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) 関数」を参照してください。 ## 戻り型 `int` ## 例 ``` SELECT * FROM "Orders" WHERE "OrderID"=1 AND size("Image") >300 ``` # DynamoDB での PartiQL 算術演算子、比較演算子、論理演算子 Amazon DynamoDB の PartiQL は、次の [SQL 標準演算子](https://www.w3schools.com/sql/sql_operators.asp)をサポートしています。 **注記** このリストに含まれていない SQL 演算子は、DynamoDB で現在サポートされていません。 ## 算術演算子 **** | 演算子 | 説明 | | --- | --- | | \$1 | Add | | - | - (減算) | ## 比較演算子 **** | 演算子 | 説明 | | --- | --- | | = | Equal to | | <> | 等しくない | | \$1= | 等しくない | | > | 超 | | < | 未満 | | >= | 以上 | | <= | 以下 | ## 論理演算子 **** | 演算子 | 説明 | | --- | --- | | AND | TRUE AND で区切られたすべての条件が TRUE の場合に | | BETWEEN | `TRUE` オペランドが比較の範囲内にある場合に この演算子には、適用するオペランドの下限と上限が含まれます。 | | IN | `TRUE` オペランドが (最大 50 ハッシュ属性値、または 100 個の非キー属性値において) 式のリストの 1 つに等しい場合。 結果は最大 10 項目までのページで返されます。`IN` リストにより多くの値が含まれている場合は、レスポンスで返された `NextToken` を使用して後続のページを取得する必要があります。 | | IS | TRUE オペランドが指定されていて、PartiQL のデータ型であり、NULL または MISSING を含む場合に | | NOT | 指定されたブール式の値を反転する | | OR | TRUE OR で区切られた条件のいずれかが TRUEの場合に | 論理演算子の使用の詳細については、「[比較の実行](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Comparators)」および「[論理評価](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.LogicalEvaluations)」を参照してください。 # DynamoDB 用の PartiQL を使用してトランザクションを実行する このセクションでは、DynamoDB 用の PartiQL でトランザクションを使用する方法について説明します。PartiQL トランザクションは、合計 100 件のステートメント (アクション) に制限されています。 DynamoDB トランザクションの詳細については、「[DynamoDB トランザクションで複雑なワークフローを管理する](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html)」を参照してください。 **注記** トランザクション全体は、読み込みステートメントまたは 書き込みステートメントのいずれかで構成されている必要があります。1 つのトランザクションで両方を混在させることはできません。この EXISTS 関数は例外です。[TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems) API オペレーションの `ConditionCheck` と同様に、項目の特定の属性の状態を確認するために使用できます。 **Topics** + [構文](#ql-reference.multiplestatements.transactions.syntax) + [パラメータ](#ql-reference.multiplestatements.transactions.parameters) + [戻り値](#ql-reference.multiplestatements.transactions.return) + [例](#ql-reference.multiplestatements.transactions.examples) ## 構文 ``` [ { "Statement":" statement ", "Parameters":[ { " parametertype " : " parametervalue " }, ...] } , ... ] ``` ## パラメータ ***ステートメント*** (必須) DynamoDB 用の PartiQL がサポートするステートメントです。 トランザクション全体は、読み込みステートメントまたは 書き込みステートメントのいずれかで構成されている必要があります。1 つのトランザクションで両方を混在させることはできません。 ***parametertype*** (オプション) PartiQL ステートメントを指定するときにパラメータが使用された場合のDynamoDB タイプ。 ***parametervalue*** (オプション) PartiQL ステートメントを指定するときにパラメータが使用された場合のパラメータの値。 ## 戻り値 このステートメントは、書き込み操作 (INSERT、UPDATE、DELETE) の値を返しません。ただし、WHERE 句で指定された条件に基づいて、読み取り操作 (SELECT) に対して異なる値を返します。 **注記** シングルトンの INSERT、UPDATE、または DELETE 操作のいずれかでエラーが返された場合、`TransactionCanceledException` 例外によりトランザクションがキャンセルされます。キャンセル理由コードには、個々のシングルトン操作からのエラーが含まれます。 ## 例 以下の例では、トランザクションとして複数のステートメントを実行します。 ------ #### [ AWS CLI ] 1. 次の JSON コードを partiql.json というファイルに保存します ``` [ { "Statement": "EXISTS(SELECT * FROM \"Music\" where Artist='No One You Know' and SongTitle='Call Me Today' and Awards is MISSING)" }, { "Statement": "INSERT INTO Music value {'Artist':?,'SongTitle':'?'}", "Parameters": [{\"S\": \"Acme Band\"}, {\"S\": \"Best Song\"}] }, { "Statement": "UPDATE \"Music\" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist='Acme Band' and SongTitle='PartiQL Rocks'" } ] ``` 1. コマンドプロンプトで、次のコマンドを実行します。 ``` aws dynamodb execute-transaction --transact-statements file://partiql.json ``` ------ #### [ Java ] ``` public class DynamoDBPartiqlTransaction { public static void main(String[] args) { // Create the DynamoDB Client with the region you want AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-2"); try { // Create ExecuteTransactionRequest ExecuteTransactionRequest executeTransactionRequest = createExecuteTransactionRequest(); ExecuteTransactionResult executeTransactionResult = dynamoDB.executeTransaction(executeTransactionRequest); System.out.println("ExecuteTransaction successful."); // Handle executeTransactionResult } catch (Exception e) { handleExecuteTransactionErrors(e); } } private static AmazonDynamoDB createDynamoDbClient(String region) { return AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); } private static ExecuteTransactionRequest createExecuteTransactionRequest() { ExecuteTransactionRequest request = new ExecuteTransactionRequest(); // Create statements List statements = getPartiQLTransactionStatements(); request.setTransactStatements(statements); return request; } private static List getPartiQLTransactionStatements() { List statements = new ArrayList(); statements.add(new ParameterizedStatement() .withStatement("EXISTS(SELECT * FROM "Music" where Artist='No One You Know' and SongTitle='Call Me Today' and Awards is MISSING)")); statements.add(new ParameterizedStatement() .withStatement("INSERT INTO "Music" value {'Artist':'?','SongTitle':'?'}") .withParameters(new AttributeValue("Acme Band"),new AttributeValue("Best Song"))); statements.add(new ParameterizedStatement() .withStatement("UPDATE "Music" SET AwardsWon=1 SET AwardDetail={'Grammys':[2020, 2018]} where Artist='Acme Band' and SongTitle='PartiQL Rocks'")); return statements; } // Handles errors during ExecuteTransaction execution. Use recommendations in error messages below to add error handling specific to // your application use-case. private static void handleExecuteTransactionErrors(Exception exception) { try { throw exception; } catch (TransactionCanceledException tce) { System.out.println("Transaction Cancelled, implies a client issue, fix before retrying. Error: " + tce.getErrorMessage()); } catch (TransactionInProgressException tipe) { System.out.println("The transaction with the given request token is already in progress, consider changing " + "retry strategy for this type of error. Error: " + tipe.getErrorMessage()); } catch (IdempotentParameterMismatchException ipme) { System.out.println("Request rejected because it was retried with a different payload but with a request token that was already used, " + "change request token for this payload to be accepted. Error: " + ipme.getErrorMessage()); } catch (Exception e) { handleCommonErrors(e); } } private static void handleCommonErrors(Exception exception) { try { throw exception; } catch (InternalServerErrorException isee) { System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage()); } catch (RequestLimitExceededException rlee) { System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " + "retrying. Error: " + rlee.getErrorMessage()); } catch (ProvisionedThroughputExceededException ptee) { System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " + "Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " + ptee.getErrorMessage()); } catch (ResourceNotFoundException rnfe) { System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage()); } catch (AmazonServiceException ase) { System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " + "service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " + "configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage()); } catch (AmazonClientException ace) { System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " + "service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+ "Error: " + ace.getMessage()); } catch (Exception e) { System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage()); } } } ``` ------ 次の例は、DynamoDB が WHERE 句で指定された異なる条件を持つ項目を読み取るときのさまざまな戻り値を示しています。 ------ #### [ AWS CLI ] 1. 次の JSON コードを partiql.json というファイルに保存します ``` [ // Item exists and projected attribute exists { "Statement": "SELECT * FROM "Music" WHERE Artist='No One You Know' and SongTitle='Call Me Today'" }, // Item exists but projected attributes do not exist { "Statement": "SELECT non_existent_projected_attribute FROM "Music" WHERE Artist='No One You Know' and SongTitle='Call Me Today'" }, // Item does not exist { "Statement": "SELECT * FROM "Music" WHERE Artist='No One I Know' and SongTitle='Call You Today'" } ] ``` 1. コマンドプロンプトで、次のコマンドを実行します。 ``` aws dynamodb execute-transaction --transact-statements file://partiql.json ``` 1. 以下のレスポンスが返されます。 ``` { "Responses": [ // Item exists and projected attribute exists { "Item": { "Artist":{ "S": "No One You Know" }, "SongTitle":{ "S": "Call Me Today" } } }, // Item exists but projected attributes do not exist { "Item": {} }, // Item does not exist {} ] } ``` ------ # DynamoDB 用の PartiQL を使用してバッチ操作を実行する このセクションでは、DynamoDB 用の PartiQL でバッチステートメントを使用する方法について説明します。 **注記** バッチ全体は、読み取りステートメントまたは書き込みステートメントのいずれかで構成する必要があります。1 つのバッチに両方を混在させることはできません。 `BatchExecuteStatement` と `BatchWriteItem` が実行できるステートメントの数は、バッチあたり 25 が上限です。 `BatchExecuteStatement` は、`BatchGetItem` を使用して、個別のステートメントでプライマリキーのリストを取得します。 **Topics** + [構文](#ql-reference.multiplestatements.batching.syntax) + [パラメータ](#ql-reference.multiplestatements.batching.parameters) + [例](#ql-reference.multiplestatements.batching.examples) ## 構文 ``` [ { "Statement": "SELECT pk FROM ProblemSet WHERE pk = 'p#9StkWHYTxm7x2AqSXcrfu7' AND sk = 'info'" }, { "Statement": "SELECT pk FROM ProblemSet WHERE pk = 'p#isC2ChceGbxHgESc4szoTE' AND sk = 'info'" } ] ``` ``` [ { "Statement":" statement ", "Parameters":[ { " parametertype " : " parametervalue " }, ...] } , ... ] ``` ## パラメータ ***ステートメント*** (必須) DynamoDB 用の PartiQL がサポートするステートメントです。 + バッチ全体は、読み取りステートメントまたは書き込みステートメントのいずれかで構成する必要があります。1 つのバッチに両方を混在させることはできません。 + `BatchExecuteStatement` と `BatchWriteItem` が実行できるステートメントの数は、バッチあたり 25 が上限です。 ***parametertype*** (オプション) PartiQL ステートメントを指定するときにパラメータが使用された場合のDynamoDB タイプ。 ***parametervalue*** (オプション) PartiQL ステートメントを指定するときにパラメータが使用された場合のパラメータの値。 ## 例 ------ #### [ AWS CLI ] 1. 次の json を partiql.json というファイルに保存します ``` [ { "Statement": "INSERT INTO Music VALUE {'Artist':?,'SongTitle':?}", "Parameters": [{"S": "Acme Band"}, {"S": "Best Song"}] }, { "Statement": "UPDATE Music SET AwardsWon=1, AwardDetail={'Grammys':[2020, 2018]} WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'" } ] ``` 1. コマンドプロンプトで、次のコマンドを実行します。 ``` aws dynamodb batch-execute-statement --statements file://partiql.json ``` ------ #### [ Java ] ``` public class DynamoDBPartiqlBatch { public static void main(String[] args) { // Create the DynamoDB Client with the region you want AmazonDynamoDB dynamoDB = createDynamoDbClient("us-west-2"); try { // Create BatchExecuteStatementRequest BatchExecuteStatementRequest batchExecuteStatementRequest = createBatchExecuteStatementRequest(); BatchExecuteStatementResult batchExecuteStatementResult = dynamoDB.batchExecuteStatement(batchExecuteStatementRequest); System.out.println("BatchExecuteStatement successful."); // Handle batchExecuteStatementResult } catch (Exception e) { handleBatchExecuteStatementErrors(e); } } private static AmazonDynamoDB createDynamoDbClient(String region) { return AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); } private static BatchExecuteStatementRequest createBatchExecuteStatementRequest() { BatchExecuteStatementRequest request = new BatchExecuteStatementRequest(); // Create statements List statements = getPartiQLBatchStatements(); request.setStatements(statements); return request; } private static List getPartiQLBatchStatements() { List statements = new ArrayList(); statements.add(new BatchStatementRequest() .withStatement("INSERT INTO Music value {'Artist':'Acme Band','SongTitle':'PartiQL Rocks'}")); statements.add(new BatchStatementRequest() .withStatement("UPDATE Music set AwardDetail.BillBoard=[2020] where Artist='Acme Band' and SongTitle='PartiQL Rocks'")); return statements; } // Handles errors during BatchExecuteStatement execution. Use recommendations in error messages below to add error handling specific to // your application use-case. private static void handleBatchExecuteStatementErrors(Exception exception) { try { throw exception; } catch (Exception e) { // There are no API specific errors to handle for BatchExecuteStatement, common DynamoDB API errors are handled below handleCommonErrors(e); } } private static void handleCommonErrors(Exception exception) { try { throw exception; } catch (InternalServerErrorException isee) { System.out.println("Internal Server Error, generally safe to retry with exponential back-off. Error: " + isee.getErrorMessage()); } catch (RequestLimitExceededException rlee) { System.out.println("Throughput exceeds the current throughput limit for your account, increase account level throughput before " + "retrying. Error: " + rlee.getErrorMessage()); } catch (ProvisionedThroughputExceededException ptee) { System.out.println("Request rate is too high. If you're using a custom retry strategy make sure to retry with exponential back-off. " + "Otherwise consider reducing frequency of requests or increasing provisioned capacity for your table or secondary index. Error: " + ptee.getErrorMessage()); } catch (ResourceNotFoundException rnfe) { System.out.println("One of the tables was not found, verify table exists before retrying. Error: " + rnfe.getErrorMessage()); } catch (AmazonServiceException ase) { System.out.println("An AmazonServiceException occurred, indicates that the request was correctly transmitted to the DynamoDB " + "service, but for some reason, the service was not able to process it, and returned an error response instead. Investigate and " + "configure retry strategy. Error type: " + ase.getErrorType() + ". Error message: " + ase.getErrorMessage()); } catch (AmazonClientException ace) { System.out.println("An AmazonClientException occurred, indicates that the client was unable to get a response from DynamoDB " + "service, or the client was unable to parse the response from the service. Investigate and configure retry strategy. "+ "Error: " + ace.getMessage()); } catch (Exception e) { System.out.println("An exception occurred, investigate and configure retry strategy. Error: " + e.getMessage()); } } } ``` ------ # DynamoDB 用 PartiQL における IAM セキュリティポリシー 以下のアクセス権限が必要です。 + DynamoDB 用の PartiQL を使用して項目を読み込むには、`dynamodb:PartiQLSelect` アクセス許可を、テーブルまたはインデックスに付与します。 + DynamoDB 用の PartiQL を使用して項目を挿入するには、`dynamodb:PartiQLInsert` アクセス許可をテーブルまたはインデックスに付与します。 + DynamoDB 用の PartiQL を使用して項目を更新するには、`dynamodb:PartiQLUpdate` アクセス許可をテーブルまたはインデックスに付与します。 + DynamoDB 用の PartiQL を使用して項目を削除するには、`dynamodb:PartiQLDelete` アクセス許可をテーブルまたはインデックスに付与します。 ## 例: テーブルに対して、すべての DynamoDB 用の PartiQL ステートメントを許可する (選択、挿入、更新、削除) 次の IAM ポリシーは、すべての DynamoDB 用の PartiQL ステートメントをテーブルに対して実行するための、アクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ] } ] } ``` ------ ## 例: テーブルに対して、DynamoDB 用の PartiQL 選択ステートメントを許可する 次の IAM ポリシーは、特定のテーブルに対して `select` ステートメントを実行するためのアクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ] } ] } ``` ------ ## 例: インデックスに対して、DynamoDB 用の PartiQL 挿入ステートメントを許可する 次の IAM ポリシーは、特定のインデックスに対して `insert` ステートメントを実行するためのアクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music/index/index1" ] } ] } ``` ------ ## 例: テーブルに対して、DynamoDB 用の PartiQL トランザクションステートメントを許可する 次の IAM ポリシーは、特定のテーブルに対してトランザクションステートメントだけを実行するためのアクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ], "Condition":{ "StringEquals":{ "dynamodb:EnclosingOperation":[ "ExecuteTransaction" ] } } } ] } ``` ------ ## 例: テーブルに対して、DynamoDB 用の PartiQL 非トランザクションの読み込み/書き込みステートメントを許可し、PartiQL 読み込み/書き込みトランザクションをブロックします。 次の IAM ポリシーは、DynamoDB 用の PartiQL トランザクション読み込み/書き込みをブロックしている間に、DynamoDB 用の PartiQL 非トランザクションの読み込み/書き込みを実行するためのアクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Deny", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ], "Condition":{ "StringEquals":{ "dynamodb:EnclosingOperation":[ "ExecuteTransaction" ] } } }, { "Effect":"Allow", "Action":[ "dynamodb:PartiQLInsert", "dynamodb:PartiQLUpdate", "dynamodb:PartiQLDelete", "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/Music" ] } ] } ``` ------ ## 例: DynamoDB 用の PartiQL で ステートメントの選択を許可し、テーブル全体のスキャンを行うステートメントを拒否する 次の IAM ポリシーは、テーブル全体のスキャンを行う `select` ステートメントをブロックしている間に、特定のテーブルに対して `select` ステートメントを実行するためのアクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Deny", "Action":[ "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/WatchList" ], "Condition":{ "Bool":{ "dynamodb:FullTableScan":[ "true" ] } } }, { "Effect":"Allow", "Action":[ "dynamodb:PartiQLSelect" ], "Resource":[ "arn:aws:dynamodb:us-west-2:123456789012:table/WatchList" ] } ] } ``` ------