DynamoDB テーブルのエクスポート出力形式

DynamoDB テーブルのエクスポートには、テーブルデータを含むファイルに加えて、マニフェストファイルが含まれます。これらのファイルはすべて、エクスポート要求で指定した Amazon S3 バケットに保存されます。以下のセクションでは、各出力オブジェクトの形式と内容について説明します。

トピック

マニフェストファイル

DynamoDB では、エクスポートリクエストごとにマニフェストファイルがチェックサムファイルとともに指定した S3 バケットに作成されます。


export-prefix/AWSDynamoDB/ExportId/manifest-summary.json
export-prefix/AWSDynamoDB/ExportId/manifest-summary.checksum
export-prefix/AWSDynamoDB/ExportId/manifest-files.json
export-prefix/AWSDynamoDB/ExportId/manifest-files.checksum

テーブルのエクスポートをリクエストする際は、export-prefix を選択します。これにより、エクスポート先 S3 バケットのファイルを整理できます。ExportId は、同じ S3 バケットへの複数のエクスポートを保証する、サービスによって生成される一意のトークンです。export-prefix は相互に上書きしません。

エクスポートでは、パーティションごとに少なくとも 1 つのファイルが作成されます。空のパーティションの場合、エクスポートリクエストにより空のファイルが作成されます。各ファイル内のすべての項目は、その特定のパーティションのハッシュされたキースペースからのものです。

注記

また、DynamoDB では、マニフェストファイルと同じディレクトリに _started という名前の空のファイルが作成されます。このファイルは、エクスポート先のバケットが書き込み可能であること、およびエクスポートが開始されたことを検証します。これは安全に削除できます。

要約マニフェスト

manifest-summary.json ファイルには、エクスポートジョブに関する概要情報が含まれています。これにより、共有データフォルダー内のどのデータファイルがこのエクスポートに関連付けられているかがわかります。この形式は次のとおりです。


{
   "version": "2020-06-30",
   "exportArn": "arn:aws:dynamodb:us-east-1:123456789012:table/ProductCatalog/export/01234567890123-a1b2c3d4",
   "startTime": "2020-11-04T07:28:34.028Z",
   "endTime": "2020-11-04T07:33:43.897Z",
   "tableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/ProductCatalog",
   "tableId": "12345a12-abcd-123a-ab12-1234abc12345",
   "exportTime": "2020-11-04T07:28:34.028Z",
   "s3Bucket": "ddb-productcatalog-export",
   "s3Prefix": "2020-Nov",
   "s3SseAlgorithm": "AES256",
   "s3SseKmsKeyId": null,
   "manifestFilesS3Key": "AWSDynamoDB/01693685827463-2d8752fd/manifest-files.json",
   "billedSizeBytes": 0,
   "itemCount": 8,
   "outputFormat": "DYNAMODB_JSON",
   "exportType": "FULL_EXPORT"
}

ファイルマニフェスト

manifest-files.json ファイルには、エクスポートされたテーブルデータを含むファイルに関する情報が含まれています。ファイルは JSON Lines 形式であるため、改行が項目区切り文字として使用されます。次の例では、読みやすくするためにファイルマニフェストの 1 つのデータファイルの詳細が複数行にフォーマットされています。


{
"itemCount": 8,
   "md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
   "etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
   "dataFileS3Key": "AWSDynamoDB/01693685827463-2d8752fd/data/asdl123dasas.json.gz"
}

データファイル

DynamoDB では、DynamoDB JSON と Amazon Ion の 2 つの形式でテーブルデータをエクスポートできます。選択した形式にかかわらず、データは、キーによって名前が付けられた複数の圧縮ファイルに書き込まれます。これらのファイルも manifest-files.json ファイル内に一覧表示されます。

フルエクスポート後の S3 バケットのディレクトリ構造では、export Id フォルダーにマニフェストファイルとデータファイルがすべて含まれます。


DestinationBucket/DestinationPrefix
.
└── AWSDynamoDB
    ├── 01693685827463-2d8752fd     // the single full export
    │   ├── manifest-files.json     // manifest points to files under 'data' subfolder
    │   ├── manifest-files.checksum
    │   ├── manifest-summary.json   // stores metadata about request
    │   ├── manifest-summary.md5  
    │   ├── data                    // The data exported by full export
    │   │   ├── asdl123dasas.json.gz
    │   │   ...
    │   └── _started                // empty file for permission check

DynamoDB JSON

DynamoDB JSON 形式のテーブルエクスポートは、複数の Item オブジェクトで構成されます。個々のオブジェクトは DynamoDB のスタンダードマーシャリングされた JSON 形式です。

DynamoDB JSON エクスポートデータ用のカスタムパーサーを作成する場合、形式は JSON Lines です。これは、改行が項目の区切り文字として使用されていることを意味します。Athena や AWS Glue など、多くの AWS サービスで、この形式は自動的に解析されます。

次の例では、読みやすくするために DynamoDB JSON エクスポートの 1 つの項目が複数行にフォーマットされています。


