DynamoDB Local は DynamoDB とどれくらい違う？

DynamoDB Local 3.3.2 は、プローブした 8 つの制限を DynamoDB と同じ値で適用し、エラー名もおおむね同じでした。ただし、エラーメッセージの半分以上は異なり、誤ったシークレットで署名したリクエストも受け付けました。

同じリクエストを DynamoDB Local と us-east-1 の Amazon DynamoDB に送り、応答を比較しました。その結果、AWS の使用上の注意のうち 3 行は 3.3.2 では誤りだとわかりました。

両方のエンジンで 76 件のチェックを実行しました。28 件は同じ結果、43 件は異なる結果で、5 件は DynamoDB Local が実装していない API に当たりました。

AWS の使用上の注意のうち 3 行は 3.3.2 では誤り

AWS の DynamoDB Local の使用上の注意には、サービスとの相違点が載っています。2026 年 10 月 27 日にこれを読み、安くテストできる行をテストしました。

• PartiQL の Limit は機能します。 注意では、Local は ExecuteStatement の Limit を無視するとしています。1 つのキーの下に 20 件のアイテムを置き、Limit: 5 を付けると、両方のエンジンが 5 件のアイテムと NextToken を返しました。AWS のリリース履歴もこれと一致します。2023 年 6 月のバージョン 1.22.0 で "Support for Limit Operation" が追加されています。
• 並列スキャンのセグメントは機能します。 注意では、Local は Segment と TotalSegments を無視するとしています。4 つのセグメントを合わせて、両方のエンジンが 100 件、異なるキー 100 個を返しました。Local がセグメントを無視するなら、各セグメントが 100 件すべてを返すはずです。セグメントは 1 つずつ順に読んだため、Local が並列にスキャンするかどうかはわかりません。
• BillingModeSummary は返ります。 注意では、Local は常に null を返すとしています。オンデマンドテーブルでは、Local はサービスと同じく PAY_PER_REQUEST を返しました。プロビジョンドテーブルはテストしていません。

何が違い、テストで何を変えるか

• エラーメッセージ。 半分以上が異なります。サービスは多くの検証メッセージを 1 validation error detected: で始め、Local は同じルールを独自の言葉で述べることがよくあります。メッセージではなくエラー名でアサートしてください。たとえば expect(err.name).toBe('ConditionalCheckFailedException') です。
• 2 つのエラー名。 重複する PartiQL の INSERT は、Local では DuplicateItem、サービスでは DuplicateItemException になりました。未知のアクセスキー ID は、Local では ResourceNotFoundException、サービスでは UnrecognizedClientException になりました。コードがどちらかの名前で分岐するなら、その分岐は DynamoDB に対してテストしてください。
• 認証情報。 Local は誤ったシークレットで署名したリクエストを受け付けました。未知のアクセスキー ID は、テーブルが存在しないエラーになりました: Cannot do operations on a non-existent table。認証情報の処理を Local でテストしないでください。
• アクセスキー ID ごとのデータベース。 Local は -inMemory でも、アクセスキー ID ごとに別のテーブルを持ちました。テストでは固定のアクセスキー ID とリージョンを 1 つずつ使うか、AWS がドキュメント化しているとおり -sharedDb で Local を起動してください。
• インデックスのページが早く埋まる。 約 1 KB のアイテム 1,200 件に対する KEYS_ONLY のグローバルセカンダリインデックスのクエリで、Local は 1,014 件と LastEvaluatedKey を返しました。サービスは 1 ページで 1,200 件すべてを返しました。1 ページの件数を数えずに、LastEvaluatedKey をたどってください。
• 大文字小文字だけが異なるテーブル名。 Local で Authors の次に authors を作成すると、HTTP ステータス 500 の InternalFailure で失敗しました。リトライするクライアントはこれをサービス障害として扱います。サービスは両方のテーブルを作成しました。
• テーブル ARN。 Local の ARN は arn:aws:dynamodb:ddblocal:000000000000:table/… となります。Local でテストするコードでは、ARN からリージョンやアカウントを読まないでください。
• 冪等性トークン。 Local は、異なるペイロードで再利用した ClientRequestToken を受け付けました。サービスは IdempotentParameterMismatchException を返しました。
• Local にない機能。 Local は CreateTable のベクトルインデックスを受け付けたうえで、捨てました。LSI を持つテーブルで項目コレクションメトリクスを返しませんでした。タグ付け、エクスポート、2017 年版のグローバルテーブル API には UnknownOperationException で応答しました。これらは DynamoDB に対してテストしてください。
• イメージのバージョン。 私たちのマシンの 1 台では、キャッシュされた latest イメージがまだ 3.3.0 でした。バージョンを固定してください。

