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 la 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
Sólo un esquema clave
Tanto un valor como un esquema de clave
No schemas
Tip
Beneficios del 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 Guíade convertidores.
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 obtener más información sobre los eventos de cambio, consulte nuestra guía sobre flujos de cambio.
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 predeterminado para el _id campo de los documentos de eventos de cambio. Debe usar el esquema de clave predeterminado a menos que elimine el _id campo de su documento de eventos de cambio mediante alguna de las transformaciones descritas en esta guía.
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 valores
El conector proporciona un esquema de valores predeterminado para los documentos de eventos de cambio. Debe usar este esquema a menos que transforme sus documentos de eventos de cambio como se describe en esta guía.
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 usar un conversor Avro. Para más información, consulte 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 una matriz con elementos de cualquier tipo en un documento pero que 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 campos entran en conflicto entre documentos anidados, el conector envía el conflicto al esquema del campo y, de manera predeterminada, establece una asignación de 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.