{
    "Item":{
        "Authors":{
            "SS":[
                "Author1",
                "Author2"
            ]
        },
        "Dimensions":{
            "S":"8.5 x 11.0 x 1.5"
        },
        "ISBN":{
            "S":"333-3333333333"
        },
        "Id":{
            "N":"103"
        },
        "InPublication":{
            "BOOL":false
        },
        "PageCount":{
            "N":"600"
        },
        "Price":{
            "N":"2000"
        },
        "ProductCategory":{
            "S":"Book"
        },
        "Title":{
            "S":"Book 103 Title"
        }
    }
}

Amazon Ion

Amazon Ion は、大規模なサービス指向アーキテクチャをエンジニアリングしながら、急速な開発、デカップリング、効率性といった日々の課題に対処するために構築されたリッチタイプの自己記述型階層型データシリアル化フォーマットです。DynamoDB は、Ion のテキストのフォーマットでのテーブルのエクスポートをサポートします。これは JSON のスーパーセットです。

テーブルを Ion 形式にエクスポートすると、テーブルで使用されている DynamoDB データ型が Ion データ型にマップされます。DynamoDB セットは、Ion 型注釈を使用して、ソーステーブルで使用されるデータ型を明確にします。

次の表に、DynamoDB データ型と ion データ型のマッピングを示します。

DynamoDB データ型	Ion 表現
文字列 (S)	文字列
ブール型 (BOOL)	ブール
数値 (N)	小数点
バイナリ (B)	blob
セット (SS、NS、BS)	リスト (型注釈 $DynamoDB_SS、$DynamoDB_NS、または $DynamoDB_BS)
リスト	リスト
マップ	構造体

Ion エクスポート内の項目は、改行で区切られます。各行は Ion バージョンマーカーで始まり、Ion 形式の項目が続きます。次の例では、読みやすくするために 1 つの Ion エクスポートの項目が複数の行にフォーマットされています。


$ion_1_0 {
    Item:{
        Authors:$dynamodb_SS::["Author1","Author2"],
        Dimensions:"8.5 x 11.0 x 1.5",
        ISBN:"333-3333333333",
        Id:103.,
        InPublication:false,
        PageCount:6d2,
        Price:2d3,
        ProductCategory:"Book",
        Title:"Book 103 Title"
    }
}

マニフェストファイル

DynamoDB では、エクスポートリクエストごとにマニフェストファイルがチェックサムファイルとともに指定した S3 バケットに作成されます。


export-prefix/AWSDynamoDB/ExportId/manifest-summary.json
export-prefix/AWSDynamoDB/ExportId/manifest-summary.checksum
export-prefix/AWSDynamoDB/ExportId/manifest-files.json
export-prefix/AWSDynamoDB/ExportId/manifest-files.checksum

注記

要約マニフェスト


{
 "version": "2023-08-01",
 "exportArn": "arn:aws:dynamodb:us-east-1:599882009758:table/export-test/export/01695097218000-d6299cbd",
 "startTime": "2023-09-19T04:20:18.000Z",
 "endTime": "2023-09-19T04:40:24.780Z",
 "tableArn": "arn:aws:dynamodb:us-east-1:599882009758:table/export-test",
 "tableId": "b116b490-6460-4d4a-9a6b-5d360abf4fb3",
 "exportFromTime": "2023-09-18T17:00:00.000Z",
 "exportToTime": "2023-09-19T04:00:00.000Z",
 "s3Bucket": "jason-exports",
 "s3Prefix": "20230919-prefix",
 "s3SseAlgorithm": "AES256",
 "s3SseKmsKeyId": null,
 "manifestFilesS3Key": "20230919-prefix/AWSDynamoDB/01693685934212-ac809da5/manifest-files.json",
 "billedSizeBytes": 20901239349,
 "itemCount": 169928274,
 "outputFormat": "DYNAMODB_JSON",
 "outputView": "NEW_AND_OLD_IMAGES",
 "exportType": "INCREMENTAL_EXPORT"
}

ファイルマニフェスト


{
"itemCount": 8,
   "md5Checksum": "sQMSpEILNgoQmarvDFonGQ==",
   "etag": "af83d6f217c19b8b0fff8023d8ca4716-1",
   "dataFileS3Key": "AWSDynamoDB/data/sgad6417s6vss4p7owp0471bcq.json.gz"
}

データファイル

増分エクスポートのデータファイルはすべて S3 バケットの共通データフォルダーに格納されています。マニフェストファイルはエクスポート ID フォルダーにあります。


DestinationBucket/DestinationPrefix
.
└── AWSDynamoDB
    ├── 01693685934212-ac809da5     // an incremental export ID
    │   ├── manifest-files.json     // manifest points to files under 'data' folder
    │   ├── manifest-files.checksum
    │   ├── manifest-summary.json   // stores metadata about request
    │   ├── manifest-summary.md5  
    │   └── _started                // empty file for permission check
    ├── 01693686034521-ac809da5
    │   ├── manifest-files.json
    │   ├── manifest-files.checksum
    │   ├── manifest-summary.json
    │   ├── manifest-summary.md5
    │   └── _started
    ├── data                        // stores all the data files for incremental exports
    │   ├── sgad6417s6vss4p7owp0471bcq.json.gz 
    │   ...

