# DynamoDB 表导出输出格式
导出格式

除了包含您的表数据的文件之外，DynamoDB 表导出还包含清单文件。这些文件都保存在[导出请求](S3DataExport_Requesting.md)指定的 Amazon S3 存储桶中。以下章节介绍每个输出对象的格式和内容。

**Topics**

## 完整导出输出


### 清单文件


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 行](https://jsonlines.org/)格式，因此，换行符用作项目分隔符。为了提高可读性，在下面的示例中，文件清单的一个数据文件的详细信息显示在多行。

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

### 数据文件


DynamoDB 可以采用两种格式导出表数据：DynamoDB JSON 和 Amazon Ion。无论选择何种格式，数据都将写入多个以键命名的压缩文件。这些文件也列在 `manifest-files.json` 文件中。

完整导出后，Amazon S3 存储桶的目录结构将在导出 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


DynamoDB JSON 格式的表导出包含多个 `Item` 对象。每个单独对象采用 DynamoDB 的标准编组 JSON 格式。

为 DynamoDB JSON 导出数据创建自定义解析器时，格式为 [JSON 行](https://jsonlines.org/)。这意味着换行符用作项目分隔符。多 AWS 服务，如 Athena 和 AWS Glue，将自动解析此格式。

在下面的示例中，为了提高可读性，DynamoDB JSON 导出的单个项目显示为多行。

```
{
    "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](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 表示 | 
| --- | --- | 
| String (S) | 字符串 | 
| Boolean (BOOL) | 布尔 | 
| Number (N) | 十进制 | 
| Binary (B) | blob | 
| Set (SS, NS, BS) | 列表（包含类型注释 \$1dynamodb\$1SS、\$1dynamodb\$1NS 或 \$1dynamodb\$1BS） | 
| 列表 | 列表 | 
| Map | struct | 

Ion 导出中的项目由换行符分隔。每行以 Ion 版本标记开头，后跟一个 Ion 格式的项目。在下面示例中，为了提高可读性，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
```

请求表导出时可以选择 **export-prefix**。这样有助于保持目标 S3 存储桶中的文件有组织。**ExportId** 是服务生成的唯一令牌，旨在确保到同一个 S3 桶和 `export-prefix` 的多个导出不互相覆盖。

导出过程为每个分区创建至少 1 个文件。对于空分区，导出请求将创建一个空文件。每个文件中的所有项目都来自于该特定分区的哈希密钥空间。

**注意**  
DynamoDB 还在清单文件的目录中创建一个名为 `_started` 的空文件。此文件验证目标存储桶是否可写入，以及导出是否已开始。可以安全删除。

#### 汇总清单


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

#### 文件清单


`manifest-files.json` 文件包含其中包含已导出表数据的文件的信息。文件采用 [JSON 行](https://jsonlines.org/)格式，因此，换行符用作项目分隔符。为了提高可读性，在下面的示例中，文件清单的一个数据文件的详细信息显示在多行。

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

### 数据文件


DynamoDB 可以采用两种格式导出表数据：DynamoDB JSON 和 Amazon Ion。无论选择何种格式，数据都将写入多个以键命名的压缩文件。这些文件也列在 `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` 操作。时间戳基于内部系统时钟，可能与您的应用程序时钟不同。对于增量导出，您可以为输出结构选择两种导出视图类型：**新旧映像**或**仅限新映像**。
+ **新映像**提供项目的最新状态 
+ **旧映像**提供项目在指定的**开始日期和时间**之前的状态

如果您想查看在导出期间项目是如何更改的，则视图类型可能会有所帮助。它还可用于高效地更新下游系统，尤其是在那些下游系统具有的分区键与您的 DynamoDB 分区键不同的情况下。

您可以通过查看输出的结构来推断增量导出输出中的项目是 `insert`、`update` 还是 `delete`。下表汇总了这两种导出视图类型的增量导出结构及其相应操作。


| 操作 | 仅限新映像 | 新旧映像 | 
| --- | --- | --- | 
|  Insert  |  键 \$1 新映像  | 键 \$1 新映像 | 
|  更新  | 键 \$1 新映像 | 键 \$1 新映像 \$1 旧映像 | 
| 删除 | 密钥 | 键 \$1 旧映像 | 
| 插入 \$1 删除 | 无输出 | 无输出 | 

#### 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


[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 表示 | 
| --- | --- | 
| String (S) | 字符串 | 
| Boolean (BOOL) | 布尔 | 
| Number (N) | 十进制 | 
| Binary (B) | blob | 
| Set (SS, NS, BS) | 列表（包含类型注释 \$1dynamodb\$1SS、\$1dynamodb\$1NS 或 \$1dynamodb\$1BS） | 
| 列表 | 列表 | 
| Map | struct | 

Ion 导出中的项目由换行符分隔。每行以 Ion 版本标记开头，后跟一个 Ion 格式的项目。在下面示例中，为了提高可读性，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"
        }
    }
}
```