정의
$iceberg 단계는 연결 레지스트리(Connection Registry)에서 Amazon Web Services S3 버킷 또는 Azure Blob 저장 컨테이너에 대한 연결을 지정합니다. 이 컨테이너에서 Apache Iceberg 테이블에 데이터를 쓰기 (write)할 수 있습니다.
배치
$iceberg 파이프라인에 나타나는 경우 파이프라인의 마지막 단계여야 합니다. 파이프라인당 하나의 $iceberg 단계만 사용할 수 있습니다.
구문
$iceberg 파이프라인 단계의 프로토타입 형식은 다음과 같습니다.
{ "$iceberg": { "connectionName": "<registered-connection>", "bucket": "<target-bucket>", "container": "<target-container>", "databaseName": "<database>", "tableName": "<string>" | <expression>, "path": "<key-prefix>", "region": "<target-region>", "mode": "cdc" | "insert", "idFieldName": "<field-name>", "partitionedBy": { "<column-name>": "<partition-transform>", . . . }, "catalog": { "type": "hadoop" | "glue" | "unity" | "horizon", "connectionName": "<data-catalog-connection>", "warehouse": "<warehouse>" }, "schemaInference": { "mode": "json" | "nested" } }}$iceberg 단계에서는 다음 필드가 있는 문서를 사용합니다.
필드 | 유형 | 필요성 | 설명 |
|---|---|---|---|
| 문자열 | 필수 사항 | 읽기 및 쓰기 (write)에 사용할 Amazon Web Services S3 또는 Azure Blob 저장 연결의 이름입니다. 이는 연결 레지스트리의 연결 이름과 일치해야 합니다. |
| 문자열 | 조건부 | S3 연결에 필요합니다. 대상 Apache Iceberg 데이터베이스가 포함된 S 버킷의 이름입니다.3 |
| 문자열 | 조건부 | Azure Blob 저장 연결에 필요합니다. 대상 Apache Iceberg 데이터베이스를 포함하는 Azure Blob 저장 컨테이너의 이름입니다. |
| 문자열 | 필수 사항 | 대상 테이블이 포함된 Apache Iceberg 데이터베이스의 이름입니다. |
| 문자열 | 표현식 | 필수 사항 | 대상 Apache Iceberg 테이블의 이름입니다. Must be either a string or an expression that evaluates to a string. 문서별 동적 라우팅에 표현식을 사용합니다. |
| 문자열 | 필수 사항 | Apache Iceberg 데이터베이스에 대한 경로의 접두사 키. |
| 문자열 | 조건부 | AWS 버킷의 리전. AWS 에서 실행되지 않는 스트림 프로세서에 필수입니다. Azure Blob 저장 연결에는 적용되지 않습니다. |
| 문자열 | 옵션 | 입력 문서당 수행할 작업을 결정하기 위한 전략입니다.
기본값은 |
| 문자열 | 옵션 |
기본값은 |
| 문서 | 옵션 | 분할 사양. 이 필드를 설정하지 않으면 1개에서 3개의 키-값 쌍을 포함하는 문서여야 합니다. 각 키는 파티션 변환을 수행할 열의 이름이어야 하며, 각 값은 사용할 파티션 변환이어야 합니다. 첫 번째 파티션 변환은
주어진 필드의 파티션 변환 값은 다음 중 하나여야 합니다.
Apache Iceberg 분할 변환에 대한 자세한 내용은 Apache Iceberg 설명서를 참조하세요. |
| 문서 | 옵션 | 사용할 Iceberg 카탈로그를 정의하는 문서입니다.
|
| 문서 | 옵션 |
기본값은 |
catalog 필드
catalog 문서에는 다음 필드가 포함됩니다.
필드 | 유형 | 필요성 | 설명 |
|---|---|---|---|
| 문자열 | 옵션 | 사용할 Apache Iceberg 카탈로그 유형입니다. 다음 값 중 하나여야 합니다.
|
| 문자열 | 조건부 | 사용할 데이터 카탈로그 연결의 이름입니다. 이 이름은 연결 레지스트리에 있는 데이터 카탈로그 연결의 이름과 일치해야 합니다.
|
| 문자열 | 조건부 | 대상 스키마가 포함된 카탈로그의 위치입니다.
|
"unity" 및 "horizon" 카탈로그의 경우 $iceberg는 warehouse, databaseName 및 tableName 필드에서 대상 테이블을 확인합니다.
Catalog Type | warehouse | databaseName | tableName |
|---|---|---|---|
| Databricks catalog | Databricks 스키마 | 테이블 이름 |
| Snowflake 데이터베이스 | Snowflake 스키마 | 테이블 이름 |
참고
Atlas Stream Processing이 웨어하우스나 스키마를 찾을 수 없는 경우, 올바른 필드에 warehouse 및 databaseName 값을 지정했는지 확인하세요. Snowflake 데이터베이스 이름은 일반적으로 대문자입니다.
행동
$iceberg 단계를 사용하는 경우 스트림 프로세서의 마지막 단계여야 합니다.
Atlas Stream Processing은 SP10, SP30 및 SP50 스트림 프로세서에서만 $iceberg 단계를 지원합니다. 프로세서 계층에 따라 동적 라우팅에 대해 지원되는 최대 테이블 수가 결정됩니다.
계층 | 최대 테이블 |
|---|---|
SP10 | 5 |
SP30 | 10 |
SP50 | 50 |
중요
동적 라우팅을 사용하는 스트림 프로세서가 해당 계층에서 지원되는 최대 테이블 수를 초과하면 프로세서는 FAILED 상태가 됩니다. 실패 원인 및 복구에 대한 자세한 내용은 오류 처리 및 재시도 정책을 참조하세요.
$iceberg 단계는 스트림 프로세서의 출력 데이터 스키마에서 결과 Apache Iceberg 테이블의 스키마를 유추합니다. Atlas Stream Processing이 struct 열 내의 필드를 포함하여 스트림의 새 필드를 관찰하면 테이블 스키마가 그에 따라 발전합니다.
이미 존재하지 않는 테이블을 지정하면 Apache Iceberg 가 해당 테이블을 대상으로 하는 첫 번째 메시지를 받을 때 테이블을 생성합니다.
Atlas Stream Processing은 Apache Iceberg 테이블로의 출력에 대해 최소 1회 처리를 보장합니다.
tableName 필드의 값으로 동적 표현식 을 사용할 수 있습니다. 동적 표현식을 사용하여 문서 특정 값을 캡처하면 이 값에 따라 입력 문서를 다른 테이블로 라우팅할 수 있습니다. 표현식은 문자열로 평가되어야 합니다. 예시는 동적 라우팅을 참조하세요. 자세한 내용은 표현식 연산자를 참조하세요.
동적 표현식으로 주제를 지정했지만 Atlas Stream Processing이 지정된 메시지에 대한 표현식을 평가할 수 없는 경우, Atlas Stream Processing은 구성된 경우 해당 메시지를 데드 레터 큐로 보내고 후속 메시지를 처리합니다. 데드 레터 큐 가 구성되어 있지 않은 경우 Atlas Stream Processing은 메시지를 완전히 건너뛰고 후속 메시지를 처리합니다.
유형 변환
Atlas Stream Processing은 $iceberg 단계의 테이블에 기록할 때 BSON 에서 Iceberg 기본 유형 으로 유형 변환을 수행합니다.
BSON | 세부 정보 | |
|---|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| 16진수 인코딩되었습니다. |
|
| 문자열화된 UUID |
|
| UUID에 적용되지 않음 |
|
| 마이크로초 단위로 측정되는 UTC 시간 |
|
| UTC 시간, 마이크로초단위로 측정 |
|
| 기본적으로 Basic JSON 문자열로 직렬화됩니다. |
|
| 기본적으로 Basic JSON 문자열로 직렬화됩니다. |
다른 BSON types는 지원되지 않습니다. Atlas Stream Processing은 지원되지 않는 BSON types을 포함한 문서를 DLQ로 보냅니다.
객체 및 배열 필드
schemaInference.mode 필드는 Atlas Stream Processing이 Apache Iceberg 테이블에 object 및 array 필드를 쓰기 (write) 방법을 결정합니다.
json모드에서 Atlas Stream Processing은object및array필드를 Basic JSON 문자열로 직렬화하고string열에 쓰기 (write).json은(는) 기본값 모드입니다.nested모드에서 Atlas Stream Processing은object및array필드에서 Iceberg 중첩 유형을(를) 유추합니다.각
object필드는struct열이 됩니다. Atlas Stream Processing은 객체의 해당 필드에서 구조체의 각 필드 유형을 유추합니다. 이는 모든 중첩 수준에 적용됩니다.각
array필드는list열이 됩니다. Atlas Stream Processing은 배열의 null이 아닌 요소에서 리스트 요소 유형을 추론합니다. 기본 요소는 모두 동일한 유형이어야 합니다. 요소가 객체인 경우, 요소 형식은 모든 객체의 필드를 포함하는struct입니다.
이 모드는 대상 테이블에 일치하는 열이 없는 필드에만 적용됩니다. 열이 이미 존재하는 경우 Atlas Stream Processing은 모드를 무시하고 열 유형에 따라 필드를 쓰기 (write).
열이
string인 경우, Atlas Stream Processing은 해당 필드를 Basic JSON string으로 직렬화합니다.열이
struct또는list인 경우, Atlas Stream Processing은 해당 필드를 중첩된 유형으로 쓰기 (write).
입력에 새로운 object 또는 array 필드가 포함된 경우, Atlas Stream Processing은 모드를 사용하여 새 열의 유형을 추론합니다.
예시
다음 예시는 $iceberg 단계의 다양한 애플리케이션을 설명합니다.
변경 스트림 보관
다음 예시는 Atlas 데이터베이스의 초기 내용과 변경 스트림을 추가 전용 방식으로 Apache Iceberg 테이블에 쓰는 방법을 보여주며, 해당 데이터베이스의 운영 기록의 지속형 보관을 생성합니다. 이 집계는 두 단계로 구성됩니다.
$source단계는 Atlas 데이터베이스와 연결하고 구체적으로db데이터베이스의orders컬렉션을 대상으로 지정합니다. 이를 통해 초기 동기화를 실행하여 프로세서 활성화 시점에 데이터베이스의 문서를 캡처하고 각 변경 스트림 이벤트로 전체 문서가 캡처되도록 합니다.$iceberg단계는 AWS S3 버킷에 연결을 수립하고iceberg-warehouse/경로의myTable테이블에 기록합니다.insert작업만 지정하면 추가만 가능한 로그 스타일의 쓰기 (write) 플로우를 확보합니다.
{ "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } }, "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "tableName": "myTable", "mode": "insert" }}컬렉션 미러링
다음 예시는 Atlas 컬렉션 전체를 Apache Iceberg 테이블로 반영하는 방법을 보여줍니다.
집계를 정의하기 전에 다음 변수를 설정합니다.
const isDeleteExpr = {$eq: [{$meta: "stream.source.operationType"}, "delete"]};다음 집계는 Atlas 소스 컬렉션의 변경 사항과 동기화되어 Apache Iceberg 테이블 엔트리를 추가, 업데이트 및 삭제합니다. 이것에는 4단계가 있습니다.
$source단계는 Atlas 데이터베이스와 연결하고 구체적으로db데이터베이스의orders컬렉션을 대상으로 지정합니다. 이를 통해 초기 동기화를 실행하여 프로세서 활성화 시점에 데이터베이스의 문서를 캡처하고 각 변경 스트림 이벤트로 전체 문서가 캡처되도록 합니다.$match단계는operationType에 대한 필터링을 수행하여 유효한 작업 유형 선언이 포함된 문서만 처리합니다.$replaceRoot단계는 작업 유형에 따라 문서 루트를 변경합니다.삭제 작업의 경우 문서 루트를 문서의 키로 변경합니다. 이로 인해 문서가 삭제되었음을 기록하지만 그 내용은 추가 처리에서 제외됩니다.
다른 모든 작업의 경우 문서 루트를
fullDocument로 변경하고 문서 내용을 전달하여 추가 처리하도록 하는 동안 변경 스트림 메타데이터는 제외합니다.
The
$icebergstage establishes a connection to the AWS S3 bucket, writing to an Apache Iceberg table namedmyTablein theiceberg-warehouse/path. Incdcmode, this stage determines the operation to perform against the Apache Iceberg table by reading from thestream.source.operationTypemetadata field of each document.
{ "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } }, "$match": { "operationType": { "$in": ["insert", "update", "delete", "replace"] } }, "$replaceRoot": { "newRoot": { "$cond": { "if": isDeleteExpr, "then": "$documentKey", "else": "$fullDocument" } } } "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "tableName": "myTable", "mode": "cdc" }}다중 컬렉션 소스에서 다중 테이블 Apache Iceberg 대상으로
다음 예시에서 Atlas Stream Processing은 동적 표현식을 사용하여 문서를 다양한 출력 대상으로 동적으로 라우팅합니다.
$source단계는 Atlas 데이터베이스와 연결을 수립하며, 구체적으로db데이터베이스의a,b,c컬렉션을 대상으로 합니다. 이를 통해 초기 동기화를 실행하여 프로세서 활성화 시점에 데이터베이스의 문서를 캡처하고 각 변경 스트림 이벤트로 전체 문서가 캡처되도록 합니다.$match단계는operationType이"insert","update","delete"또는"replace"인 문서를 필터링합니다.$replaceRoot단계는 작업 유형에 따라 문서 루트를 변경합니다.삭제 작업의 경우 문서 루트를 문서의 키로 변경합니다. 이로 인해 문서가 삭제되었음을 기록하지만 그 내용은 추가 처리에서 제외됩니다.
다른 모든 작업의 경우 문서 루트를
fullDocument로 변경하고 문서 내용을 전달하여 추가 처리하도록 하는 동안 변경 스트림 메타데이터는 제외합니다.
The
$icebergstage establishes a connection to the AWS S3 bucket namedmyData, writing to an Apache Iceberg table in theiceberg-warehouse/path. It determines the name of the table according to the name of the sourcecollectionas retrieved from document metadata. It also determines the operation to perform according to document metadata.
{ "$source": { "connectionName": "atlas1", "db": "db", "coll": ["a", "b", "c"], "initialSync": { "enable": true }, "config": { "fullDocument": "required" } }},{ "$match": { "operationType": { "$in": ["insert", "update", "delete", "replace"] } }},{ "$replaceRoot": { "newRoot": { "$cond": { "if": { "$eq": [{ "$meta": "stream.source.operationType" }, "delete"] }, "then": "$documentKey", "else": "$fullDocument" } } }},{ "$iceberg": { "connectionName": "myS3Connection", "databaseName": "iceberg-db", "bucket": "myData", "path": "iceberg-warehouse/", "tableName": { "$meta": "stream.source.ns.coll" }, "mode": "cdc" }}데이터 카탈로그 테이블에 쓰기
다음 예시는 Atlas 컬렉션의 초기 콘텐츠와 변경 스트림을 데이터 카탈로그가 managed하는 Apache Iceberg 테이블에 쓰기 (write)하는 방법을 보여줍니다. 카탈로그 유형에 대한 탭을 선택합니다. 이 예시에서는 mode를 insert로 설정하여 각 문서를 새 행으로 테이블에 추가합니다. 이 집계에는 두 단계가 있습니다.
$source단계는 Atlas 데이터베이스와 연결하고 구체적으로db데이터베이스의orders컬렉션을 대상으로 지정합니다. 이를 통해 초기 동기화를 실행하여 프로세서 활성화 시점에 데이터베이스의 문서를 캡처하고 각 변경 스트림 이벤트로 전체 문서가 캡처되도록 합니다.$iceberg단계는myS3Connection연결을 통해myData라는 이름의 Amazon Web Services S3 버킷에 쓰기 (write)를 수행합니다. 데이터 카탈로그 연결을 사용하여 카탈로그의orders테이블에 쓰기 (write)를 수행합니다.
$iceberg 단계는 myUnityCatalog 데이터 카탈로그 연결을 사용하여 Databricks main 카탈로그의 sales 스키마에 있는 orders 테이블에 쓰기 (write)합니다. unity 카탈로그 유형은 cdc 모드를 지원하지 않으므로 mode을(를) insert(으)로 설정해야 합니다.
[ { "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } } }, { "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "databaseName": "sales", "tableName": "orders", "mode": "insert", "catalog": { "type": "unity", "connectionName": "myUnityCatalog", "warehouse": "main" } } }]$iceberg 단계는 myHorizonCatalog 데이터 카탈로그 연결을 사용하여 Snowflake ICEBERG_DB 데이터베이스의 SALES 스키마에 있는 orders 테이블에 쓰기 (write)합니다.
[ { "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } } }, { "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "databaseName": "SALES", "tableName": "orders", "mode": "insert", "catalog": { "type": "horizon", "connectionName": "myHorizonCatalog", "warehouse": "ICEBERG_DB" } } }]