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 the DynamoDB protocol to create a DynamoDB-compatible ApsaraDB for MongoDB instance. For more information about how to create a DynamoDB-compatible 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 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 Description
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
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.
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
TableNames Yes N/A
DeleteTable Request parameters Required parameter: TableName Yes N/A
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
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 AttributesToGet and ConsistentRead 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 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 parameter is fixed to unknown.
  • The EndingSequenceNumber parameter indicates a timestamp.
  • The value of 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 The value of 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 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

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 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 . such as a query or projection expression cannot be processed in ApsaraDB for MongoDB.
  • Projection expressions: support only one-dimensional arrays. When a projection expression contains only one array element, other fields are returned.
  • Condition expressions:
    • Syntax 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 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 (, ...) )), the 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 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 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 valuemust 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

AWS DynamoDB supports differ 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.