# 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`가 서로 덮어쓰지 않도록 서비스에서 생성되는 고유한 토큰입니다.

이 내보내기를 수행하면 파티션당 하나 이상의 파일이 생성됩니다. 비어 있는 파티션의 경우 내보내기 요청을 통해 빈 파일이 생성됩니다. 각 파일의 모든 항목은 해당 파티션의 해시된 키스페이스에서 가져온 것입니다.

**참고**  
또한 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/)입니다. 즉, 줄 바꿈이 항목 구분 기호로 사용된다는 의미입니다. Athena, AWS Glue 등의 여러 AWS 서비스에서 이 형식을 자동으로 구문 분석합니다.

다음 예제에서는 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는 JSON의 상위 집합인 Ion [텍스트 형식](http://amzn.github.io/ion-docs/docs/spec.html)으로 테이블 데이터를 내보낼 수 있습니다.

테이블을 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) | 문자열 | 
| Boolean(BOOL) | bool | 
| 숫자(N) | decimal | 
| 이진수(B) | blob | 
| 세트(SS, NSS, BS) | list(유형 주석 \$1dynamodb\$1SS, \$1dynamodb\$1NS 또는 \$1dynamodb\$1BS 사용) | 
| 목록 | list | 
| 맵 | 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`가 서로 덮어쓰지 않도록 서비스에서 생성되는 고유한 토큰입니다.

이 내보내기를 수행하면 파티션당 하나 이상의 파일이 생성됩니다. 비어 있는 파티션의 경우 내보내기 요청을 통해 빈 파일이 생성됩니다. 각 파일의 모든 항목은 해당 파티션의 해시된 키스페이스에서 가져온 것입니다.

**참고**  
또한 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이전 이미지 | 
| Insert \$1 delete | 출력 없음 | 출력 없음 | 

#### 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는 JSON의 상위 집합인 Ion [텍스트 형식](http://amzn.github.io/ion-docs/docs/spec.html)으로 테이블 데이터를 내보낼 수 있습니다.

테이블을 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) | 문자열 | 
| Boolean(BOOL) | bool | 
| 숫자(N) | decimal | 
| 이진수(B) | blob | 
| 세트(SS, NSS, BS) | list(유형 주석 \$1dynamodb\$1SS, \$1dynamodb\$1NS 또는 \$1dynamodb\$1BS 사용) | 
| 목록 | list | 
| 맵 | 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"
        }
    }
}
```