PolarDB PostgreSQL的DynamoDB相容API支援範圍與使用限制-雲原生資料庫 PolarDB-阿里雲 - PolarDB

PolarDB PostgreSQL版提供了對Amazon DynamoDB主流API的高度相容。但在計劃使用或進行資料移轉前，請務必詳細閱讀本章節，以充分瞭解其相容範圍、使用限制和行為差異，確保您的業務能夠平滑、穩定地運行。

相容性評估工具：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環境：需為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在功能和行為上的主要差異。

通用限制

廢棄參數：本功能遵循較新版本的API規範。對於已廢棄的舊版參數（如AttributeUpdates、Expected或AttributesToGet等），系統會忽略或直接報錯。請確保您的應用程式使用對應的新版參數（如UpdateExpression、ConditionExpression或ProjectionExpression）。
錯誤資訊：部分操作的錯誤響應資訊可能與原生DynamoDB不完全一致。
統計與計費參數：所有與計費和容量消耗相關的請求參數（如ReturnConsumedCapacity）和返回欄位（如ConsumedCapacity）都會被忽略或不返回。
索引投影：為二級索引指定投影屬性（NonKeyAttributes）時，投影的欄位不能包含表的主鍵（分區鍵、排序鍵）或該索引自身的主鍵。

API特定行為差異

UpdateItem
- 當使用REMOVE a.b移除一個不存在的嵌套屬性時（即父屬性a不存在），原生DynamoDB會報錯，而PolarDB會靜默成功，不執行任何操作。
BatchWriteItem
- 原子性：PolarDB中的批量寫入是原子操作，即請求內的所有操作要麼全部成功，要麼全部失敗。因此，返回結果中的UnprocessedItems欄位將始終為空白。
- 主鍵衝突：原生DynamoDB不允許在同一次請求中對同一個主鍵執行PutItem和DeleteItem，而PolarDB當前允許此類操作。
BatchGetItem
- 原子性：與批量寫入類似，批量讀取也是原子操作。因此，返回結果中的UnprocessedKeys欄位將始終為空白。
- 主鍵重複：原生DynamoDB不允許在請求中包含重複的主鍵，而PolarDB允許，並將為每個重複的主鍵返回一條資料。
Query/Scan
- 返回結果中的ScannedCount（掃描計數）與Count（返回計數）的數值始終相等，不區分應用過濾器（FilterExpression）前後的專案數量。
TransactionGetItem/TransactionWriteItem
- 原生DynamoDB不允許在單筆事務中對同一個主鍵進行多次操作，而PolarDB當前允許此類操作。
- TransactionCanceledException目前只可能包含ConditionalCheckFailed和TransactionConflict兩種Reason。ItemCollectionSizeLimitExceeded、ProvisionedThroughputExceeded和ThrottlingError在PolarDB不會發生。任何ValidationError都會以CommonError的形式拋出，而不是在某些情境下成為TransactionCanceledException的一個Reason。

詳細命令與參數支援

說明

是否支援列：
- 是：表示支援該參數。
- 否：表示不支援該參數。
備忘列：對不支援或行為有特殊說明的參數進行了補充解釋。

CreateTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
CreateTable	請求參數	AttributeDefinitions	是	是	-
		KeySchema	是	是	-
		TableName	是	是	-
		BillingMode	否	否	請求中包含此項時，會被忽略。
		DeletionProtectionEnabled	否	是	-
		GlobalSecondaryIndexes	否	是	-
		LocalSecondaryIndexes	否	是	-
		OnDemandThroughput	否	否	請求中包含此項時，會被忽略。
		ProvisionedThroughput	否	是	請求中包含此項時，會被忽略。
		ResourcePolicy	否	否	請求中包含此項時，會被忽略。
		SSESpecification	否	否	請求中包含此項時，會被忽略。說明如有加密需求，請使用設定透明資料加密TDE。
		StreamSpecification	否	否	請求中包含此項時，會被忽略。說明如有流複製需求，請使用訂閱管理。
		TableClass	否	否	請求中包含此項時，會被忽略。
		Tags	否	否	請求中包含此項時，會被忽略。
		WarmThroughput	否	否	請求中包含此項時，會被忽略。
	返回參數	TableDescription	-	是	-

DescribeTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DescribeTable	請求參數	TableName	是	是	-
DescribeTable	返回參數	Table	-	是	-

ListTables

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
ListTables	請求參數	ExclusiveStartTableName	否	是	-
	請求參數	Limit	否	是	-
	返回參數	LastEvaluatedTableName	-	是	-
	返回參數	TableNames	-	是	-

UpdateTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UpdateTable	請求參數	TableName	是	是	-
		AttributeDefinitions	否	是	-
		BillingMode	否	否	請求中包含此項時，會被忽略。
		DeletionProtectionEnabled	否	是	-
		GlobalSecondaryIndexUpdates	否	是	建議在業務低峰期進行執行。
		GlobalTableWitnessUpdates	否	否	請求中包含此項時，會報錯。
		MultiRegionConsistency	否	否	請求中包含此項時，會報錯。
		OnDemandThroughput	否	否	請求中包含此項時，會被忽略。
		ProvisionedThroughput	否	否	請求中包含此項時，會被忽略。
		ReplicaUpdates	否	否	請求中包含此項時，會報錯。
		SSESpecification	否	否	請求中包含此項時，會被忽略。說明如有加密需求，請使用設定透明資料加密TDE。
		StreamSpecification	否	否	請求中包含此項時，會被忽略。說明如有流複製需求，請使用訂閱管理。
		TableClass	否	否	請求中包含此項時，會被忽略。
		WarmThroughput	否	否	請求中包含此項時，會被忽略。
	返回參數	TableDescription	-	是	-

DeleteTable

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DeleteTable	請求參數	TableName	是	是	-
DeleteTable	返回參數	TableDescription	-	是	-

PutItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
PutItem	請求參數	Item	是	是	-
		TableName	是	是	-
		ConditionalOperator	否	否	已廢棄。請使用`ConditionExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已廢棄。請使用`ConditionExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
		ReturnValues	否	是	-
		ReturnValuesOnConditionCheckFailure	否	是	-
	返回參數	Attributes	-	是	-
		ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-

UpdateItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UpdateItem	請求參數	Key	是	是	-
		TableName	是	是	-
		AttributeUpdates	否	否	已廢棄。請使用`UpdateExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`UpdateExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已廢棄。請使用`UpdateExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
		ReturnValues	否	是	-
		ReturnValuesOnConditionCheckFailure	否	是	-
		UpdateExpression	否	是	-
	返回參數	Attributes	-	是	-
		ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-

GetItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
GetItem	請求參數	Key	是	是	-
		TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConsistentRead	否	是	-
		ExpressionAttributeNames	否	是	-
		ProjectionExpression	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	Item	-	是	-

DeleteItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DeleteItem	請求參數	Key	是	是	-
		TableName	是	是	-
		ConditionalOperator	否	否	已廢棄。請使用`ConditionExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已廢棄。請使用`ConditionExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
		ReturnValues	否	是	-
		ReturnValuesOnConditionCheckFailure	否	是	-
	返回參數	Attributes	-	是	-
		ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-

BatchWriteItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
BatchWriteItem	請求參數	RequestItems	是	是	-
		ReturnConsumedCapacity	否	否	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		ItemCollectionMetrics	-	是	-
		UnprocessedItems	-	是	行為有差異，恒為空白。見上方限制說明。

參數	二級參數	三級參數	是否必選	是否支援	備忘
RequestItems	DeleteRequest	Key	是	是	-
RequestItems	PutRequest	Item	是	是	-

BatchGetItem

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
BatchGetItem	請求參數	RequestItems	是	是	-
	請求參數	ReturnConsumedCapacity	否	否	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		Responses	-	是	-
		UnprocessedKeys	-	是	行為有差異，恒為空白。見上方限制說明。

參數	二級參數	是否必選	是否支援	備忘
RequestItems	ConsistentRead	否	是	-
	ExpressionAttributeNames	否	是	-
	Keys	是	是	-
	ProjectionExpression	否	是	-
	AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`，請求中包含此項將報錯。

Query

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
Query	請求參數	TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`FilterExpression`。
		ConsistentRead	否	是	-
		ExclusiveStartKey	否	是	-
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		FilterExpression	否	是	-
		IndexName	否	是	-
		KeyConditionExpression	否	是	-
		KeyConditions	否	否	已廢棄。請使用`KeyConditionExpression`。
		Limit	否	是	-
		ProjectionExpression	否	是	-
		QueryFilter	否	否	已廢棄。請使用`FilterExpression`。
		ReturnConsumedCapacity	否	否	計費相關參數，會被忽略。
		ScanIndexForward	否	是	-
		Select	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		Count	-	是	行為有差異，恒等於`ScannedCount`。
		Items	-	是	-
		LastEvaluatedKey	-	是	-
		ScannedCount	-	是	-

Scan

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
Scan	請求參數	TableName	是	是	-
		AttributesToGet	否	否	已廢棄。請使用`ProjectionExpression`。
		ConditionalOperator	否	否	已廢棄。請使用`FilterExpression`。
		ConsistentRead	否	是	-
		ExclusiveStartKey	否	是	-
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		FilterExpression	否	是	-
		IndexName	否	是	-
		Limit	否	是	-
		ProjectionExpression	否	是	-
		ReturnConsumedCapacity	否	否	計費相關參數，會被忽略。
		ScanFilter	否	否	已廢棄。請使用`FilterExpression`。
		Segment	否	否	暫不支援，請求中包含此項將報錯。
		Select	否	是	-
		TotalSegments	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
		Count	-	是	行為有差異，恒等於`ScannedCount`。
		Items	-	是	-
		LastEvaluatedKey	-	是	-
		ScannedCount	-	是	-

TransactWriteItems

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
TransactWriteItems	請求參數	TransactItems	是	是	-
		ClientRequestToken	否	是	-
		ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
		ReturnItemCollectionMetrics	否	是	-
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	ItemCollectionMetrics	-	是	-

