Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

$iceberg etapa de agregació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.

$iceberg debe ser la última etapa de cualquier pipeline en la que aparezca. Solo puede utilizar una etapa $iceberg por pipeline.

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

connectionName

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.

bucket

string

Condicional

Necesario para conexiones S3.

Nombre del bucket de S3 que contiene la base de datos de Apache Iceberg de destino. Si estableces bucket, debes establecer region, pero no establezcas container.

container

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 container, no establezcas bucket ni region.

databaseName

string

Requerido

Nombre de la base de datos Apache Iceberg que contiene la tabla de destino.

tableName

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.

path

string

Requerido

Prefijo de la clave de la ruta a su base de datos Apache Iceberg.

region

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.

mode

string

Opcional

Estrategia para determinar qué operación realizar por documento de entrada.

  • "cdc" hace que Atlas Stream Processing determine el tipo de operación leyendo el campo de metadatos stream.source.operationType.

  • "insert" hace que Atlas Stream Processing agregue cada documento a la tabla de destino como una nueva fila, ignorando las declaraciones de tipo de operación en el campo de metadatos stream.source.operationType.

Se establece por defecto en cdc. El tipo de catálogo "unity" no admite la moda cdc. Si catalog.type es "unity", establezca mode en "insert".

idFieldName

string

Opcional

Campo y nombre de columna utilizados como clave de fila en el modo cdc.

Se establece por defecto en "_id".

partitionedBy

Documento

Opcional

Especificación de particionamiento. Si no establece este campo, $iceberg establece una transformación de partición por defecto para la columna idFieldName.

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 idFieldName.

Para particionar por un campo anidado dentro de una columna struct, especifique la ruta calificada por puntos al campo, por ejemplo outer.inner.key_field. La ruta no puede incluir una columna list en ningún nivel.

El valor de transformación de partición de un campo determinado debe ser uno de los siguientes:

  • "identity"

  • "year"

  • "month"

  • "day"

  • "hour"

  • { truncate: int }

  • { bucket: int }

Para obtener más información sobre las transformaciones de particiones de Apache Iceberg, consulte la documentación de Apache Iceberg.

catalog

Documento

Opcional

Documento que define el catálogo de Iceberg que se va a utilizar. Debe ser un documento que contenga el campo type con un valor de "hadoop", "glue", "unity" o "horizon". Los tipos de catálogo "unity" y "horizon" también requieren los campos connectionName y warehouse. Para aprender más información, consulta los campos catalog.

Los tipos de catálogo "unity", "horizon" y "hadoop" admiten conexiones S3 y Azure Blob almacenamiento.

El "glue" tipo de catálogo solo admite conexiones S.3

schemaInference

Documento

Opcional

Documento que configura cómo $iceberg infiere el esquema de la tabla. Debe ser un documento que contenga el campo mode con uno de los siguientes valores:

  • "json" hace que Atlas Stream Processing guarde los campos object y array como columnas de string JSON.

  • "nested" provoca que Atlas Stream Processing guarde object campos como struct columnas y array campos como list columnas.

Se establece por defecto en "json". Para aprender más, consulte Conversión de tipos.

El documento catalog acepta los siguientes campos:

Campo
Tipo
Necesidad
Descripción

type

string

Opcional

Tipo de catálogo de Apache Iceberg que se utilizará. Debe ser uno de los siguientes valores:

  • "hadoop" para catálogos de datos en Amazon Web Services y Azure

  • "glue" para catálogos de datos en Amazon Web Services

  • "unity" para catálogos de Unity de Databricks en Amazon Web Services y Azure

  • "horizon" para catálogos de Snowflake Horizon en Amazon Web Services y Azure

connectionName

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 type es "unity" o "horizon".

Atlas Stream Processing rechaza este campo si type es "hadoop" o "glue".

warehouse

string

Condicional

Ubicación en el catálogo que contiene el esquema de destino.

Obligatorio si type es "unity" o "horizon".

Atlas Stream Processing rechaza este campo si type es "hadoop" o "glue".

  • Para "unity", el nombre del catálogo de Databricks.

  • Para "horizon", el nombre de la base de datos de Snowflake.

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

"unity"

Databricks catalog

Esquema de Databricks

Nombre de la tabla

"horizon"

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.

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.

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

string

string

int

int

long

long

double

double

bool

boolean

ObjectId

string

Codificado en hexadecimal

UUID

string

UUID en cadena

BinData

binary

No se aplica a UUID

date

timestamptz

Hora UTC, medida en microsegundos

timestamp

timestamptz

Hora UTC, medida en microsegundos

object

string or struct

Serializado como un JSON básico string por defecto. En moda nested, se convierte en una columna struct. Para obtener más información, consulte Campos de objeto y arreglo.

array

string or list

Serializado como un JSON básico string por defecto. En moda nested, se convierte en una columna list. Para obtener más información, consulte Campos de objeto y arreglo.

No se admiten otros BSON types. Atlas Stream Processing envía documentos con BSON types no admitidos a la DLQ.

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 campos object y array como cadenas JSON básicas y los guarda en las columnas string. json es la moda por defecto.

  • En moda nested, Atlas Stream Processing infiere tipos anidados de Iceberg a partir de los campos object y array:

    • Cada campo object se convierte en una columna struct. 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 array se convierte en una columna list. 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 un struct que 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 struct o un list, 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.

Los siguientes ejemplos ilustran varias aplicaciones de la etapa $iceberg.

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:

  1. La etapa $source establece una conexión con la base de datos de Atlas, específicamente dirigida a la colección orders en la base de datos db. 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.

  2. La etapa $iceberg establece una conexión con el cubo AWS S3, escribiendo en una tabla llamada myTable en la ruta iceberg-warehouse/. Al especificar solo insert operaciones, 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" }}

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:

  1. La etapa $source establece una conexión con la base de datos de Atlas, específicamente dirigida a la colección orders en la base de datos db. 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.

  2. La etapa $match filtra en operationType para que solo se procesen los documentos con declaraciones de tipo de operación válidas.

  3. La etapa $replaceRoot cambia 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.

  4. La etapa $iceberg establece una conexión con el bucket de AWS S3, escribiendo en una tabla Apache Iceberg llamada myTable en la ruta iceberg-warehouse/. En la moda cdc, esta etapa determina la operación que se va a realizar en la tabla Apache Iceberg mediante la lectura del campo de metadatos stream.source.operationType de 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" }}

En el siguiente ejemplo, Atlas Stream Processing utiliza expresiones dinámicas para enrutar dinámicamente documentos a varios destinos de salida.

  1. La etapa $source establece una conexión con la base de datos de Atlas, específicamente dirigida a las colecciones a, b y c en la base de datos db. 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.

  2. La etapa $match filtra los documentos cuyo operationType es uno de "insert", "update", "delete" o "replace".

  3. La etapa $replaceRoot cambia 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.

  4. La etapa $iceberg establece una conexión con el cubo Amazon Web Services S3 denominado myData, escribiendo en una tabla Apache Iceberg en la ruta iceberg-warehouse/. Determina el nombre de la tabla según el nombre de la fuente collection recuperado 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" }}

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:

  1. La etapa $source establece una conexión con la base de datos de Atlas, específicamente dirigida a la colección orders en la base de datos db. 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.

  2. La etapa $iceberg guarda en el bucket de Amazon Web Services S3 llamado myData a través de la conexión myS3Connection. Utiliza una conexión de catálogo de datos para guardar en la tabla orders del 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" } } }]