兼容性与限制_云原生数据库 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与原生DynamoDB在功能和行为上的主要差异。

通用限制

废弃参数：本功能遵循较新版本的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字段将始终为空。
- 主键冲突：原生DynamoDB不允许在同一次请求中对同一个主键执行PutItem和DeleteItem，而PolarDB当前允许此类操作。
BatchGetItem
- 原子性：与批量写入类似，批量读取也是原子操作。因此，返回结果中的UnprocessedKeys字段将始终为空。
- 主键重复：原生DynamoDB不允许在请求中包含重复的主键，而PolarDB允许，并将为每个重复的主键返回一条数据。
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

接口名称	参数类型	参数名	是否必选	是否支持	备注
CreateTable	请求参数	AttributeDefinitions	是	是	-
		KeySchema	是	是	-
		TableName	是	是	-
		BillingMode	否	否	计费相关参数，会被忽略。
		GlobalSecondaryIndexes	否	是	-
		LocalSecondaryIndexes	否	是	-
		ProvisionedThroughput	否	是	计费相关参数，会被忽略。
		SSESpecification	否	否	-
		StreamSpecification	否	否	-
		Tags	否	否	-
	返回参数	TableDescription	-	是	-

DescribeTable

接口名称	参数类型	参数名	是否必选	是否支持	备注
DescribeTable	请求参数	TableName	是	是	-
DescribeTable	返回参数	Table	-	是	-

ListTables

接口名称	参数类型	参数名	是否必选	是否支持	备注
ListTables	请求参数	ExclusiveStartTableName	否	是	-
	请求参数	Limit	否	是	-
	返回参数	LastEvaluatedTableName	-	是	-
	返回参数	TableNames	-	是	-

DeleteTable

接口名称	参数类型	参数名	是否必选	是否支持	备注
DeleteTable	请求参数	TableName	是	是	-
DeleteTable	返回参数	TableDescription	-	是	-

PutItem

接口名称	参数类型	参数名	是否必选	是否支持	备注
PutItem	请求参数	Item	是	是	-
		TableName	是	是	-
		ConditionalOperator	否	否	已废弃。请使用`ConditionExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已废弃。请使用`ConditionExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	计费相关参数，会被忽略。
		ReturnItemCollectionMetrics	否	否	统计相关参数，暂不支持。
		ReturnValues	否	是	-
	返回参数	Attributes	-	是	-
		ConsumedCapacity	-	否	计费相关参数，不返回。
		ItemCollectionMetrics	-	否	统计相关参数，不返回。

UpdateItem

接口名称	参数类型	参数名	是否必选	是否支持	备注
UpdateItem	请求参数	Key	是	是	-
		TableName	是	是	-
		AttributeUpdates	否	否	已废弃。请使用`UpdateExpression`。
		ConditionalOperator	否	否	已废弃。请使用`UpdateExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已废弃。请使用`UpdateExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	计费相关参数，会被忽略。
		ReturnItemCollectionMetrics	否	否	统计相关参数，暂不支持。
		ReturnValues	否	是	-
		UpdateExpression	否	是	-
	返回参数	Attributes	-	是	-
		ConsumedCapacity	-	否	计费相关参数，不返回。
		ItemCollectionMetrics	-	否	统计相关参数，不返回。

GetItem

接口名称	参数类型	参数名	是否必选	是否支持	备注
GetItem	请求参数	Key	是	是	-
		TableName	是	是	-
		AttributesToGet	否	否	已废弃。请使用`ProjectionExpression`。
		ConsistentRead	否	否	只能设置为`false`。默认会话一致性，一致性级别在访问地址上配置。
		ExpressionAttributeNames	否	是	-
		ProjectionExpression	否	是	-
		ReturnConsumedCapacity	否	是	计费相关参数，会被忽略。
	返回参数	ConsumedCapacity	-	否	计费相关参数，不返回。
	返回参数	Item	-	是	-

DeleteItem

接口名称	参数类型	参数名	是否必选	是否支持	备注
DeleteItem	请求参数	Key	是	是	-
		TableName	是	是	-
		ConditionalOperator	否	否	已废弃。请使用`ConditionExpression`。
		ConditionExpression	否	是	-
		Expected	否	否	已废弃。请使用`ConditionExpression`。
		ExpressionAttributeNames	否	是	-
		ExpressionAttributeValues	否	是	-
		ReturnConsumedCapacity	否	是	计费相关参数，会被忽略。
		ReturnItemCollectionMetrics	否	否	统计相关参数，暂不支持。
		ReturnValues	否	是	-
	返回参数	Attributes	-	是	-
		ConsumedCapacity	-	否	计费相关参数，不返回。
		ItemCollectionMetrics	-	否	统计相关参数，不返回。

BatchWriteItem

接口名称	参数类型	参数名	是否必选	是否支持	备注
BatchWriteItem	请求参数	RequestItems	是	是	-
		ReturnConsumedCapacity	否	否	计费相关参数，会被忽略。
		ReturnItemCollectionMetrics	否	否	统计相关参数，暂不支持。
	返回参数	ConsumedCapacity	-	否	计费相关参数，不返回。
		ItemCollectionMetrics	-	否	统计相关参数，不返回。
		UnprocessedItems	-	是	行为有差异，恒为空。见上方限制说明。

BatchGetItem

接口名称	参数类型	参数名	是否必选	是否支持	备注
BatchGetItem	请求参数	RequestItems	是	是	-
	请求参数	ReturnConsumedCapacity	否	否	计费相关参数，会被忽略。
	返回参数	ConsumedCapacity	-	否	计费相关参数，不返回。
		Responses	-	是	-
		UnprocessedKeys	-	是	行为有差异，恒为空。见上方限制说明。

Query

接口名称	参数类型	参数名	是否必选	是否支持	备注
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

接口名称	参数类型	参数名	是否必选	是否支持	备注
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

接口名称	参数类型	参数名	是否必选	是否支持	备注
TransactWriteItems	请求参数	TransactItems	是	是	-
		ClientRequestToken	否	是	-
		ReturnConsumedCapacity	否	是	计费相关参数，会被忽略。
		ReturnItemCollectionMetrics	否	否	统计相关参数，暂不支持。
	返回参数	ConsumedCapacity	-	否	计费相关参数，不返回。
	返回参数	ItemCollectionMetrics	-	否	统计相关参数，不返回。

TransactGetItems

接口名称	参数类型	参数名	是否必选	是否支持	备注
TransactGetItems	请求参数	TransactItems	是	是	-
	请求参数	ReturnConsumedCapacity	否	是	计费相关参数，会被忽略。
	返回参数	ConsumedCapacity	-	否	计费相关参数，不返回。
	返回参数	Responses	-	是	-