Definición
La etapa $iceberg especifica una conexión en el Registro de conexiones a un bucket de Amazon Web Services S3 o a un contenedor de almacenamiento de Azure donde puede guardar datos en una tabla de Apache Iceberg.
Ubicación
$iceberg debe ser la última etapa de cualquier pipeline en la que aparezca. Solo puede utilizar una etapa $iceberg por pipeline.
Sintaxis
La etapa de pipeline $iceberg tiene la siguiente forma de prototipo:
{ "$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" } }}La etapa $iceberg procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Requerido | Nombre de la conexión de AWS S3 o Azure Blob almacenamiento que se utilizará para leer y guardar. Esto debe coincidir con el nombre de la conexión en el Registro de conexiones. |
| string | Condicional | Necesario para conexiones S3. Nombre del bucket de S3 que contiene la base de datos de Apache Iceberg de destino. Si estableces |
| string | Condicional | Necesario para conexiones de Azure Blob almacenamiento. Nombre del contenedor de Azure Blob almacenamiento que contiene la base de datos de Apache Iceberg de destino. Si estableces |
| string | Requerido | Nombre de la base de datos Apache Iceberg que contiene la tabla de destino. |
| string | expresión | Requerido | Nombre de la tabla de destino Apache Iceberg. Debe ser una string o una expresión que se evalúe como una string. Utiliza expresiones para el enrutamiento dinámico por documento. |
| string | Requerido | Prefijo de la clave de la ruta a su base de datos Apache Iceberg. |
| string | Condicional | AWS región del bucket. Necesario para procesadores de flujo que no se ejecutan en AWS. No se aplica a las conexiones de Azure Blob almacenamiento. |
| string | Opcional | Estrategia para determinar qué operación realizar por documento de entrada.
Se establece por defecto en |
| string | Opcional | Campo y nombre de columna utilizados como clave de fila en el modo Se establece por defecto en |
| Documento | Opcional | Especificación de particionamiento. Si no establece este campo, Debe ser un documento que contenga entre uno y tres pares clave-valor. Cada clave debe ser el nombre de una columna en la que realizar una transformación de partición, y cada valor debe ser la transformación de partición que se va a utilizar. La primera transformación de partición debe aplicarse a Para particionar por un campo anidado dentro de una columna El valor de transformación de partición de un campo determinado debe ser uno de los siguientes:
Para obtener más información sobre las transformaciones de particiones de Apache Iceberg, consulte la documentación de Apache Iceberg. |
| Documento | Opcional | Documento que define el catálogo de Iceberg que se va a utilizar. Debe ser un documento que contenga el campo Los tipos de catálogo El |
| Documento | Opcional | Documento que configura cómo
Se establece por defecto en |
catalog Campos
El documento catalog acepta los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Opcional | Tipo de catálogo de Apache Iceberg que se utilizará. Debe ser uno de los siguientes valores:
|
| string | Condicional | Nombre de la conexión del catálogo de datos que se utilizará. Esto debe coincidir con el nombre de una conexión del catálogo de datos en el Registro de conexiones. Obligatorio si Atlas Stream Processing rechaza este campo si |
| string | Condicional | Ubicación en el catálogo que contiene el esquema de destino. Obligatorio si Atlas Stream Processing rechaza este campo si
|
Para los catálogos "unity" y "horizon", $iceberg resuelve la tabla de destino a partir de los campos warehouse, databaseName y tableName:
Catalog Type | warehouse | databaseName | tableName |
|---|---|---|---|
| Databricks catalog | Esquema de Databricks | Nombre de la tabla |
| base de datos de Snowflake | Esquema en copo de nieve | Nombre de la tabla |
Nota
Si Atlas Stream Processing no puede encontrar el almacén o el esquema, confirme que especificó los valores warehouse y databaseName en los campos correctos. Los nombres de las bases de datos de Snowflake suelen estar en mayúsculas.
Comportamiento
Si utiliza la etapa $iceberg, debe ser la última etapa de su procesador de transmisión.
Atlas Stream Processing es compatible con la etapa $iceberg solo para los procesadores de transmisión SP10, SP30 y SP50. Su nivel de procesador determina el número máximo de tablas compatibles con el enrutamiento dinámico:
Nivel | Tablas máximas |
|---|---|
SP10 | 5 |
SP30 | 10 |
SP50 | 50 |
Importante
Si un procesador de flujo con enrutamiento dinámico supera el número máximo de tablas admitidas en su nivel, el procesador entra en un estado de FAILED. Para aprender sobre las causas de los errores y la recuperación, consulta Gestión de errores y políticas de reintentos.
La etapa $iceberg infiere el esquema de la tabla resultante Apache Iceberg a partir del esquema de los datos de salida del procesador de transmisión. A medida que Atlas Stream Processing observa nuevos campos en el flujo, incluidos campos dentro de struct columnas, el esquema de la tabla evoluciona en consecuencia.
Si especifica una tabla que aún no existe, Apache Iceberg crea la tabla cuando recibe el primer mensaje que la dirige.
Atlas Stream Processing garantiza el procesamiento al menos una vez para la salida a las tablas de Apache Iceberg.
Puede utilizar una expresión dinámica como valor del campo tableName. Al utilizar una expresión dinámica para capturar valores específicos del documento, puede enrutar los documentos de entrada a diferentes tablas según estos valores. La expresión debe evaluarse como una string. Para obtener un ejemplo, consulte Enrutamiento dinámico. Para obtener más información, consulte operadores de expresión.
Si especifica un tema con una expresión dinámica, pero Atlas Stream Processing no puede evaluar la expresión para un mensaje determinado, Atlas Stream Processing envía ese mensaje a la fila de letra muerta, si está configurada, y procesa los mensajes subsiguientes. Si no hay ninguna fila de letra muerta configurada, Atlas Stream Processing omite el mensaje por completo y procesa los mensajes subsiguientes.
Conversión de tipo
Atlas Stream Processing realiza la conversión de tipos de BSON a tipos primitivos de Iceberg al escribir en tablas en la etapa $iceberg.
BSON | Apache Iceberg Primitivo | Detalles |
|---|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| Codificado en hexadecimal |
|
| UUID en cadena |
|
| No se aplica a UUID |
|
| Hora UTC, medida en microsegundos |
|
| Hora UTC, medida en microsegundos |
|
| Serializado como un JSON básico string por defecto. En moda |
|
| Serializado como un JSON básico string por defecto. En moda |
No se admiten otros BSON types. Atlas Stream Processing envía documentos con BSON types no admitidos a la DLQ.
Campos de objeto y arreglo
El campo schemaInference.mode determina cómo Atlas Stream Processing guardar los campos object y array en las tablas de Apache Iceberg:
En la moda
json, Atlas Stream Processing serializa los camposobjectyarraycomo cadenas JSON básicas y los guarda en las columnasstring.jsones la moda por defecto.En moda
nested, Atlas Stream Processing infiere tipos anidados de Iceberg a partir de los camposobjectyarray:Cada campo
objectse convierte en una columnastruct. Atlas Stream Processing infiere el tipo de cada campo de la estructura a partir del campo correspondiente del objeto. Esto se aplica en cada nivel de anidamiento.Cada campo
arrayse convierte en una columnalist. Atlas Stream Processing infiere el tipo de elemento de la lista a partir de los elementos no nulos del arreglo. Los elementos primitivos deben ser todos del mismo tipo. Si los elementos son objetos, el tipo de elemento es unstructque contiene los campos de todos los objetos.
La moda se aplica solo a los campos que no tienen una columna coincidente en la tabla de destino. Si la columna ya existe, Atlas Stream Processing ignora la moda y guarda el campo según el tipo de columna:
Si la columna es un
string, Atlas Stream Processing serializa el campo como un JSON básico string.Si la columna es un
structo unlist, Atlas Stream Processing guardar el campo como ese tipo anidado.
Si la entrada contiene nuevos campos object o array, Atlas Stream Processing utiliza la moda para inferir los tipos de las nuevas columnas.
Ejemplos
Los siguientes ejemplos ilustran varias aplicaciones de la etapa $iceberg.
Archivar un Changestream
El siguiente ejemplo muestra cómo guardar el contenido inicial y el changestream de una base de datos de Atlas en una tabla de Apache Iceberg de solo anexar, creando un fichero duradero del historial operativo de esa base de datos. Esta agregación tiene dos etapas:
La etapa
$sourceestablece una conexión con la base de datos de Atlas, específicamente dirigida a la colecciónordersen la base de datosdb. Permite que la sincronización inicial capture documentos en la base de datos en el momento de la activación del procesador y garantiza que cada evento de flujo de cambios capture el documento completo.La etapa
$icebergestablece una conexión con el cubo AWS S3, escribiendo en una tabla llamadamyTableen la rutaiceberg-warehouse/. Al especificar soloinsertoperaciones, garantiza un flujo de guardar de solo anexión, estilo de registro.
{ "$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" }}Reflejar una colección
El siguiente ejemplo demuestra cómo reflejar una colección de Atlas en su totalidad en una tabla de Apache Iceberg.
Antes de definir la agregación, establezca la siguiente variable:
const isDeleteExpr = {$eq: [{$meta: "stream.source.operationType"}, "delete"]};La siguiente agregación agrega, actualiza y elimina entradas de tabla de Apache Iceberg en sincronización con los cambios en la colección de origen de Atlas. Tiene cuatro etapas:
La etapa
$sourceestablece una conexión con la base de datos de Atlas, específicamente dirigida a la colecciónordersen la base de datosdb. Permite que la sincronización inicial capture documentos en la base de datos en el momento de la activación del procesador y garantiza que cada evento de flujo de cambios capture el documento completo.La etapa
$matchfiltra enoperationTypepara que solo se procesen los documentos con declaraciones de tipo de operación válidas.La etapa
$replaceRootcambia la raíz del documento según el tipo de operación.Para las operaciones de borrado, cambia la raíz del documento a la clave del documento. Esto da como resultado un registro de que el documento se borró, pero excluye su contenido de un procesamiento posterior.
Para todas las demás operaciones, cambia la raíz del documento a
fullDocument, pasando el contenido del documento para su posterior procesamiento mientras excluye los metadatos de changestream.
La etapa
$icebergestablece una conexión con el bucket de AWS S3, escribiendo en una tabla Apache Iceberg llamadamyTableen la rutaiceberg-warehouse/. En la modacdc, esta etapa determina la operación que se va a realizar en la tabla Apache Iceberg mediante la lectura del campo de metadatosstream.source.operationTypede cada documento.
{ "$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" }}De un origen de varias colecciones a un destino de varias tablas Apache Iceberg
En el siguiente ejemplo, Atlas Stream Processing utiliza expresiones dinámicas para enrutar dinámicamente documentos a varios destinos de salida.
La etapa
$sourceestablece una conexión con la base de datos de Atlas, específicamente dirigida a las coleccionesa,bycen la base de datosdb. Permite que la sincronización inicial capture documentos en la base de datos en el momento de la activación del procesador y garantiza que cada evento de flujo de cambios capture el documento completo.La etapa
$matchfiltra los documentos cuyooperationTypees uno de"insert","update","delete"o"replace".La etapa
$replaceRootcambia la raíz del documento según el tipo de operación.Para las operaciones de borrado, cambia la raíz del documento a la clave del documento. Esto da como resultado un registro de que el documento se borró, pero excluye su contenido de un procesamiento posterior.
Para todas las demás operaciones, cambia la raíz del documento a
fullDocument, pasando el contenido del documento para su posterior procesamiento mientras excluye los metadatos de changestream.
La etapa
$icebergestablece una conexión con el cubo Amazon Web Services S3 denominadomyData, escribiendo en una tabla Apache Iceberg en la rutaiceberg-warehouse/. Determina el nombre de la tabla según el nombre de la fuentecollectionrecuperado de los metadatos del documento. También determina la operación a realizar según los metadatos del documento.
{ "$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" }}Escritura en una tabla de Data Catalog
El siguiente ejemplo demuestra cómo guardar el contenido inicial y el flujo de cambios de una colección de Atlas en una tabla de Apache Iceberg que gestiona un catálogo de datos. Seleccione la pestaña de su tipo de catálogo. El ejemplo establece mode en insert para añadir cada documento a la tabla como una nueva fila. Esta agregación consta de dos etapas:
La etapa
$sourceestablece una conexión con la base de datos de Atlas, específicamente dirigida a la colecciónordersen la base de datosdb. Permite que la sincronización inicial capture documentos en la base de datos en el momento de la activación del procesador y garantiza que cada evento de flujo de cambios capture el documento completo.La etapa
$icebergguarda en el bucket de Amazon Web Services S3 llamadomyDataa través de la conexiónmyS3Connection. Utiliza una conexión de catálogo de datos para guardar en la tablaordersdel catálogo.
La etapa $iceberg utiliza la conexión del catálogo de datos myUnityCatalog para guardar en la tabla orders en el esquema sales del catálogo main de Databricks. El tipo de catálogo unity no admite la moda cdc, por lo que debe establecer mode en 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" } } }]La etapa $iceberg utiliza la conexión del catálogo de datos myHorizonCatalog para guardar en la tabla orders del esquema SALES de la base de datos ICEBERG_DB de Snowflake.
[ { "$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" } } }]