Compatibility details of DynamoDB-compatible instances - ApsaraDB for MongoDB

ApsaraDB for MongoDB supports the DynamoDB protocol. This topic describes the compatibility details of DynamoDB-compatible ApsaraDB for MongoDB instances.

Important

DynamoDB-compatible sharded cluster instances are no longer available for purchase. To use sharded cluster instances, we recommend that you use the MongoDB protocol. For more information, see [Notice] End of sale for DynamoDB-compatible sharded cluster instances.

Background information

Amazon DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance with seamless scalability. ApsaraDB for MongoDB is compatible with the DynamoDB protocol. You can select the DynamoDB protocol to create a DynamoDB-compatible ApsaraDB for MongoDB instance.

Usage notes

The DynamoDB protocol is supported only for ApsaraDB for MongoDB sharded cluster instances that run MongoDB 4.0.
You can modify the protocol type to DynamoDB for existing ApsaraDB for MongoDB sharded cluster instances to make them compatible with the DynamoDB protocol.
The DynamoDB protocol is supported only for ApsaraDB for MongoDB sharded cluster instances that use the VPC network type. No authentication is required.

Compatibility details of DynamoDB operations

Operation	Parameter		Supported	Remarks
CreateTable	Request parameters	Required parameter: AttributeDefinitions	Yes	N/A
		Required parameter: KeySchema	Yes	N/A
		Required parameter: TableName	Yes	It cannot contain the following special characters: dollar sign ($). It cannot start with the `system.` prefix. It must be 1 to 100 characters in length.
		Optional parameter: BillingMode	No	N/A
		Optional parameter: GlobalSecondaryIndexes	Yes	N/A
		Optional parameter: LocalSecondaryIndexes	Yes	N/A
		Optional parameter: ProvisionedThroughput	No	N/A
		Optional parameter: SSESpecification	No	N/A
		Optional parameter: StreamSpecification	Yes	The `StreamViewType` parameter supports only the following values: KEYS_ONLY Note KEYS_ONLY supports only partition keys, but does not support sort keys. NEW_IMAGE
		Optional parameter: Tags	No	N/A
	Response parameters	TableDescription	Yes	N/A
UpdateTable	Request parameters	Optional parameter: AttributeDefinitions	Yes	N/A
		Optional parameter: BillingMode	No	N/A
		Required parameter: GlobalSecondaryIndexesUpdates	Yes	CREATE and DELETE are supported. UPDATE is not supported.
		Optional parameter: ProvisionedThroughput	No	N/A
		Optional parameter: ReplicaUpdates	No	N/A
		Optional parameter: SSESpecification	No	N/A
		Optional parameter: StreamSpecification	Yes	The `StreamViewType` parameter supports only the following values: KEYS_ONLY Note KEYS_ONLY supports only partition keys, but does not support sort keys. NEW_IMAGE
		Required parameter: TableName	Yes	N/A
	Response parameters	TableDescription	Yes	For more information, see TableDescription.
DescribeTable	Request parameters	Required parameter: TableName	Yes	N/A
DescribeTable	Response parameters	Table	Yes	For more information, see TableDescription.
ListTables	Request parameters	Optional parameter: ExclusiveStartTableName	No	Records in different pages are not supported. No limit is imposed on the number of returned records.
	Request parameters	Optional parameter: Limit	No	Records in different pages are not supported. No limit is imposed on the number of returned records.
	Response parameters	LastEvaluatedTableName	No	N/A
	Response parameters	TableNames	Yes	N/A
DeleteTable	Request parameters	Required parameter: TableName	Yes	N/A
DeleteTable	Response parameters	TableDescription	Yes	For more information, see TableDescription.
PutItem	Request parameters	Required parameter: Item	Yes	N/A
		Required parameter: TableName	Yes	N/A
		Optional parameter: ConditionalOperator	No	N/A
		Optional parameter: ConditionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: Expected	No	N/A
		Optional parameter: ExpressionAttributeNames	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ExpressionAttributeValues	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ReturnConsumedCapacity	No	N/A
		Optional parameter: ReturnItemCollectionMetrics	No	N/A
		Optional parameter: ReturnValues	Yes	N/A
	Response parameters	Attributes	Yes	N/A
		ConsumedCapacity	No	N/A
		ItemCollectionMetrics	No	N/A
