PolarDB DynamoDB API 互換性概要 - PolarDB

PolarDB for PostgreSQL は、Amazon DynamoDB の主要な API と高い互換性を備えています。PolarDB をご利用になる前、またはデータ移行を実施する前に、本トピックで互換性の範囲、使用制限、および動作の相違点を確認することを推奨します。これにより、業務の安定かつ円滑な運用を確保できます。

互換性評価ツール：polardb_ddb_code_digest

既存プロジェクトの PolarDB との互換性を効率的に評価するために、PolarDB では、ローカル静的コード解析ツール polardb_ddb_code_digest.tar.gz を提供しています。

動作仕組み

コードスキャン：ツールは、指定したプロジェクトディレクトリを再帰的にスキャンし、ソースファイルを検出し解析します。現在、Go および Python がサポートされています。
API 解析：ツールは、AWS 公式 SDK の仕様に基づき、すべての DynamoDB API 呼び出し、パラメーター名、定数、および式構造を抽出します。
レポート生成：ツールは、収集した情報をビジネスデータ値をすべて削除して機密情報除去を行い、構造化された API 使用状況レポートを生成します。このレポートには、プロジェクト内で使用されている API、パラメーター、およびその使用頻度が明確に一覧表示されます。

このレポートを用いて、本ドキュメントに記載された制限事項に対する自己評価を実施できます。

手順

ローカル静的コード解析ツール polardb_ddb_code_digest.tar.gz をアプリケーション環境にダウンロードします。
ファイルを展開し、展開先ディレクトリに移動した後、以下のコマンドを実行してプロジェクト依存関係をインストールします。
1. Python 環境：Python 3.9.6 以降が必要です。
2. （任意）必要に応じて仮想環境を作成できます。これにより、プロジェクトの依存関係がグローバル環境に影響を与えることを防止できます。
```
python3 -m venv venv && source venv/bin/activate
```
3. プロジェクト依存関係をインストールします。
```
pip3 install -r requirements.txt
```
ソースファイルを検出し解析します：
- ソースファイルが Python ファイル（フォルダ内）の場合：python3 main.py --dir <path/to/dir> --lang python > scan_output.log
- ソースファイルが Go ファイル（フォルダ内）の場合：python3 main.py --dir <path/to/dir> --lang go > scan_output.log

制限事項および動作の相違点

重要な情報を素早く特定できるよう、本セクションでは、PolarDB とネイティブ DynamoDB の主な機能および動作の相違点を一覧表示します。

一般的な制限事項

非推奨パラメーター：PolarDB は、新しい API 仕様に準拠しています。そのため、AttributeUpdates、Expected、または AttributesToGet などの非推奨パラメーターは、システムによって無視されるかエラーとして報告されます。アプリケーションでは、対応する新規パラメーター（例：UpdateExpression、ConditionExpression、ProjectionExpression）をご利用ください。
エラーメッセージ：一部の操作における応答のエラーメッセージは、ネイティブ DynamoDB と完全に一致しない場合があります。
強力な整合性読み取り：API リクエストで ConsistentRead=true パラメーターを指定して単一の強力な整合性読み取りを行うことはサポートされていません。整合性レベルは、DynamoDB エンドポイントで設定してください。
統計および課金パラメーター：課金およびキャパシティ消費に関連するすべてのリクエストパラメーター（例：ReturnConsumedCapacity）および応答フィールド（例：ConsumedCapacity）は、無視されるか返されません。
インデックス投影：セカンダリインデックスに対して投影属性（NonKeyAttributes）を指定する場合、投影対象のフィールドにはテーブルのプライマリキー（パーティションキーまたはソートキー）や、インデックス自体のプライマリキーを含めることはできません。

API 別の動作の相違点