すべてのアクセスキー ID とリージョンで 1 つのデータベースを使うには:

docker run -p 8000:8000 amazon/dynamodb-local:3.3.2 -jar DynamoDBLocal.jar -sharedDb -inMemory

測定した読み込みでは、消費キャパシティは一致しました: 2 回の GetItem と 8 件の Query 1 回です。書き込みは確認していません。

DynamoDB Local のガイドでは実行方法を、DynamoDB Local と LocalStack への接続ではツールの向け方を説明しています。DynoTable はローカルプロファイルを通じて DynamoDB Local に接続します。DynoTable をダウンロードして、ローカルのテーブルを開いてください。

測定方法

1 つの Node プロセスが、同じ AWS SDK for JavaScript のコードと SDK のデフォルトのリトライで、まず Local で全チェックを、次にサービスで全チェックを実行しました。各チェックは 1 回だけ実行したため、1,014 のような件数は 1 回の観測として扱ってください。チェックはフィクスチャテーブルを共有するため、状態が次のチェックに持ち越されることがあります。

Local は公式イメージをダイジェストで固定して実行しました。サービス側では、実行中に作成して削除する us-east-1 のオンデマンドのスクラッチテーブルを使いました。

エラー名、メッセージ、HTTP ステータスが一致するか、プローブの測定値が一致する場合に、2 つの応答を同じとみなします。テーブル名、アカウント ID、アクセスキー ID、エコーされたリクエスト値は、両側でプレースホルダーに置き換えます。ARN と、スキャンセグメントへのキーの分かれ方は比較していません。

エラーチェックは、よくある DynamoDB エラーのカタログから取りました。API からのランダムなサンプルではありません。

エンジン: DynamoDB Local 3.3.2 と Amazon DynamoDB（us-east-1）、2026 年 10 月 27 日に取得。クライアント: Node v24.22.1 上の @aws-sdk/client-dynamodb 3.1126.0。

Local イメージ: amazon/dynamodb-local:3.3.2@sha256:6ada631ec7aa5fc83446855eb17233e3dad184fec47477e8140c6c569cfe0c86。デフォルトの java -jar DynamoDBLocal.jar -inMemory で起動。

8 件のエラーチェックは制限プローブと同じ制限を超え、サービスから同じメッセージを受け取るため、両方のグループに数えられています。

今回の取得は、時間や費用のかかるものを含みません: スロットリング、TTL による削除、トランザクションの競合、インデックスのバックフィル、プロビジョンドテーブル、他の SDK、Local の他のモード、他のリージョンです。

挙動プローブ

• Limit 付きの PartiQL ExecuteStatement: 同じ
  • Local: 返されたアイテム数: 5、NextToken あり: true
  • DynamoDB: 返されたアイテム数: 5、NextToken あり: true
• 4 セグメントでの並列 Scan: 同じ
  • Local: 書き込んだアイテム数: 100、返されたアイテム数: 100、異なるキーの数: 100
  • DynamoDB: 書き込んだアイテム数: 100、返されたアイテム数: 100、異なるキーの数: 100
• 大文字小文字だけが異なる名前の 2 つのテーブル: 異なる
  • Local: 最初の CreateTable が成功: true、InternalFailure: The request processing has failed because of an unknown error, exception or failure.
  • DynamoDB: 最初の CreateTable が成功: true