參數	二級參數	是否必選	是否支援	備忘
TransactItems	ConditionCheck	否	是	-
	Put	否	是	-
	Update	否	是	-
	Delete	否	是	-

TransactGetItems

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
TransactGetItems	請求參數	TransactItems	是	是	-
	請求參數	ReturnConsumedCapacity	否	是	計費相關參數，會被忽略。
	返回參數	ConsumedCapacity	-	否	計費相關參數，不返回。
	返回參數	Responses	-	是	-

DescribeTimeToLive

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
DescribeTimeToLive	請求參數	TableName	是	是	-
DescribeTimeToLive	返回參數	TimeToLiveDescription	-	是	-

UpdateTimeToLive

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UpdateTimeToLive	請求參數	TableName	是	是	-
	請求參數	TimeToLiveSpecification	是	是	-
	返回參數	TimeToLiveSpecification	-	是	-

參數	二級參數	是否必選	是否支援	備忘
TimeToLiveSpecification	AttributeName	是	是	-
TimeToLiveSpecification	Enabled	是	是	-

TagResource

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
TagResource	請求參數	ResourceArn	是	是	來自於TableDescription的TableArn欄位。
TagResource	請求參數	Tags	是	是	-

UntagResource

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
UntagResource	請求參數	ResourceArn	是	是	來自於TableDescription的TableArn欄位。
UntagResource	請求參數	TagKeys	是	是	-

ListTagsOfResource

介面名稱	參數類型	參數名	是否必選	是否支援	備忘
ListTagsOfResource	請求參數	ResourceArn	是	是	來自於TableDescription的TableArn欄位。
	請求參數	NextToken	否	是	-
	返回參數	Tags	-	是	-
	返回參數	NextToken	-	是	-

特定的功能差異

下表列出了DynamoDB中與PolarDB架構差異較大的功能類別。這些功能在DynamoDB中通過專有API實現，而PolarDB通過平台自身能力或PostgreSQL生態提供對等方案。

功能類別	DynamoDB介面/參數	PolarDB對等方案
計費相關	`BillingMode`、`ProvisionedThroughput`、`OnDemandThroughput`、`WarmThroughput`、`ReturnConsumedCapacity`、`ConsumedCapacity`	計費模式與DynamoDB不同，相關參數配置後不生效（自動忽略）。
彈性配置	`DescribeTableReplicaAutoScaling`、`UpdateTableReplicaAutoScaling`、`DescribeLimits`	通過Serverless與變更配置實現彈效能力。
PartiQL查詢	`ExecuteStatement`、`ExecuteTransaction`、`BatchExecuteStatement`	同時相容DynamoDB介面與PostgreSQL標準SQL，可直接用SQL滿足複雜查詢需求。
備份與恢複	`CreateBackup`、`DeleteBackup`、`DescribeBackup`、`ListBackups`、`RestoreTableFromBackup`、`RestoreTableToPointInTime`、`DescribeContinuousBackups`、`UpdateContinuousBackups`	支援周期性自動備份與即時生效的手動備份，並支援按時間點恢複（PITR）。詳情請參見備份恢複。
全域表	`CreateGlobalTable`、`DescribeGlobalTable`、`DescribeGlobalTableSettings`、`ListGlobalTables`、`UpdateGlobalTable`、`UpdateGlobalTableSettings`	通過全球資料庫網路（GDN）實現跨地區資料同步與就近讀取。
服務端加密	`SSESpecification`（在`CreateTable`/`UpdateTable`中）	通過設定透明資料加密TDE實現待用資料加密。
DynamoDB Streams	`DescribeStream`、`GetShardIterator`、`GetRecords`、`ListStreams`、`StreamSpecification`	基於PostgreSQL原生邏輯複製，實現資料變更的增量訂閱與下遊消費。詳情請參見訂閱管理。
S3匯入與匯出	`ImportTable`、`ExportTableToPointInTime`、`DescribeExport`、`DescribeImport`、`ListExports`、`ListImports`	基於HTAP能力（內建列存索引（IMCI）），分析查詢可直接線上運行，無需ETL到獨立分析系統。或可通過DTS、OSS外表、邏輯複製對接MaxCompute、AnalyticDB、EMR等巨量資料生態。
資源策略	`GetResourcePolicy`、`PutResourcePolicy`、`DeleteResourcePolicy`、`ResourcePolicy`參數	通過阿里雲帳號使用RAM進行存取控制實現精微調權限管理，資料面採用PostgreSQL原生使用者與許可權體系。
Kinesis流式整合	`DescribeKinesisStreamingDestination`、`EnableKinesisStreamingDestination`、`DisableKinesisStreamingDestination`、`UpdateKinesisStreamingDestination`	通過DTS資料同步或PostgreSQL原生邏輯複製實現流式Data Integration。
貢獻者洞察	`DescribeContributorInsights`、`UpdateContributorInsights`、`ListContributorInsights`	通過資料庫自治服務（DAS）提供SQL洞察、效能監控、慢SQL分析等能力。
服務端點查詢	`DescribeEndpoints`	通過OpenAPI - DescribeDBClusterEndpoints查詢叢集DynamoDB串連地址。