UpdateItem	Request parameters	Required parameter: Key	Yes	N/A
		Required parameter: TableName	Yes	N/A
		Optional parameter: AttributeUpdates	No	N/A
		Optional parameter: ConditionalOperator	No	N/A
		Optional parameter: ConditionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: Expected	No	N/A
		Optional parameter: ExpressionAttributeNames	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ExpressionAttributeValues	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ReturnConsumedCapacity	No	N/A
		Optional parameter: ReturnItemCollectionMetrics	No	N/A
		Optional parameter: ReturnValues	Yes	N/A
		Optional parameter: UpdateExpression	Yes	For more information, see Compatibility details of expressions.
	Response parameters	Attributes	Yes	N/A
		ConsumedCapacity	No	N/A
		ItemCollectionMetrics	No	N/A
GetItem	Request parameters	Required parameter: Key	Yes	N/A
		Required parameter: TableName	Yes	N/A
		Optional parameter: AttributesToGet	No	N/A
		Optional parameter: ConsistentRead	No	N/A
		Optional parameter: ExpressionAttributeNames	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ProjectionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ReturnConsumedCapacity	No	N/A
	Response parameters	ConsumedCapacity	No	N/A
	Response parameters	Item	Yes	N/A
DeleteItem	Request parameters	Required parameter: Key	Yes	N/A
		Required parameter: TableName	Yes	N/A
		Optional parameter: ConditionalOperator	No	N/A
		Optional parameter: ConditionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: Expected	No	N/A
		Optional parameter: ExpressionAttributeNames	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ExpressionAttributeValues	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ReturnConsumedCapacity	No	N/A
		Optional parameter: ReturnItemCollectionMetrics	No	N/A
		Optional parameter: ReturnValues	Yes	N/A
	Response parameters	Attributes	Yes	N/A
		ConsumedCapacity	No	N/A
		ItemCollectionMetrics	No	N/A
BatchWriteItem	Request parameters	Required parameter: RequestItems	Yes	N/A
		Optional parameter: ReturnConsumedCapacity	No	N/A
		Optional parameter: ReturnItemCollectionMetrics	No	N/A
	Response parameters	ConsumedCapacity	No	N/A
		ItemCollectionMetrics	No	N/A
		UnprocessedItems	Yes	N/A
BatchGetItem	Request parameters	Required parameter: RequestItems	Yes	Item does not support the `AttributesToGet` and `ConsistentRead` parameters.
	Request parameters	Optional parameter: ReturnConsumedCapacity	No	N/A
	Response parameters	ConsumedCapacity	No	N/A
		Responses	Yes	N/A
		UnprocessedKeys	Yes	N/A
Query	Request parameters	Required parameter: TableName	Yes	N/A
		Optional parameter: AttributesToGet	No	N/A
		Optional parameter: ConditionalOperator	No	N/A
		Optional parameter: ConsistentRead	No	N/A
		Optional parameter: ExclusiveStartKey	Yes	N/A
		Optional parameter: ExpressionAttributeNames	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ExpressionAttributeValues	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: FilterExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: IndexName	Yes	N/A
		Optional parameter: KeyConditionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: KeyConditions	No	N/A
		Optional parameter: Limit	Yes	N/A
		Optional parameter: ProjectionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: QueryFilter	No	N/A
		Optional parameter: ReturnConsumedCapacity	No	N/A
		Optional parameter: ScanIndexForward	Yes	N/A
		Optional parameter: Select	No	N/A
	Response parameters	ConsumedCapacity	No	N/A
		Count	Yes	N/A
		Items	Yes	N/A
		LastEvaluatedKey	Yes	N/A
		ScannedCount	Yes	N/A