UpdateItem
- REMOVE a.b を使用して存在しないネストされた属性を削除しようとした場合（つまり親属性 a が存在しない場合）、ネイティブ DynamoDB ではエラーが返されます。一方、PolarDB では、処理は静かに成功し、実際には何も実行されません。
BatchWriteItem
- アトミシティ: PolarDB では、バッチ書き込みはアトミック操作です。リクエスト内のすべての操作は、すべて成功するか、すべて失敗します。したがって、応答内のUnprocessedItems フィールドは常に Empty です。
- プライマリキーの競合：ネイティブの DynamoDB では、1つのリクエスト内で同じプライマリキーに対して PutItem および DeleteItem 操作を実行できません。ただし、PolarDB では現在、これらの操作が許可されています。
BatchGetItem
- アトミック操作：バッチ書き込みと同様に、バッチ読み取りもアトミック操作です。したがって、応答内の UnprocessedKeys フィールドは常に空になります。
- 重複するプライマリキー：ネイティブ DynamoDB では、リクエスト内で重複するプライマリキーを指定することは許可されていません。PolarDB では、重複するプライマリキーを許可しており、各重複キーに対して 1 件のデータ項目を返します。
Query/Scan
- 応答内の ScannedCount および Count の値は常に等しくなります。これらの値は、フィルター（FilterExpression）適用前のアイテム数と適用後のアイテム数を区別しません。
TransactWriteItems
- プライマリキーの競合：ネイティブ DynamoDB では、単一トランザクション内で同一のプライマリキーに対して複数の操作を実行することは許可されていません。一方、PolarDB では、現時点でこれらの操作が許可されています。
- 失敗時の動作：条件チェックに失敗したためにトランザクションがキャンセルされた場合、ネイティブ DynamoDB では、すべての操作を試行した後に各操作のステータスを含むリストを返します。
```
// ネイティブ DynamoDB の失敗応答の例
TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None, ConditionalCheckFailed]
```
  一方、PolarDB では、最初に失敗した操作に遭遇すると直ちにトランザクションを中止し、比較的簡潔なエラーメッセージを返します。
```
// PolarDB の失敗応答の例
ConditionalCheckFailedException: The conditional request failed
```
TransactGetItems
- プライマリキーの競合：ネイティブ DynamoDB では、単一トランザクション内で同一のプライマリキーに対して複数の操作を実行することは許可されていません。一方、PolarDB では、現時点でこれらの操作が許可されています。

詳細なコマンドおよびパラメーター対応状況

説明

サポートされているカラム：
- 「はい」は、該当パラメーターがサポートされていることを示します。
- 「いいえ」は、該当パラメーターがサポートされていないことを示します。
「備考」カラムには、サポートされていないパラメーターまたは特殊な動作をするパラメーターについての追加説明を記載します。

CreateTable

API 名	パラメーター種別	パラメーター名	必須	対応	備考
CreateTable	リクエストパラメーター	AttributeDefinitions	はい	はい	-
		KeySchema	はい	はい	-
		TableName	はい	はい	-
		BillingMode	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		DeletionProtectionEnabled	いいえ	はい	-
		GlobalSecondaryIndexes	いいえ	はい	-
		LocalSecondaryIndexes	いいえ	はい	-
		OnDemandThroughput	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		ProvisionedThroughput	いいえ	はい	リクエストに含まれている場合、無視されます。
		ResourcePolicy	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		SSESpecification	いいえ	いいえ	このパラメーターがリクエストに含まれている場合、無視されます。説明暗号化が必要な場合は、「TDE の設定」をご参照ください。
		StreamSpecification	いいえ	いいえ	リクエストに含まれている場合、無視されます。説明ストリーミングレプリケーションが必要な場合は、「サブスクリプション管理」をご参照ください。
		TableClass	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		Tags	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		WarmThroughput	いいえ	いいえ	リクエストに含まれている場合、無視されます。
	応答パラメーター	TableDescription	-	はい	-

DescribeTable

API 名	パラメーター種別	パラメーター名	必須	対応?	備考
DescribeTable	リクエストパラメーター	TableName	はい	はい	-
DescribeTable	応答パラメーター	Table	-	はい	-

ListTables

API 名	パラメーター種別	パラメーター名	必須	対応	備考
ListTables	リクエストパラメーター	ExclusiveStartTableName	いいえ	はい	-
	リクエストパラメーター	Limit	いいえ	はい	-
	応答パラメーター	LastEvaluatedTableName	-	はい	-
	応答パラメーター	TableNames	-	はい	-

UpdateTable

