Overview
En esta guía, puedes aprender cómo aplicar esquemas a documentos entrantes en un conector de origen de MongoDB Kafka.
Hay dos tipos de esquemas en Kafka Connect, esquema clave y esquema de valor. Kafka Connect envía mensajes a Apache Kafka que contienen tanto tu valor como una clave. Un esquema de clave aplica una estructura para las claves en los mensajes enviados a Apache Kafka. Un esquema de valores aplica una estructura a los valores en los mensajes enviados a Apache Kafka.
Importante
Nota sobre terminología
Esta guía utiliza la definición de Apache Kafka de la palabra "clave", que difiere ligeramente de la definición de BSON. En BSON, una "clave" es un identificador único de string para un campo en un documento.
En Apache Kafka, una "clave" es un arreglo de bytes enviada en un mensaje que se utiliza para determinar a qué partición de un tema guardar el mensaje. Las claves de Kafka pueden ser duplicados de otras claves o null.
Es opcional especificar esquemas en el conector, y puedes especificar cualquiera de las siguientes combinaciones de esquemas:
Solo un esquema de valor
Solo un esquema clave
Tanto un valor como un esquema de clave
No schemas
Tip
Beneficios de esquema
Para ver una discusión sobre los beneficios de usar esquemas con Kafka Connect, consulte este artículo de Confluent.
Si deseas enviar datos a través de Apache Kafka con un formato de datos específico, como Apache Avro o JSON Schema, consulta el Converters guía.
Para obtener más información sobre las claves y valores en Apache Kafka, consulta la introducción oficial de Apache Kafka.
Default Schemas
El conector proporciona dos esquemas por defecto:
Un esquema clave para el campo _id de los documentos de eventos de cambio de MongoDB.
Un esquema de valor para documentos de eventos de cambio de MongoDB.
Para aprender más sobre los eventos de cambio, consulta nuestra guía sobre flujos de cambios.
Para obtener más información sobre los esquemas por defecto, consulta los esquemas por defecto aquí en el código fuente del Conector MongoDB para Kafka.
Esquema de Clave
El conector proporciona un esquema de clave por defecto para el campo _id de los documentos de eventos de cambio. Se debe usar el esquema de clave por defecto a menos que se remueva el campo _id del documento de evento de cambio utilizando cualquiera de las transformaciones descritas en esta guía aquí.
Si especificas cualquiera de estas transformaciones y deseas utilizar un esquema de claves para tus documentos entrantes, debes especificar un esquema de claves como se describe en la sección "Especificar un esquema" de esta guía.
Puedes habilitar el esquema de clave por defecto con la siguiente opción:
output.format.key=schema
Esquema de valor
El conector proporciona un esquema de valor predeterminado para los documentos de eventos de cambio. Debe usar el esquema de valor por defecto a menos que transforme sus documentos de eventos de cambio como se describe en esta guía aquí.
Si especificas alguna de estas transformaciones y quieres utilizar un esquema de valores para tus documentos entrantes, debes usar uno de los mecanismos descritos en la sección de esquemas para documentos transformados de esta guía.
Puedes habilitar el esquema de valor por defecto con la siguiente opción:
output.format.value=schema
Esquemas para documentos transformados
Hay dos formas de transformar los documentos de eventos de cambio en un conector de origen:
La opción
publish.full.document.only=trueUn pipeline de agregación que modifica la estructura de los documentos de eventos de cambio
Si transformas tus documentos de eventos de cambio de MongoDB, debes realizar lo siguiente para aplicar esquemas:
Para obtener más información sobre las opciones de configuración anteriores, consulta la página Cambiar propiedades del flujo.
Especificar esquemas
Puedes especificar esquemas para documentos entrantes usando la sintaxis de esquema Avro. Haz clic en las siguientes pestañas para ver cómo especificar un esquema para los valores y claves de documentos:
output.format.key=schema output.schema.key=<your avro schema>
output.format.value=schema output.schema.value=<your avro schema>
Para ver un ejemplo que demuestra cómo especificar un esquema, consulta el ejemplo de uso de Especificar un Esquema.
Para obtener más información sobre Avro Schema, consulta la guía Formatos de datos.
Importante
Conversores
Si desea enviar sus datos a través de Apache Kafka con codificación binaria Avro, debe utilizar un convertidor Avro. Para obtener más información, consulta la guía sobre Conversores.
Inferir un esquema
Puede hacer que su conector de origen infiera un esquema para los documentos entrantes. Esta opción funciona bien para el desarrollo y para fuentes de datos que no cambian frecuentemente de estructura, pero para la mayoría de las implementaciones en producción recomendamos que se especifique un esquema.
El conector puede inferir un esquema especificando las siguientes opciones:
output.format.value=schema output.schema.infer.value=true
El conector de origen puede inferir esquemas para documentos entrantes que contienen documentos anidados almacenados en arreglos. A partir de la versión 1.9 del conector, la inferencia de esquemas recopilará el tipo de datos apropiado para los campos en lugar de asignar por defecto un tipo de string si existen diferencias entre los documentos anidados descritos por los siguientes casos:
Un campo está presente en un documento pero falta en otro.
Un campo está presente en un documento, pero
nullen otro.Un campo es un arreglo con elementos de cualquier tipo en un documento, pero tiene elementos adicionales o elementos de otros tipos de datos en otro.
Un campo es un arreglo con elementos de cualquier tipo en un documento, pero un arreglo vacío en otro.
Si los tipos de campo entran en conflicto entre documentos anidados, el conector lleva el conflicto al esquema del campo y, por defecto, asigna un tipo string.
Nota
No se puede inferir el esquema clave
El conector no soporta la inferencia del esquema de claves. Si deseas utilizar un esquema de clave y transformar tus documentos de eventos de cambios en MongoDB, debes especificar un esquema de clave como se describe en la sección de especificar esquemas de esta guía.