Scan	Request parameters	Required parameter: TableName	Yes	N/A
		Optional parameter: AttributesToGet	No	N/A
		Optional parameter: ConditionalOperator	No	N/A
		Optional parameter: ConsistentRead	No	N/A
		Optional parameter: ExclusiveStartKey	Yes	N/A
		Optional parameter: ExpressionAttributeNames	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ExpressionAttributeValues	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: FilterExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: IndexName	Yes	N/A
		Optional parameter: Limit	Yes	N/A
		Optional parameter: ProjectionExpression	Yes	For more information, see Compatibility details of expressions.
		Optional parameter: ReturnConsumedCapacity	No	N/A
		Optional parameter: ScanFilter	No	N/A
		Optional parameter: Segment	Yes	N/A
		Optional parameter: Select	No	N/A
		Optional parameter: TotalSegments	Yes	N/A
	Response parameters	ConsumedCapacity	No	N/A
		Count	Yes	N/A
		Items	Yes	N/A
		LastEvaluatedKey	Yes	N/A
		ScannedCount	Yes	N/A

Compatibility details of DynamoDB Streams operations

Operation	Parameter		Supported	Remarks
DescribeStream	Request parameters	Required parameter: StreamArn	Yes	N/A
		Optional parameter: Limit	No	N/A
		Optional parameter: ExclusiveStartShardId	No	N/A
	Response parameters	Required parameter: StreamDescription	Yes	The values of this response parameter of DynamoDB-compatible ApsaraDB for MongoDB instances differ from those of Amazon DynamoDB instances in the following aspects: The value of the `StartingSequenceNumber` parameter is fixed to `unknown`. The `EndingSequenceNumber` parameter indicates a timestamp. The `ShardId` parameter is fixed to `arn:alibaba:mongo-dynamodb@shard-only-1` because a DynamoDB-compatible ApsaraDB for MongoDB sharded cluster instance has only one shard node.
ListStreams	Request parameters	Optional parameter: TableName	Yes	N/A
		Optional parameter: Limit	No	N/A
		Optional parameter: ExclusiveStartStreamArn	No	N/A
	Response parameters	Required parameter: Streams	Yes	For each table, up to one stream can be returned.
GetShardIterator	Request parameters	Required parameter: StreamArn	Yes	N/A
		Required parameter: ShardId	Yes	This parameter is fixed to `arn:alibaba:mongo-dynamodb@shard-only-1` because a DynamoDB-compatible ApsaraDB for MongoDB sharded cluster instance has only one shard node.
		Required parameter: ShardIteratorType	Yes	Only `LATEST` and `AFTER_SEQUENCE_NUMBER` are supported.
		Optional parameter: SequenceNumber	Yes	This parameter is valid only when the `ShardIteratorType` parameter is set to `AFTER_SEQUENCE_NUMBER`. The parameter value can be a 32-bit timestamp in seconds.
	Response parameters	Required parameter: ShardIterator	Yes	N/A
GetRecords	Request parameters	Required parameter: ShardIterator	Yes	N/A
	Request parameters	Optional parameter: Limit	Yes	When this parameter is not specified, each page contains 101 data entries, instead of 1 MB of data.
	Response parameters	Required parameter: Records	Yes	N/A

Data structures of DynamoDB operations

Data type	Field	Supported
TableDescription	ArchivalSummary	No
	AttributeDefinitions	No
	BillingModeSummary	No
	CreationDateTime	No
	GlobalSecondaryIndexes	Yes
	GlobalTableVersion	No
	ItemCount	Yes
	KeySchema	Yes
	LatestStreamArn	Yes
	LatestStreamLabel	Yes
	LocalSecondaryIndexes	Yes
	ProvisionedThroughput	No
	Replicas	No
	RestoreSummary	No
	SSEDescription	No
	StreamSpecification	Yes
	TableArn	No
	TableId	No
	TableName	Yes
	TableSizeBytes	Yes
	TableStatus	Yes