API 名	パラメーター種別	パラメーター名	必須	対応	備考
UpdateTable	リクエストパラメーター	TableName	はい	はい	-
		AttributeDefinitions	いいえ	はい	-
		BillingMode	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		DeletionProtectionEnabled	いいえ	はい	-
		GlobalSecondaryIndexUpdates	いいえ	はい	これは同期操作です。業務の閑散時間帯に実行してください。
		GlobalTableWitnessUpdates	いいえ	いいえ	リクエストに含まれている場合、エラーが報告されます。
		MultiRegionConsistency	いいえ	いいえ	リクエストに含まれている場合、エラーが報告されます。
		OnDemandThroughput	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		ProvisionedThroughput	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		ReplicaUpdates	いいえ	いいえ	リクエストに含まれている場合、エラーが報告されます。
		SSESpecification	いいえ	いいえ	このパラメーターがリクエストに含まれている場合、無視されます。説明暗号化が必要な場合は、「TDE の設定」をご参照ください。
		StreamSpecification	いいえ	いいえ	リクエストに含まれている場合、無視されます。説明ストリーミングレプリケーションが必要な場合は、「サブスクリプション管理」をご参照ください。
		TableClass	いいえ	いいえ	リクエストに含まれている場合、無視されます。
		WarmThroughput	いいえ	いいえ	リクエストに含まれている場合、無視されます。
	応答パラメーター	TableDescription	-	はい	-

DeleteTable

API 名	パラメーター種別	パラメーター名	必須	対応ですか？	備考
DeleteTable	リクエストパラメーター	TableName	はい	はい	-
DeleteTable	応答パラメーター	TableDescription	-	はい	-

PutItem

API 名	パラメーター種別	パラメーター名	必須	対応ですか？	備考
PutItem	リクエストパラメーター	Item	はい	はい	-
		TableName	はい	はい	-
		ConditionalOperator	いいえ	いいえ	非推奨。代わりに `ConditionExpression` を使用してください。
		ConditionExpression	いいえ	はい	-
		Expected	いいえ	いいえ	非推奨。代わりに `ConditionExpression` を使用してください。
		ExpressionAttributeNames	いいえ	はい	-
		ExpressionAttributeValues	いいえ	はい	-
		ReturnConsumedCapacity	いいえ	はい	課金関連パラメーター。無視されます。
		ReturnItemCollectionMetrics	いいえ	いいえ	統計関連パラメーター。サポートされていません。
		ReturnValues	いいえ	はい	-
		ReturnValuesOnConditionCheckFailure	いいえ	はい	-
	応答パラメーター	Attributes	-	はい	-
		ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		ItemCollectionMetrics	-	いいえ	統計関連パラメーター。応答に含まれません。

UpdateItem

API 名	パラメーター種別	パラメーター名	必須	対応	備考
UpdateItem	リクエストパラメーター	Key	はい	はい	-
		TableName	はい	はい	-
		AttributeUpdates	いいえ	いいえ	非推奨。代わりに `UpdateExpression` を使用してください。
		ConditionalOperator	いいえ	いいえ	非推奨。代わりに `UpdateExpression` を使用してください。
		ConditionExpression	いいえ	はい	-
		Expected	いいえ	いいえ	非推奨。代わりに `UpdateExpression` を使用してください。
		ExpressionAttributeNames	いいえ	はい	-
		ExpressionAttributeValues	いいえ	はい	-
		ReturnConsumedCapacity	いいえ	はい	課金関連パラメーター。無視されます。
		ReturnItemCollectionMetrics	いいえ	いいえ	統計関連パラメーター。サポートされていません。
		ReturnValues	いいえ	はい	-
		ReturnValuesOnConditionCheckFailure	いいえ	はい	-
		UpdateExpression	いいえ	はい	-
	応答パラメーター	Attributes	-	はい	-
		ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		ItemCollectionMetrics	-	いいえ	統計関連パラメーター。応答に含まれません。

GetItem