• 約 1 KB のアイテム 1,200 件に対する KEYS_ONLY インデックスのクエリ: 異なる
  • Local: 書き込んだアイテム数: 1,200、最初のページのアイテム数: 1,014、LastEvaluatedKey あり: true
  • DynamoDB: 書き込んだアイテム数: 1,200、最初のページのアイテム数: 1,200、LastEvaluatedKey あり: false
• オンデマンドテーブルでの DescribeTable の BillingModeSummary と TableArn: 同じ
  • Local: BillingModeSummary: PAY_PER_REQUEST
  • DynamoDB: BillingModeSummary: PAY_PER_REQUEST
• テーブルにタグを付けて読み戻す: Local に未実装
  • Local: TagResource: UnknownOperationException: Tagging is not currently supported in DynamoDB Local.、ListTagsOfResource: UnknownOperationException: Tagging is not currently supported in DynamoDB Local.
  • DynamoDB: TagResource: 成功、ListTagsOfResource: 成功、タグ team=parity
• ベクトルインデックス付きの CreateTable: 異なる
  • Local: DescribeTable のベクトルインデックス: null
  • DynamoDB: DescribeTable のベクトルインデックス: Embeddings
• アンダースコアを含むアクセスキー ID: 異なる
  • Local: UnrecognizedClientException: The Access Key ID or security token is invalid.
  • DynamoDB: UnrecognizedClientException: The security token included in the request is invalid.
• LSI を持つテーブルでの ReturnItemCollectionMetrics: 異なる
  • Local: ItemCollectionMetrics: null
  • DynamoDB: ItemCollectionMetrics: {"ItemCollectionKey":{"pk":{"S":"parity-icm"}},"SizeEstimateRangeGB":[0,1]}
• 読み込みで報告される ConsumedCapacity: 同じ
  • Local: GetItem（結果整合性）: 0.5、GetItem（強い整合性）: 1、約 1 KB のアイテム 8 件の Query（強い整合性）: 2
  • DynamoDB: GetItem（結果整合性）: 0.5、GetItem（強い整合性）: 1、約 1 KB のアイテム 8 件の Query（強い整合性）: 2

8 つの制限を両側からプローブ

両方のエンジンが、ドキュメントに記載された 8 つの制限のそれぞれで制限値ちょうどのリクエストを受け付け、1 単位超えたリクエストを拒否しました。

すべてのエラーチェック

エラー名が異なる、または一方のエンジンだけでエラーになった 5 件

• duplicateitemexception
  • Local: DuplicateItem: Duplicate primary key exists in table
  • DynamoDB: DuplicateItemException: Duplicate primary key exists in table
• idempotentparametermismatchexception
  • Local: 成功
  • DynamoDB: IdempotentParameterMismatchException: Specified idempotent token was used with different request parameters within the idempotency window
• security-token-invalid
  • Local: ResourceNotFoundException: Cannot do operations on a non-existent table
  • DynamoDB: UnrecognizedClientException: The security token included in the request is invalid.
• signature-does-not-match
  • Local: 成功
  • DynamoDB: InvalidSignatureException: The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method. Consult the service documentation for details.
• vector-index-update-on-local
  • Local: ValidationException: Nothing to update
  • DynamoDB: 成功

エラー名は同じで文言が異なる 18 件

• batchgetitem-too-many-items, ValidationException
  • Local: Too many items requested for the BatchGetItem call
  • DynamoDB: 1 validation error detected: Value at 'RequestItems.<table-name>.member.Keys' failed to satisfy constraint: Member must have length less than or equal to 100
• batchwriteitem-too-many-items, ValidationException
  • Local: Too many items requested for the BatchWriteItem call
  • DynamoDB: 1 validation error detected: Value '<your request>' at 'requestItems' failed to satisfy constraint: Map value must satisfy constraint: [Member must have length less than or equal to 25, Member must have length greater than or equal to 1]