Compatibility details of expressions

An attribute name that contains .: An attribute name that contains . indicates a scalar attribute or a nested document. In Amazon DynamoDB, if an expression attribute name maps to all elements in a document path, the attribute is processed as a scalar attribute. Otherwise, the attribute is processed as a nested attribute.
Note
Scalar attributes that contain ., such as a query or projection expression, cannot be processed in ApsaraDB for MongoDB.
Projection expressions: Only one-dimensional arrays are supported. When a projection expression contains only one array element, other fields are returned.
Condition expressions:
- Syntax for condition expressions in Amazon DynamoDB:
```
condition-expression ::=
      operand comparator operand
    | operand BETWEEN operand AND operand
    | operand IN ( operand (',' operand (, ...) ))
    | function
    | condition AND condition
    | condition OR condition
    | NOT condition
    | ( condition )

comparator ::=
    =
    | <>
    | <
    | <=
    | >
    | >=

function ::=
    attribute_exists (path)
    | attribute_not_exists (path)
    | attribute_type (path, type)
    | begins_with (path, substr)
    | contains (path, operand)
    | size (path)
```
- In operand1 comparator operand2, operand1 must be a path, and operand2 must be an expression attribute value.
- In operand1 BETWEEN operand2 AND operand3, operand1 must be a path, and other operand must be expression attribute values.
- In operand1 IN ( operand2 (',' operand3 (, ...) )), operand1 must be a path, and other operand must be expression attribute values.
- For the size(path) function in function, the path field must be of the STRING type (used to determine the length) or of the SET or LIST type (used to determine the size). It cannot be of the BINARY or MAP type.
Update expressions:
- Syntax for update expressions in Amazon DynamoDB:
```
update-expression ::=
    [ SET action [, action] ... ]
    [ REMOVE action [, action] ...]
    [ ADD action [, action] ... ]
    [ DELETE action [, action] ...]

set-action ::=
    path = value

value ::=
    operand
    | operand '+' operand
    | operand '-' operand

operand ::=
    path | function

function ::=
    if_not_exists (path, value)
    | list_append (list1, list2)

remove-action ::=
    path

add-action ::=
    path value

delete-action ::=
    path value
```
- set-action:
  - In SET path = operand, operand cannot be a path.
  - In SET path = operand1 '+'|'-' operand2, operand1 must be a path. This indicates that only field increment or decrement is supported in this expression.
  - In SET path = if_not_exists (path, value), two paths must be equal, and value must be an expression attribute value.
  - In SET path = if_not_exists (path, value), partial updates are not supported when multiple conditions are concurrently specified. This indicates that all conditions must be met for this expression to be executed.
  - In SET path = list_append(list1, list2), one of the list1 and list2 values must be equal to path, and the other one must be an expression attribute value.
- remove-action: When an element in a list is removed, null is used to replace the removed element. The list size remains unchanged and the remaining elements are not shifted.

Data type mappings

Amazon DynamoDB supports different data types from ApsarsDB for MongoDB. Data type mappings are provided between DynamoDB-compatible ApsaraDB for MongoDB instances and ApsaraDB for MongoDB instances for compatibility between the two sets of data types.

The following table lists the data type mappings.

DynamoDB data type	MongoDB data type
B	Binary data
BOOL	Boolean
BS	*
L	Array
M	Object
N	Double
NS	*
NULL	Null
S	String
SS	*

Note

In Amazon DynamoDB, each value must be unique within a binary set (BS), a number set (NS), or a string set (SS). For example, when you insert 1,2,2,3 in an NS, Amazon DynamoDB removes duplicates and then the inserted data becomes 1,2,3. DynamoDB-compatible ApsaraDB for MongoDB instances do not support data deduplication for BSs, NSs, and SSs. In this case, the * data types in the preceding table are processed as arrays. In later release of ApsaraDB for MongoDB, these data types will be optimized for data deduplication.