# DynamoDB テーブルのエクスポート出力形式
<a name="S3DataExport.Output"></a>

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

**Topics**

## フルエクスポート出力
<a name="full-export-output"></a>

### マニフェストファイル
<a name="S3DataExport.Output_Manifest"></a>

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` という名前の空のファイルが作成されます。このファイルは、エクスポート先のバケットが書き込み可能であること、およびエクスポートが開始されたことを検証します。これは安全に削除できます。

#### 要約マニフェスト
<a name="S3DataExport.Output_Manifest_Summary"></a>

`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"
}
```

#### ファイルマニフェスト
<a name="S3DataExport.Output_Manifest_Files"></a>

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

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

### データファイル
<a name="S3DataExport.Output_Data"></a>

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

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

```
amzn-s3-demo-bucket/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
<a name="S3DataExport.Output_Data_DDB-JSON"></a>

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

DynamoDB JSON エクスポートデータ用のカスタムパーサーを作成する場合、形式は [JSON Lines](https://jsonlines.org/) です。これは、改行が項目の区切り文字として使用されていることを意味します。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
<a name="S3DataExport.Output_Data_ION"></a>

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

テーブルを Ion 形式にエクスポートすると、テーブルで使用されている DynamoDB データ型が [Ion データ型](http://amzn.github.io/ion-docs/docs/spec.html)にマップされます。DynamoDB セットは、[Ion 型注釈](http://amzn.github.io/ion-docs/docs/spec.html#annot)を使用して、ソーステーブルで使用されるデータ型を明確にします。

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


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

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"
    }
}
```

## 増分エクスポート出力
<a name="incremental-export-output"></a>

### マニフェストファイル
<a name="S3DataIncrementalExport.Output_Manifest"></a>

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` という名前の空のファイルが作成されます。このファイルは、エクスポート先のバケットが書き込み可能であること、およびエクスポートが開始されたことを検証します。これは安全に削除できます。

#### 要約マニフェスト
<a name="S3DataIncrementalExport.Output_Manifest_Summary"></a>

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

```
{
 "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"
}
```

#### ファイルマニフェスト
<a name="S3DataIncrementalExport.Output_Manifest_Files"></a>

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

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

### データファイル
<a name="S3DataIncrementalExport.Output_Data"></a>

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

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

```
amzn-s3-demo-bucket/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` のどれであったかは、出力の構造を見れば推測できます。両方のエクスポートビュータイプについて、増分エクスポートの構造とそれに対応するオペレーションを以下の表にまとめています。


| Operation | 新しいイメージのみ | 新旧イメージ | 
| --- | --- | --- | 
|  Insert  |  キー \$1 新しいイメージ  | キー \$1 新しいイメージ | 
|  更新  | キー \$1 新しいイメージ | キー \$1 新しいイメージ \$1 古いイメージ | 
| 削除 | キー | キー \$1 古いイメージ | 
| delete \$1 insert | 出力なし | 出力なし | 

#### DynamoDB JSON
<a name="S3DataIncrementalExport.Output_Data_DDB-JSON"></a>

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
<a name="S3DataIncrementalExport.Output_Data_ION"></a>

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

テーブルを Ion 形式にエクスポートすると、テーブルで使用されている DynamoDB データ型が [Ion データ型](http://amzn.github.io/ion-docs/docs/spec.html)にマップされます。DynamoDB セットは、[Ion 型注釈](http://amzn.github.io/ion-docs/docs/spec.html#annot)を使用して、ソーステーブルで使用されるデータ型を明確にします。

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


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

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

```
$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"
        }
    }
}
```