ApsaraDB for MongoDB supports the DynamoDB protocol. This topic describes the compatibility details of DynamoDB-compatible ApsaraDB for MongoDB 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 DynamoDB as the protocol type during instance creation to create a DynamoDB-compatible ApsaraDB for MongoDB instance. For more information about how to create a DynamoDB-compatible ApsaraDB for MongoDB instance, see Create a DynamoDB-compatible ApsaraDB for MongoDB instance.

Precautions

  • The DynamoDB protocol is supported only for ApsaraDB for MongoDB sharded cluster instances that run MongoDB 4.0.
  • You can change 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 reside within VPCs. No authentication is required.

Compatibility details of the DynamoDB protocol

Table 1. Compatibility details of DynamoDB API operations
Operation Parameter Supported Description
CreateTable Request parameters Required parameter: AttributeDefinitions Yes N/A
Required parameter: KeySchema Yes N/A
Required parameter: TableName Yes
  • The following special characters cannot be included: dollar signs ($).
  • The value cannot start with system..
  • The value 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 Valid values for the StreamViewType parameter:
  • KEYS_ONLY
    Note KEYS_ONLY supports only partition keys and does not support sort keys in tables.
  • 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 operations are supported, and update operations are not supported.
Optional parameter: ProvisionedThroughput No N/A
Optional parameter: ReplicaUpdates No N/A
Optional parameter: SSESpecification No N/A
Optional parameter: StreamSpecification Yes Valid values for the StreamViewType parameter:
  • KEYS_ONLY
    Note KEYS_ONLY supports only partition keys and does not support sort keys in tables.
  • NEW_IMAGE
Required parameter: TableName Yes N/A
Response parameters TableDescription Yes For more information, see the "Data structure of DynamoDB API operations" section of this topic.
DescribeTable Request parameters Required parameter: TableName Yes N/A
Response parameters Table Yes For more information, see the "Data structure of DynamoDB API operations" section of this topic.
ListTables Request parameters Optional parameter: ExclusiveStartTableName No Paged queries are not supported, and no limits are imposed on the number of returned entries.
Optional parameter: Limit No Paged queries are not supported, and no limits are imposed on the number of returned entries.
Response parameters LastEvaluatedTableName No N/A
TableNames Yes N/A
DeleteTable Request parameters Required parameter: TableName Yes N/A
Response parameters TableDescription Yes For more information, see the "Data structure of DynamoDB API operations" section of this topic.
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
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 elements do not support the AttributesToGet or ConsistentRead parameter.
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
Table 2. Compatibility details of DynamoDB Streams operations
Operation Parameter Supported Description
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 AWS DynamoDB instances in the following aspects:
  • The value of the StartingSequenceNumber field is fixed to unknown.
  • The EndingSequenceNumber field indicates a timestamp.
  • The value of the ShardId field 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 The value of this field 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 Valid values: LATEST and AFTER_SEQUENCE_NUMBER.
Optional parameter: SequenceNumber Yes This parameter takes effect when the ShardIteratorType parameter is set to AFTER_SEQUENCE_NUMBER. The 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
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
Table 3. Data structure of DynamoDB API 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 an embedded document. In AWS DynamoDB, if an expression attribute name maps to all elements in a document path, the attribute is handled as a scalar attribute. Otherwise, the attribute is handled as a nested attribute.
    Note Scalar attributes that contain . cannot be processed, such as a query or projection in ApsaraDB for MongoDB.
  • ProjectionExpression: Projection expressions support only one-dimensional arrays. When a projection expression contains only one array element, other fields are returned.
  • ConditionExpression:
    • The following syntax is available for condition expressions in AWS 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 the operand1 comparator operand2 syntax, operand1 must be a path, and operand2 must be an expression attribute value.
    • In the operand1 BETWEEN operand2 AND operand3 syntax, operand1 must be a path, and other operands must be expression attribute values.
    • operand1 IN ( operand2 (',' operand3 (, ...) In )) syntax, operand1 must be a path, and other operands must be expression attribute values.
    • The size(path) function in the function section has the following limits: The attribute specified by path must be of the STRING, Set, or List type. The BINARY or MAP data type is not supported. If the attribute is of the String type, size returns the length of the string. If the attribute is of the Set or List type, size returns the number of elements in the set or list.
  • UpdateExpression:
    • The following syntax is available for update expressions in AWS 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 the SET path = operand syntax, operand cannot be a path.
      • In the SET path = operand1 '+'|'-' operand2 syntax, operand1 must be a path. This indicates that only field increment or decrement is supported in this expression.
      • In the SET path = if_not_exists (path, value) syntax, the two paths must be equal and value must be set to an expression attribute value.
      • In the SET path = if_not_exists (path, value) syntax, 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 the SET path = list_append(list1, list2) syntax, one of the list1 and list2 values must be equal to the path value, 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

The supported data types of AWS DynamoDB differ from those of ApsarsDB for MongoDB. For this reason, Alibaba Cloud provides data type mappings between DynamoDB-compatible ApsaraDB for MongoDB instances and ApsaraDB for MongoDB instances. This way, compatibility is maintained for 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 Duplicates are not allowed in the binary set (BS), number set (NS), and string set (SS) data types of AWS DynamoDB. For example, when you insert 1,2,2,3 in NS, NS removes duplicates and then the inserted data becomes 1,2,3. DynamoDB-compatible ApsaraDB for MongoDB instances do not allow duplicates to be removed from data of these types. In this case, the * parts in the preceding table are processed as arrays. ApsaraDB for MongoDB plans to optimize these data types and allow duplicates to be removed from data of these data types in future releases.

Best practices

You can migrate data from AWS DynamoDB to ApsaraDB for MongoDB. For more information, see Migrate an Amazon DynamoDB database to ApsaraDB for MongoDB by using NimoShake.