ファイルをエクスポートする場合、各項目の出力には、テーブル内でその項目が更新された日時を表すタイムスタンプとinsert、update、または delete オペレーションであったかどうかを示すデータ構造が含まれます。タイムスタンプは内部システムクロックに基づいており、アプリケーションクロックとは異なる場合があります。増分エクスポートでは、出力構造の 2 つのエクスポートビュータイプ (新旧イメージ、または新しいイメージのみ) を選択できます。

新しいイメージには、項目の最新の状態が表示されます。
古いイメージには、指定した開始日時の直前の項目の状態が表示されます。

ビュータイプは、エクスポート期間中に項目がどのように変更されたかを確認する場合に役立ちます。また、特にダウンストリームシステムに DynamoDB パーティションキーと異なるパーティションキーがある場合に、ダウンストリームシステムを効率的に更新するのにも役立ちます。

増分エクスポート出力の項目が insert、update、または delete のどれであったかは、出力の構造を見れば推測できます。両方のエクスポートビュータイプについて、増分エクスポートの構造とそれに対応するオペレーションを以下の表にまとめています。

操作	新しいイメージのみ	新旧イメージ
Insert	キー + 新しいイメージ	キー + 新しいイメージ
更新	キー + 新しいイメージ	キー + 新しいイメージ + 古いイメージ
削除	キー	キー + 古いイメージ
delete + insert	出力なし	出力なし

DynamoDB JSON

DynamoDB JSON 形式のテーブルエクスポートは、項目の書き込み時間を示すメタデータタイムスタンプと、それに続く項目のキーと値で構成されています。以下は、エクスポートビュータイプを新イメージおよび旧イメージとして使用した DynamoDB JSON 出力の例を示しています。


// Ex 1: Insert
//   An insert means the item did not exist before the incremental export window
//   and was added during the incremental export window

{
   "Metadata": {
     "WriteTimestampMicros": "1680109764000000"
   },
   "Keys": {
     "PK": { 
       "S": "CUST#100" 
     }
   },
   "NewImage": {
     "PK": { 
       "S": "CUST#100" 
     },
     "FirstName": {
       "S": "John"
     },
     "LastName": {
       "S": "Don"
     }
   }
}

// Ex 2: Update
//   An update means the item existed before the incremental export window
//   and was updated during the incremental export window. 
//   The OldImage would not be present if choosing "New images only".

{
   "Metadata": {
     "WriteTimestampMicros": "1680109764000000"
   },
   "Keys": {
     "PK": { 
       "S": "CUST#200" 
     }
   },
   "OldImage": {
     "PK": { 
       "S": "CUST#200" 
     },
     "FirstName": {
       "S": "Mary"
     },
     "LastName": {
       "S": "Grace"
     }
   },
   "NewImage": {
     "PK": { 
       "S": "CUST#200" 
     },
     "FirstName": {
       "S": "Mary"
     },
     "LastName": {
       "S": "Smith"
     }
   }
}

// Ex 3: Delete
//   A delete means the item existed before the incremental export window
//   and was deleted during the incremental export window
//   The OldImage would not be present if choosing "New images only".

{
   "Metadata": {
     "WriteTimestampMicros": "1680109764000000"
   },
   "Keys": {
     "PK": { 
       "S": "CUST#300" 
     }
   },
   "OldImage": {
     "PK": { 
       "S": "CUST#300" 
     },
     "FirstName": {
       "S": "Jose"
     },
     "LastName": {
       "S": "Hernandez"
     }
   }
}

// Ex 4: Insert + Delete
//   Nothing is exported if an item is inserted and deleted within the 
//   incremental export window.

Amazon Ion

次の表に、DynamoDB データ型と ion データ型のマッピングを示します。

DynamoDB データ型	Ion 表現
文字列 (S)	文字列
ブール型 (BOOL)	ブール
数値 (N)	小数点
バイナリ (B)	blob
セット (SS、NS、BS)	リスト (型注釈 $DynamoDB_SS、$DynamoDB_NS、または $DynamoDB_BS)
リスト	リスト
マップ	構造体


$ion_1_0 {
    Record:{
        Keys:{
             ISBN:"333-3333333333"
         },
        Metadata:{
            WriteTimestampMicros:1684374845117899.
        },
        OldImage:{
            Authors:$dynamodb_SS::["Author1","Author2"],
            ISBN:"333-3333333333",
            Id:103.,
            InPublication:false,
            ProductCategory:"Book",
            Title:"Book 103 Title"
        },
        NewImage:{
            Authors:$dynamodb_SS::["Author1","Author2"],
            Dimensions:"8.5 x 11.0 x 1.5",
            ISBN:"333-3333333333",
            Id:103.,
            InPublication:true,
            PageCount:6d2,
            Price:2d3,
            ProductCategory:"Book",
            Title:"Book 103 Title"
        }
    }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

テーブルのエクスポートのリクエスト

Amazon OpenSearch Service との統合