• cannot-do-operations-on-a-non-existent-table, ResourceNotFoundException
  • Local: Cannot do operations on a non-existent table
  • DynamoDB: Requested resource not found
• dynamodb-query-condition-missed-key-schema-element, ValidationException
  • Local: Query condition missed key schema element
  • DynamoDB: Query condition missed key schema element: pk
• expression-size-exceeded, ValidationException
  • Local: Invalid ConditionExpression: Expression size has exceeded the maximum allowed size; expression size: 27785
  • DynamoDB: 1 validation error detected: Invalid ConditionExpression: Expression size has exceeded the maximum allowed size;
• gsi-count-exceeded, ValidationException
  • Local: GlobalSecondaryIndex count exceeds the per-table limit
  • DynamoDB: One or more parameter values were invalid: GlobalSecondaryIndex count exceeds the per-table limit of 20
• item-size-greater-than-key-limit, ValidationException
  • Local: Hash primary key values must be under 2048 bytes, and range primary key values must be under 1024 bytes
  • DynamoDB: One or more parameter values were invalid: Aggregated size of all range keys has exceeded the size limit of 1024 bytes
• key-attribute-size-exceeded, ValidationException
  • Local: Hash primary key values must be under 2048 bytes, and range primary key values must be under 1024 bytes
  • DynamoDB: One or more parameter values were invalid: Size of hashkey has exceeded the maximum size limit of2048 bytes
• key-element-does-not-match-schema, ValidationException
  • Local: One or more parameter values were invalid: Type mismatch for key
  • DynamoDB: The provided key element does not match the schema
• lsi-count-exceeded, ValidationException
  • Local: Cannot have more than 5 local secondary indexes per table
  • DynamoDB: One or more parameter values were invalid: Number of LocalSecondaryIndexes exceeds per-table limit of 5
• projected-attributes-per-index-exceeded, ValidationException
  • Local: No more than 20 attributes per table can be projected into Local Secondary Indices
  • DynamoDB: 1 validation error detected: Value '<your request>' at 'globalSecondaryIndexes.1.member.projection.nonKeyAttributes' failed to satisfy constraint: Member must have length less than or equal to 20
• projected-attributes-per-table-exceeded, ValidationException
  • Local: No more than 20 attributes per table can be projected into Local Secondary Indices
  • DynamoDB: One or more parameter values were invalid: Number of projected attributes in all indexes exceeds limit of 100, number of projected attributes:120
• provided-starting-key-invalid, ValidationException
  • Local: Exclusive Start Key must have same size as table's key schema
  • DynamoDB: The provided starting key is invalid
• resourceinuseexception, ResourceInUseException
  • Local: Cannot create preexisting table
  • DynamoDB: Table already exists: <table-name>
• resourcenotfoundexception, ResourceNotFoundException
  • Local: Cannot do operations on a non-existent table
  • DynamoDB: Requested resource not found: Table: <table-name> not found
• scan-segment-out-of-range, ValidationException
  • Local: 1 validation error detected: Value '<your request>' at 'segment' failed to satisfy constraint: Member must have value less than or equal to 1
  • DynamoDB: The Segment parameter is zero-based and must be less than parameter TotalSegments
• table-already-exists, ResourceInUseException
  • Local: Cannot create preexisting table
  • DynamoDB: Table already exists: <table-name>
• transactwriteitems-too-many, ValidationException
  • Local: Member must have length less than or equal to 100
  • DynamoDB: 1 validation error detected: Value '<your request>' at 'transactItems' failed to satisfy constraint: Member must have length less than or equal to 100

サービスが 1 validation error detected: を付け加えるだけの 8 件

それ以外のメッセージは同じです。以下は DynamoDB Local のメッセージです:

• expressionattributenames-contains-invalid-key: ValidationException: ExpressionAttributeNames contains invalid key: Syntax error; key: "#my.attribute"
• expressionattributenames-not-used: ValidationException: Value provided in ExpressionAttributeNames unused in expressions: keys: {#status}
• expressionattributevalues-not-used: ValidationException: Value provided in ExpressionAttributeValues unused in expressions: keys: {:status}
• nesting-depth-exceeded: ValidationException: Nesting Levels have exceeded supported limits: Attributes in the item have nested levels beyond supported limit
• number-overflow: ValidationException: Number overflow. Attempting to store a number with magnitude larger than supported range
• reserved-keyword-attribute-name: ValidationException: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status
• select-count-with-projection: ValidationException: Cannot specify the ProjectionExpression when choosing to get only the Count
• two-document-paths-overlap: ValidationException: Invalid UpdateExpression: Two document paths overlap with each other; must remove or rewrite one of these paths; path one: [profile], path two: [profile, city]

Local が実装していない API に当たった 4 件

Local は 4 件すべてに UnknownOperationException: An unknown operation was requested. で応答しました。サービスの応答は次のとおりです:

• export-no-pitr: PointInTimeRecoveryUnavailableException: Point in time recovery is not enabled for table '<table-name>'
• globaltablenotfoundexception: GlobalTableNotFoundException: Global table not found: Global table with name: 'no-such-global-table' does not exist.
• globaltablenotfoundexception-replica: GlobalTableNotFoundException: Global table not found: Global table with name: 'no-such-global-table' does not exist.
• pointintimerecoveryunavailableexception: PointInTimeRecoveryUnavailableException: Point in time recovery is not enabled for table '<table-name>'

同じ結果になった 23 件

• both-keyconditions-and-keyconditionexpression: ValidationException: Can not use both expression and non-expression parameters in the same request: Non-expression parameters: {KeyConditions} Expression parameters: {KeyConditionExpression}
• conditional-request-failed-transact: TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed]、理由 ConditionalCheckFailed
• conditionalcheckfailedexception: ConditionalCheckFailedException: The conditional request failed
• consistent-reads-not-supported-on-gsi: ValidationException: Consistent reads are not supported on global secondary indexes
• document-path-invalid-for-update: ValidationException: The document path provided in the update expression is invalid for update
• duplicate-item-in-batchwrite: ValidationException: Provided list of item keys contains duplicates
• duplicate-keys-in-batchget: ValidationException: Provided list of item keys contains duplicates
• filter-expression-with-key-attribute: ValidationException: Filter Expression can only contain non-primary key attributes: Primary key attribute: pk
• index-not-found: ValidationException: The table does not have the specified index: no-such-index
• item-size-exceeded-maximum: ValidationException: Item size has exceeded the maximum allowed size
• item-size-exceeded-maximum-update: ValidationException: Item size to update has exceeded the maximum allowed size
• key-schema-not-projected: ValidationException: One or more parameter values were invalid: Global secondary index gsi1 does not project [unprojected]
• partiql-aggregate-function: ValidationException: Unexpected path component at 1:8:3
• partiql-group-by: ValidationException: Unsupported clause: GROUP BY
• partiql-multi-table-join: ValidationException: Only select from a single table or index is supported.
• partiql-subquery-in: ValidationException: IN operator must have a left hand argument of type Variable Reference and right hand argument of type Seq with at least one member
• partiql-unexpected-from-source: ValidationException: Unexpected from source
• query-key-condition-not-supported: ValidationException: Query key condition not supported
• supplied-attributevalue-empty: ValidationException: Supplied AttributeValue is empty, must contain exactly one of the supported datatypes
• transaction-multiple-operations-one-item: ValidationException: Transaction request cannot include multiple operations on one item
• transactioncanceledexception: TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed]、理由 ConditionalCheckFailed
• update-expression-operand-incorrect-datatype: ValidationException: An operand in the update expression has an incorrect data type
• validation-empty-expression: ValidationException: Invalid FilterExpression: The expression can not be empty;

変更履歴

• 2026-10-27: 初回の取得、DynamoDB Local 3.3.2。

DynamoDB Local の新しいリリースごとに取得をやり直し、変わった点をここに記載します。