API 名	パラメーター種別	パラメーター名	必須	対応	備考
GetItem	リクエストパラメーター	Key	はい	はい	-
		TableName	はい	はい	-
		AttributesToGet	いいえ	いいえ	非推奨。代わりに `ProjectionExpression` を使用してください。
		ConsistentRead	いいえ	いいえ	`false` のみ設定可能です。デフォルトはセッションの一貫性です。整合性レベルはエンドポイントで設定してください。
		ExpressionAttributeNames	いいえ	はい	-
		ProjectionExpression	いいえ	はい	-
		ReturnConsumedCapacity	いいえ	はい	課金関連パラメーター。無視されます。
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
	応答パラメーター	Item	-	はい	-

DeleteItem

API 名	パラメーター種別	パラメーター名	必須	この機能は対応していますか？	備考
DeleteItem	リクエストパラメーター	Key	はい	はい	-
		TableName	はい	はい	-
		ConditionalOperator	いいえ	いいえ	非推奨。代わりに `ConditionExpression` を使用してください。
		ConditionExpression	いいえ	はい	-
		Expected	いいえ	いいえ	非推奨。代わりに `ConditionExpression` を使用してください。
		ExpressionAttributeNames	いいえ	はい	-
		ExpressionAttributeValues	いいえ	はい	-
		ReturnConsumedCapacity	いいえ	はい	課金関連パラメーター。無視されます。
		ReturnItemCollectionMetrics	いいえ	いいえ	統計関連パラメーター。サポートされていません。
		ReturnValues	いいえ	はい	-
		ReturnValuesOnConditionCheckFailure	いいえ	はい	-
	応答パラメーター	Attributes	-	はい	-
		ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		ItemCollectionMetrics	-	いいえ	統計関連パラメーター。応答に含まれません。

BatchWriteItem

API 名	パラメーター種別	パラメーター名	必須	この機能は対応していますか？	備考
BatchWriteItem	リクエストパラメーター	RequestItems	はい	はい	-
		ReturnConsumedCapacity	いいえ	いいえ	課金関連パラメーター。無視されます。
		ReturnItemCollectionMetrics	いいえ	いいえ	統計関連パラメーター。サポートされていません。
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		ItemCollectionMetrics	-	いいえ	統計関連パラメーター。応答に含まれません。
		UnprocessedItems	-	はい	動作が異なります。常に空です。上記の制限事項をご参照ください。

パラメーター	サブパラメーター	第3レベルのパラメーター	必須	対応	備考
RequestItems	DeleteRequest	Key	はい	はい	-
RequestItems	PutRequest	Item	はい	はい	-

BatchGetItem

API 名	パラメーター種別	パラメーター名	必須	対応	備考
BatchGetItem	リクエストパラメーター	RequestItems	はい	はい	-
	リクエストパラメーター	ReturnConsumedCapacity	いいえ	いいえ	課金関連パラメーター。無視されます。
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		Responses	-	はい	-
		UnprocessedKeys	-	はい	動作が異なります。常に空です。上記の制限事項をご参照ください。

パラメーター	サブパラメーター	必須	対応ですか？	備考
RequestItems	ConsistentRead	いいえ	はい	-
	ExpressionAttributeNames	いいえ	はい	-
	Keys	はい	はい	-
	ProjectionExpression	いいえ	はい	-
	AttributesToGet	いいえ	いいえ	非推奨。代わりに `ProjectionExpression` を使用してください。リクエストに含まれている場合、エラーが報告されます。

Query

API 名	パラメーター種別	パラメーター名	必須	対応ですか？	備考
Query	リクエストパラメーター	TableName	はい	はい	-
		AttributesToGet	いいえ	いいえ	非推奨。代わりに `ProjectionExpression` を使用してください。
		ConditionalOperator	いいえ	いいえ	非推奨。代わりに `FilterExpression` を使用してください。
		ConsistentRead	いいえ	いいえ	`false` のみ設定可能です。デフォルトはセッションの一貫性です。整合性レベルはエンドポイントで設定してください。
		ExclusiveStartKey	いいえ	はい	-
		ExpressionAttributeNames	いいえ	はい	-
		ExpressionAttributeValues	いいえ	はい	-
		FilterExpression	いいえ	はい	-
		IndexName	いいえ	はい	-
		KeyConditionExpression	いいえ	はい	-
		KeyConditions	いいえ	いいえ	非推奨。代わりに `KeyConditionExpression` を使用してください。
		Limit	いいえ	はい	-
		ProjectionExpression	いいえ	はい	-
		QueryFilter	いいえ	いいえ	非推奨。代わりに `FilterExpression` を使用してください。
		ReturnConsumedCapacity	いいえ	いいえ	課金関連パラメーター。無視されます。
		ScanIndexForward	いいえ	はい	-
		Select	いいえ	はい	-
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		Count	-	はい	動作が異なります。常に `ScannedCount` と等しくなります。
		Items	-	はい	-
		LastEvaluatedKey	-	はい	-
		ScannedCount	-	はい	-

