Definición
La etapa $source especifica una conexión en el Registro de Conexiones desde la cual transmitir datos. Se admiten los siguientes tipos de conexión:
Apache Kafka broker
flujo de cambios de colección de MongoDB
Flujo de cambios de la base de datos MongoDB
Flujo de cambios del clúster de MongoDB
AWS Kinesis flujo de datos
Arreglo de documentos
Cronograma de Cron
Sintaxis
Apache Kafka Broker
Para operar con datos en transmisión de un broker de Apache Kafka, la etapa $source tiene la siguiente forma de prototipo:
{ "$source": { "connectionName": "<registered-connection>", "topic" : ["<source-topic>", ...], "timeField": { $toDate | $dateFromString: <expression> }, "partitionIdleTimeout": { "size": <duration-number>, "unit": "<duration-unit>" }, "partitions": { "min": <partition-id>, "max": <partition-id> }, "schemaRegistry": { "connectionName": "<schema-registry-name>", }, "config": { "auto_offset_reset": "<start-event>", "group_id": "<group-id>", "keyFormat": "<deserialization-type>", "keyFormatError": "<error-handling>" }, }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Requerido | Etiqueta que identifica la conexión en el Registro de conexiones, para ingerir datos de esta. |
| string o arreglo de strings | Requerido | Nombre de uno o más temas de Apache Kafka de los que transmitir mensajes. Si desea transmitir mensajes de más de un tema, especifíquelos en un arreglo. |
| Documento | Opcional | Documento que define una marca de tiempo autorizada para los mensajes entrantes. Si utilizas
Si no declaras un |
| Documento | Opcional | Documento especificando la cantidad de tiempo que se permite que una partición esté inactiva antes de que se ignore en los cálculos de marcas de agua. Este campo está desactivado por defecto. Para gestionar las particiones que no avanzan debido a la inactividad, establece un valor para este campo. |
| entero | Opcional | Número que especifica la duración del tiempo de espera de inactividad de la partición. |
| string | Opcional | Unidad de tiempo para la duración del tiempo de espera por inactividad de la partición. El valor de
|
| Documento | Opcional | Documento que especifica un rango inclusivo de ID de partición desde los que lee el procesador de flujo. Atlas Stream Processing solo lee de las particiones del tema de origen cuyos ID se encuentran dentro de este rango. Si especifica más de un tema, Atlas Stream Processing aplica el rango a las particiones de cada tema. Si omite este campo, Atlas Stream Processing lee de todas las particiones del tema de origen. |
| entero | Condicional | ID de partición más bajo en el rango. Debe ser |
| entero | Opcional | ID de partición más alto en el rango. Debe ser mayor o igual a Si omite este campo, Atlas Stream Processing lee de todas las particiones con un ID mayor o igual a |
| Documento | Opcional | Documento que habilita el uso de un Registro de esquemas para apoyar la lectura desde una fuente serializada en Avro. Para habilitar esta funcionalidad, debe crear una conexión con el Registro de esquemas. |
| string | Condicional | Nombre de la conexión del Registro de esquemas que se utilizará para la deserialización de Avro. |
| Documento | Opcional | Documento que contiene campos que sobrescriben diversos valores por defecto. |
| string | Opcional | Especifica con qué evento del tema fuente Apache Kafka se iniciará la ingestión.
Se establece por defecto en Si un procesador de flujo con una fuente de Apache Kafka se inicia sin un punto de control, se reanuda desde los desplazamientos confirmados de su grupo de consumidores. |
| string | Opcional | ID del grupo de consumidores de Kafka para asociar con el procesador de flujo. Si se omite, Atlas Stream Processing asocia el espacio de trabajo de Stream Processing con una ID generada automáticamente en el siguiente formato: Atlas Stream Processing genera automáticamente un valor para este parámetro en todos los procesadores de flujos persistentes. Para los procesadores de flujo efímeros definidos con sp.process(), este parámetro solo se configura si lo define manualmente. |
| booleano | Condicional | Indicador que determina la política de confirmaciones para los desfases de partición de los intermediarios de Kafka. Atlas Stream Processing admite dos políticas de confirmación:
Para un procesador de flujos efímero definido con sp.process(), este parámetro se asigna por defecto a Para obtener más información sobre los offsets cuando se utiliza Kafka como |
| string | Opcional | Tipo de dato usado para deserializar los datos de claves de Apache Kafka. Debe ser uno de los siguientes valores:
Se establece por defecto en |
| string | Opcional | Cómo gestionar los errores encontrados al deserializar los datos clave de Apache Kafka. Debe ser uno de los siguientes valores:
|
Nota
Atlas Stream Processing requiere que los documentos en el flujo de datos de origen sean válidos json o ejson. Atlas Stream Processing establece que los documentos que no cumplen este requisito se asignen a tu fila de letra muerta si has configurado una.
MongoDB colección Change Stream
Un flujo de cambios de la colección de Atlas permite que las aplicaciones accedan a los cambios de datos en tiempo real en una sola colección. Para aprender a abrir un flujo de cambios en una colección, consulta Change Streams.
Al usar un flujo de cambios $source, configura el clúster de origen con una oplog window de al menos 24 horas.
Para leer el flujo de cambios, Atlas Stream Processing escanea la colección oplog. Como resultado, es posible que veas COLLSCAN advertencias en tus registros. Estas advertencias indican un comportamiento normal y no señalan un error.
Si configuras config.fullDocument o config.fullDocumentBeforeChange en required, activa changeStreamPreAndPostImages en cada colección antes de cualquier operación de guardado que desees capturar. Si una postimagen no está disponible para un evento porque no se habilitó la funcionalidad cuando ocurrió el guardado, o porque la postimagen ha caducado, el procesador de flujos falla. Para obtener instrucciones sobre cómo habilitar las preimágenes y las postimágenes, consulta Change Streams con pre/postimágenes de documentos.
Importante
Puedes reanudar un flujo de cambios solo mientras la colección oplog todavía contenga la operación que identifica su token de reanudación. Para asegurarse de que su aplicación pueda reanudar sus change streams, configure una oplog window mínima más larga que la interrupción más larga que espera.
Para operar sobre datos en transmisión de un flujo de cambios de una colección de Atlas, la etapa $source tiene la siguiente forma prototipo:
{ "$source": { "connectionName": "<registered-connection>", "timeField": { $toDate | $dateFromString: <expression> }, "db" : "<source-db>", "coll" : ["<source-coll>",...], "initialSync": { "enable": <boolean>, "parallelism": <integer> }, "readPreference": "<read-preference>", "readPreferenceTags": [ {"<key>": "<value>"}, . . . ], "config": { "startAfter": <start-token> | "startAtOperationTime": <timestamp>, "fullDocument": "<full-doc-condition>", "fullDocumentOnly": <boolean>, "fullDocumentBeforeChange": "<before-change-condition>", "pipeline": [{ "<aggregation-stage>" : { <stage-input>, . . . }, . . . }], "maxAwaitTimeMS": <time-ms>, } }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Condicional | Etiqueta que identifica la conexión en el Registro de conexiones, para ingerir datos de esta. |
| Documento | Opcional | Documento que define una marca de tiempo autorizada para los mensajes entrantes. Si utilizas
Si no declaras un |
| string | Requerido | Nombre de la base de datos MongoDB alojada en la instancia de Atlas especificada por |
| string o arreglo de strings | Requerido | Nombre de una o más colecciones de MongoDB alojadas en la instancia de Atlas especificada por |
| Documento | Opcional | Documento que contiene Atlas Stream Processing Si Atlas Stream Processing fija el conjunto de colecciones a sincronizar cuando se inicia el procesador de transmisiones. No sincroniza las colecciones que cree después de ese punto, y si falla la sincronización de una colección, falla todo el procesador de transmisiones. Si habilitas IMPORTANTE: Consulte Limitaciones para conocer las consideraciones y restricciones de |
| booleano | Condicional | Determina si se debe habilitar |
| entero | Opcional | Determina el nivel de paralelismo con el que se procesará la operación Si
El valor máximo que puede establecer depende del nivel de su procesador de transmisión. Para obtener más información, consulte Guía de selección de nivel de Atlas Stream Processing. Cada procesador de flujo tiene un valor máximo de paralelismo acumulado determinado por su nivel. El paralelismo acumulativo de un procesador de flujo se calcula de la siguiente manera:
Donde Por ejemplo, si tu etapa Si un procesador de flujo supera el paralelismo acumulativo máximo para su nivel, Atlas Stream Processing genera un error e informa del nivel mínimo de procesador requerido para el nivel de paralelismo previsto. Debe escalar el procesador a un nivel superior o reducir los valores de paralelismo de sus etapas para resolver el error. Para aprender más, consulte Procesamiento de flujos. |
| string | Opcional | Preferencia de lectura para flujo de cambios y Se establece por defecto en |
| arreglo | Opcional | Leer etiquetas de preferencia de lectura para el flujo de cambios y las operaciones |
| Documento | Opcional | Documento que contiene campos que sobrescriben diversos valores por defecto. |
| token | Condicional | El evento de cambio después del cual la fuente comienza a reporte. Esto toma la forma de un token de currículum. Puedes utilizar solo uno de |
| timestamp | fecha | Condicional | El operation time después del cual la fuente debe comenzar a reportar. Puedes utilizar solo uno de Acepta valores MongoDB Extended JSON |
| string | Condicional | Configuración que controla si una fuente de flujo de cambios debe devolver un documento completo o sólo las modificaciones cuando se produce una actualización. Debe ser uno de los siguientes:
Para utilizar |
| booleano | Condicional | Configuración que controla si una fuente de flujos de cambios devuelve todo el documento del evento de cambio, incluyendo todos los metadatos, o solo el contenido de Si |
| string | Opcional | Especifica si una fuente de flujo de cambios debe incluir el documento completo en su estado original "antes de los cambios" en la salida. Debe ser uno de los siguientes:
Si no se especifica un valor para Para utilizar este campo con una colección de flujo de cambios, debe habilitar la Preimágenes y Postimágenes de flujo de cambios en esa colección. |
| Documento | Opcional | Especifica un pipeline de agregación para filtrar la salida del flujo de cambios antes de pasarla para procesamiento adicional. Este pipeline debe respetar los parámetros que se describen en Modifica la salida del change stream. IMPORTANTE: Cada evento de cambio incluye los campos |
| entero | Opcional | Tiempo máximo, en milisegundos, para esperar a que se reporten nuevos cambios de datos al cursor del flujo de cambios antes de devolver un lote vacío. Se establece por defecto en |
Flujo de cambios del Base de datos MongoDB
Un flujo de cambios de base de datos de Atlas permite que las aplicaciones accedan a cambios de datos en tiempo real en una única base de datos. Para aprender a abrir un flujo de cambios en una base de datos, consulta Change Streams.
Al usar un flujo de cambios $source, configura el clúster de origen con una oplog window de al menos 24 horas.
Para leer el flujo de cambios, Atlas Stream Processing escanea la colección oplog. Como resultado, es posible que veas COLLSCAN advertencias en tus registros. Estas advertencias indican un comportamiento normal y no señalan un error.
Si configuras config.fullDocument o config.fullDocumentBeforeChange en required, activa changeStreamPreAndPostImages en cada colección antes de cualquier operación de guardado que desees capturar. Si una postimagen no está disponible para un evento porque no se habilitó la funcionalidad cuando ocurrió el guardado, o porque la postimagen ha caducado, el procesador de flujos falla. Para obtener instrucciones sobre cómo habilitar las preimágenes y las postimágenes, consulta Change Streams con pre/postimágenes de documentos.
Importante
Puedes reanudar un flujo de cambios solo mientras la colección oplog todavía contenga la operación que identifica su token de reanudación. Para asegurarse de que su aplicación pueda reanudar sus change streams, configure una oplog window mínima más larga que la interrupción más larga que espera.
Para operar sobre datos en transmisión de un flujo de cambios de la base de datos Atlas, la etapa $source tiene la siguiente forma de prototipo:
{ "$source": { "connectionName": "<registered-connection>", "timeField": { $toDate | $dateFromString: <expression> }, "db" : "<source-db>", "readPreference": "<read-preference>", "readPreferenceTags": [ {"<key>": "<value>"}, . . . ], "config": { "startAfter": <start-token> | "startAtOperationTime": <timestamp>, "fullDocument": "<full-doc-condition>", "fullDocumentOnly": <boolean>, "fullDocumentBeforeChange": "<before-change-condition>", "pipeline": [{ "<aggregation-stage>" : { <stage-input>, . . . }, . . . }] }, }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Condicional | Etiqueta que identifica la conexión en el Registro de conexiones, para ingerir datos de esta. |
| Documento | Opcional | Documento que define una marca de tiempo autorizada para los mensajes entrantes. Si utilizas
Si no declaras un |
| string | Requerido | Nombre de la base de datos MongoDB alojada en la instancia de Atlas especificada por |
| string | Opcional | preferencia de lectura para operaciones de flujo de cambios. Se establece por defecto en |
| arreglo | Opcional | Lea las etiquetas de preferencia de lectura para las operaciones de flujo de cambios. |
| Documento | Opcional | Documento que contiene campos que sobrescriben diversos valores por defecto. |
| token | Condicional | El evento de cambio después del cual la fuente comienza a reporte. Esto toma la forma de un token de currículum. Puedes utilizar solo uno de |
| timestamp | fecha | Condicional | El operation time después del cual la fuente debe comenzar a reportar. Puedes utilizar solo uno de Acepta valores MongoDB Extended JSON |
| string | Condicional | Configuración que controla si una fuente de flujo de cambios debe devolver un documento completo o sólo las modificaciones cuando se produce una actualización. Debe ser uno de los siguientes:
Si no se especifica un valor para Para usar |
| booleano | Condicional | Configuración que controla si una fuente de flujos de cambios devuelve todo el documento del evento de cambio, incluyendo todos los metadatos, o solo el contenido de Si |
| string | Opcional | Especifica si una fuente de flujo de cambios debe incluir el documento completo en su estado original "antes de los cambios" en la salida. Debe ser uno de los siguientes:
Si no se especifica un valor para Para usar este campo con un flujo de cambios de base de datos, debes habilitar imágenes anteriores y posteriores en cada colección de esa base de datos. |
| Documento | Opcional | Especifica un pipeline de agregación para filtrar la salida del flujo de cambios en el punto de origen. Esta pipeline debe ajustarse a los parámetros descritos en Modificar la salida del flujo de cambios. IMPORTANTE: Cada evento de cambio incluye los campos |
| entero | Opcional | Tiempo máximo, en milisegundos, para esperar a que se reporten nuevos cambios de datos al cursor del flujo de cambios antes de devolver un lote vacío. Se establece por defecto en |
Fuente de flujo de cambios en clúster de MongoDB
Al usar un flujo de cambios $source, configura el clúster de origen con una oplog window de al menos 24 horas.
Para leer el flujo de cambios, Atlas Stream Processing escanea la colección oplog. Como resultado, es posible que veas COLLSCAN advertencias en tus registros. Estas advertencias indican un comportamiento normal y no señalan un error.
Si configuras config.fullDocument o config.fullDocumentBeforeChange en required, activa changeStreamPreAndPostImages en cada colección antes de cualquier operación de guardado que desees capturar. Si una postimagen no está disponible para un evento porque no se habilitó la funcionalidad cuando ocurrió el guardado, o porque la postimagen ha caducado, el procesador de flujos falla. Para obtener instrucciones sobre cómo habilitar las preimágenes y las postimágenes, consulta Change Streams con pre/postimágenes de documentos.
Importante
Puedes reanudar un flujo de cambios solo mientras la colección oplog todavía contenga la operación que identifica su token de reanudación. Para asegurarse de que su aplicación pueda reanudar sus change streams, configure una oplog window mínima más larga que la interrupción más larga que espera.
Para operar datos de transmisión de todo un flujo de cambio del clúster Atlas, la etapa $source tiene la siguiente forma prototipo:
{ "$source": { "connectionName": "<registered-connection>", "timeField": { $toDate | $dateFromString: <expression> }, "readPreference": "<read-preference>", "readPreferenceTags": [ {"<key>": "<value>"}, . . . ], "config": { "startAfter": <start-token> | "startAtOperationTime": <timestamp>, "fullDocument": "<full-doc-condition>", "fullDocumentOnly": <boolean>, "fullDocumentBeforeChange": "<before-change-condition>", "pipeline": [{ "<aggregation-stage>" : { <stage-input>, . . . }, . . . }] }, }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Condicional | Etiqueta que identifica la conexión en el Registro de conexiones, para ingerir datos de esta. |
| Documento | Opcional | Documento que define una marca de tiempo autorizada para los mensajes entrantes. Si utilizas
Si no declaras un |
| string | Opcional | preferencia de lectura para operaciones de flujo de cambios. Se establece por defecto en |
| arreglo | Opcional | Lea las etiquetas de preferencia de lectura para las operaciones de flujo de cambios. |
| Documento | Opcional | Documento que contiene campos que sobrescriben diversos valores por defecto. |
| token | Condicional | El evento de cambio después del cual la fuente comienza a reporte. Esto toma la forma de un token de currículum. Puedes utilizar solo uno de |
| fecha | marca temporal | Condicional | El operation time después del cual la fuente debe comenzar a reportar. Puedes utilizar solo uno de Acepta valores MongoDB Extended JSON |
| string | Condicional | Configuración que controla si una fuente de flujo de cambios debe devolver un documento completo o sólo las modificaciones cuando se produce una actualización. Debe ser uno de los siguientes:
Si no se especifica un valor para Para usar |
| booleano | Condicional | Configuración que controla si una fuente de flujos de cambios devuelve todo el documento del evento de cambio, incluyendo todos los metadatos, o solo el contenido de Si |
| string | Opcional | Especifica si una fuente de flujo de cambios debe incluir el documento completo en su estado original "antes de los cambios" en la salida. Debe ser uno de los siguientes:
Si no se especifica un valor para Para usar este campo con un flujo de cambios de base de datos, debes habilitar imágenes anteriores y posteriores en cada colección de esa base de datos. |
| Documento | Opcional | Especifica un pipeline de agregación para filtrar la salida del flujo de cambios en el punto de origen. Esta pipeline debe ajustarse a los parámetros descritos en Modificar la salida del flujo de cambios. Ten en cuenta que el Atlas Stream Processing espera recibir los campos |
| entero | Opcional | Tiempo máximo, en milisegundos, para esperar a que se reporten nuevos cambios de datos al cursor del flujo de cambios antes de devolver un lote vacío. Se establece por defecto en |
AWS Kinesis Data Stream
Atlas Stream Processing admite la creación de conexiones Private Link con flujos AWS Kinesis. Para obtener más información, consulte Agregar una conexión privada de Kinesis.
Para operar con datos de un AWS flujo de datos de Kinesis, la etapa $source tiene el siguiente formulario prototipo:
{ "$source": { "connectionName": "<registered-connection>", "stream": "<stream-name>", "region": "<aws-region>", "timeField": { $toDate | $dateFromString: <expression> }, "tsFieldName": "<field-name>", "shardIdleTimeout": { "size": <duration-number>, "unit": "<duration-unit>" }, "config": { "consumerARN": "<aws-arn>", "initialPosition": <initial-position>, reshardDetectionIntervalSecs: <interval> } }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Requerido | Etiqueta que identifica la conexión en el Registro de Conexiones, de la cual se obtiene la información. |
| string | Requerido | ARN correspondiente a un consumidor de Kinesis. Su consumidor debe usar Fan-out mejorado. |
| string | Requerido | Flujo de datos de AWS Kinesis desde el cual transmitir mensajes. |
| string | Condicional | Región AWS en la que existe el flujo especificado. Kinesis admite varios flujos de datos con el mismo nombre en diferentes regiones. Si se usa el mismo nombre para los flujos de datos en dos o más regiones dentro de la misma conexión, se debe usar este campo para especificar qué combinación de nombre y región usar. |
| Documento | Opcional | Documento que define una marca de tiempo autorizada para los mensajes entrantes. Si utilizas
Si no declaras un |
| string | Opcional | Nombre del campo para la marca de tiempo en el documento proyectado. Utiliza este campo para anular el nombre de campo de la marca de tiempo por defecto. |
| Documento | Opcional | Documento que especifica el tiempo que se permite que una partición esté inactiva antes de que se ignore en los cálculos de marcas de agua. Este campo está desactivado por defecto. Para gestionar las particiones que no avanzan debido a la inactividad, establece un valor para este campo. |
| Documento | Opcional | Número que especifica la duración del tiempo de espera de inactividad de la partición. |
| Documento | Opcional | Unidad de tiempo para la duración del tiempo de espera inactivo de la partición. El valor de
|
| Documento | Opcional | Documento que contiene campos que sobrescriben diversos valores por defecto. |
| string | Opcional | Posición en el historial de la transmisión de datos de Kinesis desde la cual se comenzará a ingresar mensajes. Debe ser uno de los siguientes:
Se establece por defecto en |
| fecha | Condicional | La marca de tiempo desde la que comenzar a recibir mensajes. Requerido cuando |
| entero | Opcional | Intervalo, en segundos, entre chequeos de la velocidad del flujo de datos a través de tu flujo de Kinesis para fines de rebalanceo. Por defecto son |
arreglo de documentos
Para operar sobre un arreglo de documentos, la etapa $source tiene el siguiente formato prototipo:
{ "$source": { "timeField": { $toDate | $dateFromString: <expression> }, "documents" : [{source-doc},...] | <expression> }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| Documento | Opcional | Documento que define una marca de tiempo autorizada para los mensajes entrantes. Si utilizas
Si no declaras un |
| arreglo | Condicional | Arreglo de documentos para usar como fuente de datos en streaming. El valor de este campo puede ser un arreglo de objetos o una expresión que se evalúe como un arreglo de objetos. No utilice este campo cuando use el campo |
Cron cronograma
Para generar un documento en un cronograma recurrente en lugar de leer de una conexión, la etapa $source tiene la siguiente forma de prototipo:
{ "$source": { "schedule": "<cron-expression>", "tsFieldName": "<timestamp-field-name>" }}La etapa $source procesa un documento con los siguientes campos:
Campo | Tipo | Necesidad | Descripción |
|---|---|---|---|
| string | Requerido | Expresión cron de seis campos que determina cuándo la etapa emite un documento. Los campos son, en orden: segundo, minuto, hora, día del mes, mes y día de la semana. Atlas Stream Processing evalúa la expresión en UTC. Cada campo acepta Para aprender sobre cómo Atlas Stream Processing resuelve una expresión que restringe tanto el día del mes como el día de la semana, consulte Comportamiento. |
| string | Opcional | Nombre del campo en el que la etapa realiza el Proyecto de la marca de tiempo programada. Se establece por defecto en |
Comportamiento
$source debe ser la primera etapa de cualquier pipeline en el que aparezca. Solo puedes usar una $source etapa por pipeline.
Para etapas de Kafka $source, Atlas Stream Processing lee en paralelo desde múltiples particiones dentro del tema de origen. El límite de partición lo determina tu nivel de procesador. Para obtener detalles adicionales, revise la referencia de facturación de Stream Processing.
Para las etapas cron $source, cada hora programada produce un único documento vacío que lleva la marca de hora programada. Utilice etapas posteriores en el pipeline para rellenar el documento.
Cuando una expresión schedule restringe tanto el día del mes como el día de la semana, Atlas Stream Processing emite un documento solo en los momentos programados que satisfacen ambos campos. Esto difiere de las implementaciones de cron que emiten un documento cuando coincide cualquiera de los campos.
Si un procesador de flujo con una etapa cron $source se reinicia, emite un documento para cada hora programada que omitió mientras no estaba en ejecución. No emite documentos para las horas programadas que omitió después de que lo detuviera.
Un procesador de flujo con una etapa cron $source se ejecuta continuamente entre los tiempos programados, y Atlas lo factura en su nivel de procesador durante todo ese período. Un cronograma poco frecuente no reduce el costo de ejecutar el procesador. Para aprender más, consulte la referencia de facturación de Stream Processing.
Ejemplos
Ejemplo de Kafka
Una fuente de datos de transmisión genera informes meteorológicos detallados desde varias ubicaciones, cumpliendo con el esquema del Conjunto de Datos Meteorológicos de Muestra. La siguiente agregación tiene tres etapas:
La etapa
$sourceestablece una conexión con el broker Apache Kafka recogiendo estos informes en un tema llamadomy_weatherdata, exponiendo cada registro a medida que se ingiere a las siguientes etapas de agregación. Esta etapa también anula el nombre del campo de marca de hora que proyecta y lo pone eningestionTime.La etapa
$matchexcluye los documentos que tienen undewPoint.valuemenor o igual a5.0y pasa los documentos condewPoint.valuemayor que5.0a la siguiente etapa.La fase
$mergeescribe la salida en una colección Atlas denominadastreamen la base de datossample_weatherstream. Si no existe tal base de datos o colección, Atlas los creará.
[{ "$source": { "connectionName": "sample_weatherdata", "topic": "my_weatherdata" }},{ "$match": { "dewPoint.value": { "$gt": 5 } }},{ "$merge": { "into": { "connectionName": "weatherStreamOutput", "db": "sample_weatherstream", "coll": "stream" } }}]Para ver los documentos de la colección sample_weatherstream.stream resultante, conéctate a un clúster de Atlas y ejecuta el siguiente comando:
db.getSiblingDB("sample_weatherstream").stream.find()Nota
Lo anterior es un ejemplo representativo. Los datos en transmisión no son estáticos, y cada usuario ve documentos distintos.
Ejemplo de flujo de cambios
La siguiente agregación ingiere datos de la fuente cluster0-collection, que se conecta a un clúster de Atlas cargado con el conjunto de datos de muestra. Para aprender cómo crear un espacio de trabajo de Stream Processing y agregar una conexión a un clúster de Atlas al registro de conexión, consulte Introducción a Atlas Stream Processing. Esta agregación ejecuta dos etapas para abrir un flujo de cambios y registrar los cambios en la colección data de la base de datos sample_weatherdata:
La etapa
$sourcese conecta a la fuentecluster0-collectiony abre un flujo de cambios en la coleccióndatade la base de datossample_weatherdata.La etapa
$mergeescribe los documentos de flujo de cambios filtrados en una colección de Atlas denominadadata_changesen la base de datossample_weatherdata. Si no existe tal colección, Atlas la crea.
[{ "$source": { "connectionName": "cluster0-connection", "db": "sample_weatherdata", "coll": "data" }},{ "$merge": { "into": { "connectionName": "cluster0-connection", "db": "sample_weatherdata", "coll": "data_changes" } }}]El siguiente comando mongosh borra un documento data:
db.getSiblingDB("sample_weatherdata").data.deleteOne( { _id: ObjectId("5553a99ae4b02cf715120e4b") })Después de que el documento data sea eliminado, el procesador de flujo registra el documento de evento del flujo de cambios en la colección sample_weatherdata.data_changes. Para ver los documentos en la colección resultante de sample_weatherdata.data_changes, usa mongosh para conectarte a tu clúster de Atlas y ejecutar el siguiente comando:
db.getSiblingDB("sample_weatherdata").data_changes.find()Ejemplo de flujo de cambios de base de datos
La siguiente agregación ingiere datos de la fuente db-change-stream-connection, que se conecta a un clúster de Atlas cargado con el conjunto de datos colección del conjunto de datos Mflix de muestra. Para aprender cómo crear un espacio de trabajo de Stream Processing y agregar una conexión a un clúster de Atlas al registro de conexión, consulte Introducción a Atlas Stream Processing. Esta agregación ejecuta dos etapas para abrir un flujo de cambios en la base de datos de origen sample_mflix y registro los cambios en la colección db_changes de la base de datos de destino sample_mflix_changes:
La etapa
$sourcese conecta al origendb-change-stream-connectiony abre un flujo de cambios en la base de datos de origensample_mflix. El campoconfig.startAtOperationTimeestablece el tiempo después del cual la fuente comienza el reporte. Este ejemplo establece el valorstartAtpara que comience un minuto en el pasado.La etapa
$mergeguarda los documentos del flujo de cambios en una colección de Atlas llamadadb_changesen la base de datos receptorasample_mflix_changes.
const startAt = new Date(Date.now() - 60 * 1000);
const pipeline = [ { $source: { connectionName: "db-change-stream-connection", db: "sample_mflix", config: { startAtOperationTime: startAt } } }, { $merge: { into: { connectionName: "db-change-stream-connection", db: "sample_mflix_changes", coll: "db_changes" } } }];Ejecute los siguientes comandos en su clúster de origen para verificar el comportamiento del procesador de flujo. Para conectarse, consulte Conectarse a un clúster mediante mongosh.
Inserte un documento en la colección movies y un documento en la colección comments en la base de datos de origen sample_mflix:
db.getSiblingDB("sample_mflix").movies.insertOne({ title: "The Stream Processor", year: 2026})
db.getSiblingDB("sample_mflix").comments.insertOne({ name: "Ada Lovelace", text: "A fine film about data in motion."})Después de insertar los documentos, el procesador de flujo guardar un documento de evento de flujo de cambios para cada inserción en la colección sample_mflix_changes.db_changes. Ejecute el siguiente comando en su clúster para ver los documentos en la colección sample_mflix_changes.db_changes resultante:
db.getSiblingDB("sample_mflix_changes").db_changes.find( {}, { _id: 0, clusterTime: 1, ns: 1, operationType: 1, fullDocument: 1 })Cada evento incluye una marca de tiempo, el cambio completo del documento, un operationType y un campo ns. El campo ns nombra la base de datos y la colección de origen, para que pueda distinguir qué colección produjo cada cambio.
Ejemplo de flujo de cambios en todo el clúster
La siguiente agregación ingiere datos de la fuente cluster-changestream-connection, que se conecta a un clúster de Atlas cargado con el conjunto de datos colecciones de muestra de Mflix Dataset, y guarda en el destino cluster-changestream-sink-connection, que se conecta a un clúster de Atlas independiente. Para aprender cómo crear un espacio de trabajo de Stream Processing y agregar una conexión a un clúster de Atlas al registro de conexión, consulte Introducción a Atlas Stream Processing. Esta agregación ejecuta dos etapas para abrir un flujo de cambios en todo el clúster en el clúster de origen y registrar los cambios en la colección events de la base de datos cluster_changes en el clúster de destino. Esta etapa $source omite db y coll, por lo que informa de los cambios de cada base de datos y colección en el clúster de origen, en lugar de una única colección o base de datos.
La etapa
$sourcese conecta al origencluster-changestream-connectiony abre un flujo de cambios en todo el clúster de origen. El campoconfig.startAtOperationTimeespecifica que el procesador de transmisión debe comenzar con el reporte de los cambios que se produzcan a partir de una hora especificada.La etapa
$mergeescribe los documentos del flujo de cambios en una colección de Atlas llamadaeventsen la base de datoscluster_changesen el clúster de destino. Si no existe tal base de datos o colección, Atlas los crea.
[{ "$source": { "connectionName": "cluster-changestream-connection", "config": { "startAtOperationTime": {"$date": "2024-08-19T18:00:00.000Z"} } }},{ "$merge": { "into": { "connectionName": "cluster-changestream-sink-connection", "db": "cluster_changes", "coll": "events" } }}]El siguiente comando mongosh inserta un documento en la colección movies en la base de datos sample_mflix en el clúster de origen:
db.getSiblingDB("sample_mflix").movies.insertOne( { _id: ObjectId("66c1a1f1f1f1f1f1f1f1f1f1"), title: "Example Movie" })Una vez insertado el documento, el procesador de flujo guarda el documento de evento del flujo de cambios en la colección cluster_changes.events en el clúster de destino.
Para ver los documentos en la colección resultante cluster_changes.events, ejecute los siguientes comandos en su clúster de destino. Para conectarse, consulte Conectarse a un clúster mediante mongosh.
db.getSiblingDB("cluster_changes").events.find()El campo ns en el documento de salida muestra que el cambio se origina en la inserción sample_mflix.movies en el clúster de origen. El pipeline de agregación de flujo de cambios refleja este cambio en la colección cluster_changes.events en el clúster de destino.
Ejemplo de arreglo de documentos
La siguiente agregación utiliza un arreglo de documentos en línea como fuente de datos de transmisión, que contiene observaciones meteorológicas para tres ubicaciones. El arreglo utiliza el mismo esquema que el Conjunto de Datos de muestra de Meteorología. Esta agregación ejecuta tres etapas:
La etapa
$sourcedefine un arreglodocumentsen línea de observaciones meteorológicas como fuente de datos en streaming y utilizatimeFieldpara designar el campotimestampde cada documento como la marca temporal autorizada.La etapa
$matchremite solo los documentos condewPoint.valuemayor que5.0a la siguiente etapa.La fase
$mergeescribe la salida en una colección Atlas denominadastreamen la base de datossample_weatherstream. Si no existe tal base de datos o colección, Atlas los creará.
[{ "$source": { "documents": [ { "location": "New York", "timestamp": ISODate('2024-01-15T08:00:00Z'), "temp": 23.5, "dewPoint": { "value": 6.2 } }, { "location": "Los Angeles", "timestamp": ISODate('2024-01-15T08:05:00Z'), "temp": 18.2, "dewPoint": { "value": 4.8 } }, { "location": "Chicago", "timestamp": ISODate('2024-01-15T08:10:00Z'), "temp": 26.8, "dewPoint": { "value": 7.5 } } ] }},{ "$match": { "dewPoint.value": { "$gt": 5.0 } }},{ "$merge": { "into": { "connectionName": "weatherStreamOutput", "db": "sample_weatherstream", "coll": "stream" } }}]Para ver los documentos de la colección sample_weatherstream.stream resultante, conéctate a un clúster de Atlas y ejecuta el siguiente comando:
db.getSiblingDB("sample_weatherstream").stream.find()Ejemplo de flujo solar
La siguiente agregación filtra informes de la fuente de datos de transmisión de muestra sample_stream_solar. Archiva los resultados en la conexión solar-cluster-connection. Para aprender cómo crear un espacio de trabajo de Stream Processing y agregar una conexión a su espacio de trabajo de Atlas Stream Processing, consulte Introducción a Atlas Stream Processing y Agregar una conexión de Atlas Stream Processing. Esta agregación ejecuta tres etapas para filtrar informes de la fuente sample_stream_solar y guardar los resultados en una colección denominada solarColl en la base de datos solarDb:
La etapa
$sourcese conecta a la fuentesample_stream_solar. El campotimeFieldconvierte el campotimestampde cada informe entrante a una fecha utilizando$dateFromString.La etapa
$matchexcluye los documentos dondedevice_idesdevice_8, y pasa informes de todos los demás dispositivos a la siguiente etapa.La etapa
$mergeguarda la salida en la colecciónsolarCollde la base de datossolarDbdel clústersolar-cluster-connection.
[{ "$source": { "connectionName": "sample_stream_solar", "timeField": { "$dateFromString": { "dateString": "$timestamp" } } }},{ "$match": { "device_id": { "$ne": "device_8" } }},{ "$merge": { "into": { "connectionName": "solar-cluster-connection", "db": "solarDb", "coll": "solarColl" } }}]Nota
La fuente sample_stream_solar es una conexión solo de prueba que produce documentos de muestra cada segundo y está destinada a la creación rápida de prototipos.
Ejecute los siguientes comandos en su clúster solar-cluster-connection para verificar el comportamiento del procesador de transmisiones. Para conectarse, consulte Conectarse a un clúster mediante mongosh.
Para ver los documentos de la colección solarDb.solarColl resultante, ejecuta:
db.getSiblingDB("solarDb").solarColl.find()Cada documento incluye los campos device_id, event_type, group_id, max_watts, obs y timestamp de un informe de dispositivo solar. Puede observar que ningún documento en la salida tiene un device_id de device_8, porque la etapa $match excluye esos informes antes de que la etapa $merge guarde los documentos restantes en solarColl.
Nota
Lo anterior es un ejemplo representativo. Los datos en transmisión no son estáticos, y cada usuario ve documentos distintos.
Ejemplo de cronograma Cron
La siguiente agregación genera un documento cada cinco minutos en lugar de leer de una conexión. Esta agregación ejecuta tres etapas:
La
$sourceetapa emite un documento vacío en el segundo0de cada cinco minutos, en UTC.La etapa
$projectetiqueta cada documento con un nombre de tarea y copia la marca de tiempo programada del campo_tsen un camporunAt.La fase
$mergeescribe la salida en una colección Atlas denominadaheartbeatsen la base de datossample_weatherstream. Si no existe tal base de datos o colección, Atlas los creará.
[{ "$source": { "schedule": "0 0/5 * * * *" }},{ "$project": { "job": "five-minute-heartbeat", "runAt": "$_ts" }},{ "$merge": { "into": { "connectionName": "weatherStreamOutput", "db": "sample_weatherstream", "coll": "heartbeats" } }}]Para ver los documentos de la colección sample_weatherstream.heartbeats resultante, conéctate a un clúster de Atlas y ejecuta el siguiente comando:
db.getSiblingDB("sample_weatherstream").heartbeats.find()Nota
Lo anterior es un ejemplo representativo. Las marcas de tiempo que ve dependen de cuándo inicia el procesador de flujos.