DynamoDB兼容API范围限制与差异-云原生数据库 PolarDB-阿里云-云原生数据库 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	是	是	-