Supervisar los cambios en los datos

Datos de muestra

Los ejemplos de esta guía utilizan el restaurants colección en la base de datos sample_restaurants de la Conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía Introducción a MongoDB.

Abrir un ejemplo de flujo de cambios

El siguiente ejemplo abre un flujo de cambios en la colección restaurants e imprime los cambios a medida que ocurren:

bson_t *pipeline = bson_new();
const bson_t *doc;
mongoc_change_stream_t *change_stream =
    mongoc_collection_watch(collection, pipeline, NULL);
while (true) {
    bson_error_t error;
    if (mongoc_change_stream_next(change_stream, &doc)) {
        char *str = bson_as_canonical_extended_json(doc, NULL);
        printf("Received change: %s\n", str);
        bson_free(str);
    } else if (mongoc_change_stream_error_document(change_stream, &error, NULL)) {
        printf("Got error on change stream: %s\n", error.message);
        break;
    }
}
bson_destroy(pipeline);
mongoc_change_stream_destroy(change_stream);

Para empezar a observar los cambios, ejecuta la aplicación. Luego, en una aplicación o shell por separado, realiza una operación de guardado en la colección restaurants. El siguiente ejemplo actualiza un documento en el que el valor del campo name es "Blarney Castle":

bson_t *filter = BCON_NEW("name", BCON_UTF8("Blarney Castle"));
bson_t *update = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Irish"), "}");
mongoc_collection_update_one(collection, filter, update, NULL, NULL, NULL);

Cuando actualizas la colección, la aplicación del flujo de cambios imprime el cambio a medida que ocurre. El evento de cambio impreso se parece al siguiente:

{
  "_id": { ... },
  "operationType": "update",
  "clusterTime": { ... },
  "ns": {
    "db": "sample_restaurants",
    "coll": "restaurants"
  },
  "updateDescription": {
    "updatedFields": {
      "cuisine": "Irish"
    },
    "removedFields": [],
    "truncatedArrays": []
  }
  ...
}

Ejemplo de eventos específicos de un partido

El siguiente ejemplo utiliza el parámetro pipeline para incluir una etapa $match que abre un flujo de cambios que registra solo operaciones de actualización:

bson_t *pipeline = BCON_NEW(
    "pipeline", "[", 
    "{", "$match", "{", "operationType", BCON_UTF8("update"), "}", "}", 
    "]");
const bson_t *doc;
mongoc_change_stream_t *change_stream =
    mongoc_collection_watch(collection, pipeline, NULL);
while (mongoc_change_stream_next(change_stream, &doc)) {
  char *str = bson_as_canonical_extended_json(doc, NULL);
  printf("Received change: %s\n", str);
  bson_free(str);
}
bson_destroy(pipeline);
mongoc_change_stream_destroy(change_stream);

Para obtener más información sobre cómo modificar la salida de tu flujo de cambios, consulta la sección Modificar salida del flujo de cambio en el manual del MongoDB Server.

Incluir imágenes preoperativas y postoperatorias

De forma predeterminada, al realizar una operación en una colección, el evento de cambio correspondiente incluye solo la delta de los campos modificados por dicha operación. Para ver el documento completo antes o después de un cambio, especifique las opciones fullDocumentBeforeChange o fullDocument en la llamada a la función de vigilancia.

La preimagen es la versión completa de un documento antes de un cambio. Para incluir la preimagen en el evento del flujo de cambios, pasa uno de los siguientes valores a la opción fullDocumentBeforeChange:

• whenAvailable:El evento de cambio incluye una imagen previa del documento modificado para eventos de cambio solo si la imagen previa está disponible.

• requiredEl evento de cambio incluye una preimagen del documento modificado para los eventos de cambio. Si la preimagen no está disponible, el driver genera un error.

La post-imagen es la versión completa de un documento después de un cambio. Para incluir la postimagen en el evento de flujo de cambios, se debe pasar uno de los siguientes valores a la opción fullDocument:

• updateLookup: El evento de cambio incluye una copia de todo el documento cambiado a partir de cierto tiempo después del cambio.

• whenAvailable: El evento de cambio incluye una postimagen del documento modificado para eventos de cambio solo si la postimagen está disponible.

• required: El evento de cambio incluye una imagen posterior del documento modificado para eventos de cambio. Si la imagen posterior no está disponible, el driver genera un error.

El siguiente ejemplo llama a la función mongoc_collection_watch() en una colección e incluye la postimagen de los documentos actualizados en los resultados al especificar la opción fullDocument:

bson_t *pipeline = bson_new();
bson_t *opts = BCON_NEW("fullDocument", BCON_UTF8("updateLookup"));
const bson_t *doc;
mongoc_change_stream_t *change_stream =
    mongoc_collection_watch(collection, pipeline, opts);
while (true) {
    bson_error_t error;
    if (mongoc_change_stream_next(change_stream, &doc)) {
        char *str = bson_as_canonical_extended_json(doc, NULL);
        printf("Received change: %s\n", str);
        bson_free(str);
    } else if (mongoc_change_stream_error_document(change_stream, &error, NULL)) {
        printf("Got error on change stream: %s\n", error.message);
        break;
    }
}
bson_destroy(pipeline);
bson_destroy(opts);
mongoc_change_stream_destroy(change_stream);

Con la aplicación de flujo de cambios ejecutándose, actualizar un documento en la colección restaurants usando el ejemplo anterior de actualización imprime un evento de cambio semejante al siguiente:

{
  "_id": ...,
  "operationType": "update",
  "clusterTime": ...,
  "wallTime": ...,
  "fullDocument": {
    "_id": {
      ...
    },
    "address": ...,
    "borough": "Queens",
    "cuisine": "Irish",
    "grades": [ ... ],
    "name": "Blarney Castle",
    "restaurant_id": ...
  },
  "ns": {
    "db": "sample_restaurants",
    "coll": "restaurants"
  },
  "documentKey": {
    "_id": ...
  },
  "updateDescription": {
    "updatedFields": {
      "cuisine": "Irish"
    },
    "removedFields": [],
    "truncatedArrays": []
  }
}

Para obtener más información sobre pre-imágenes y post-imágenes, consulta Change Streams con preimágenes y postimágenes de documentos en el manual de MongoDB Server.

Documentación de la API

Para obtener más información sobre cualquiera de las funciones o tipos analizados en esta guía, consulte la siguiente documentación de API:

• mongoc_client_watch()

• mongoc_database_watch()

• mongoc_collection_watch()

• mongoc_change_stream_t