Scan

API 名	パラメーター種別	パラメーター名	必須	対応	備考
Scan	リクエストパラメーター	TableName	はい	はい	-
		AttributesToGet	いいえ	いいえ	非推奨。代わりに `ProjectionExpression` を使用してください。
		ConditionalOperator	いいえ	いいえ	非推奨。代わりに `FilterExpression` を使用してください。
		ConsistentRead	いいえ	いいえ	`false` のみ設定可能です。整合性レベルはエンドポイントで設定してください。
		ExclusiveStartKey	いいえ	はい	-
		ExpressionAttributeNames	いいえ	はい	-
		ExpressionAttributeValues	いいえ	はい	-
		FilterExpression	いいえ	はい	-
		IndexName	いいえ	はい	-
		Limit	いいえ	はい	-
		ProjectionExpression	いいえ	はい	-
		ReturnConsumedCapacity	いいえ	いいえ	課金関連パラメーター。無視されます。
		ScanFilter	いいえ	いいえ	非推奨。代わりに `FilterExpression` を使用してください。
		Segment	いいえ	いいえ	サポートされていません。リクエストに含まれている場合、エラーが報告されます。
		Select	いいえ	はい	-
		TotalSegments	いいえ	はい	-
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
		Count	-	はい	動作が異なります。常に `ScannedCount` と等しくなります。
		Items	-	はい	-
		LastEvaluatedKey	-	はい	-
		ScannedCount	-	はい	-

TransactWriteItems

API 名	パラメーター種別	パラメーター名	必須	対応していますか？	備考
TransactWriteItems	リクエストパラメーター	TransactItems	はい	はい	-
		ClientRequestToken	いいえ	はい	-
		ReturnConsumedCapacity	いいえ	はい	課金関連パラメーター。無視されます。
		ReturnItemCollectionMetrics	いいえ	いいえ	統計関連パラメーター。サポートされていません。
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
	応答パラメーター	ItemCollectionMetrics	-	いいえ	統計関連パラメーター。応答に含まれません。

パラメーター	サブパラメーター	必須	対応	備考
TransactItems	ConditionCheck	いいえ	はい	-
	Put	いいえ	はい	-
	Update	いいえ	はい	-
	Delete	いいえ	はい	-

TransactGetItems

API 名	パラメーター種別	パラメーター名	必須	対応	備考
TransactGetItems	リクエストパラメーター	TransactItems	はい	はい	-
	リクエストパラメーター	ReturnConsumedCapacity	いいえ	はい	課金関連パラメーター。無視されます。
	応答パラメーター	ConsumedCapacity	-	いいえ	課金関連パラメーター。応答に含まれません。
	応答パラメーター	Responses	-	はい	-

DescribeTimeToLive

API 名	パラメーター種別	パラメーター名	必須	対応	備考
DescribeTimeToLive	リクエストパラメーター	TableName	はい	はい	-
DescribeTimeToLive	応答パラメーター	TimeToLiveDescription	-	はい	-

UpdateTimeToLive

API 名	パラメーター種別	パラメーター名	必須	対応	備考
UpdateTimeToLive	リクエストパラメーター	TableName	はい	はい	-
	リクエストパラメーター	TimeToLiveSpecification	はい	はい	-
	応答パラメーター	TimeToLiveSpecification	-	はい	-

パラメーター	サブパラメーター	必須	対応	備考
TimeToLiveSpecification	AttributeName	はい	はい	-
TimeToLiveSpecification	Enabled	はい	はい	-