Acceder a datos desde un cursor

Overview

En esta guía, puedes aprender cómo acceder a datos desde un cursor con el controlador C.

Un cursor es un mecanismo que devuelve los resultados de una operación de lectura en lotes iterables. Debido a que un cursor solo mantiene un subconjunto de documentos en un momento dado, los cursores reducen tanto el consumo de memoria como el número de solicitudes que el controlador envía al servidor.

Siempre que el controlador C realiza una operación de lectura que devuelve múltiples documentos, automáticamente retorna esos documentos en un cursor.

Acceder al contenido del cursor de forma iterativa

Para iterar sobre el contenido de un cursor, utiliza un bucle while. El siguiente ejemplo recupera todos los documentos de la colección restaurants e imprime cada documento recorriendo el cursor:

const bson_t *doc;
bson_t *filter = bson_new();
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts(collection, filter, NULL, NULL);
while (mongoc_cursor_next(results, &doc)) {
    char *str = bson_as_canonical_extended_json(doc, NULL);
    printf("%s\n", str);
    bson_free(str);
}
mongoc_cursor_destroy(results);
bson_destroy(filter);

{ "_id" : { "$oid" : "..." }, ... , "name" : "Golden Pavillion", "restaurant_id" : "40363920" }
{ "_id" : { "$oid" : "..." }, ... , "name" : "Morris Park Bake Shop", "restaurant_id" : "30075445" }
{ "_id" : { "$oid" : "..." }, ... , "name" : "Criminal Court Bldg Cafeteria", "restaurant_id" : "40364443" }
{ "_id" : { "$oid" : "..." }, ... , "name" : "7B Bar", "restaurant_id" : "40364518" }
{ "_id" : { "$oid" : "..." }, ... , "name" : "Nyac Main Dining Room", "restaurant_id" : "40364467" }
...

Recuperar documentos individualmente

Recupera documentos de un cursor individualmente llamando a la función mongoc_cursor_next(). Esta función itera sobre el cursor y configura el parámetro bson al siguiente documento en el cursor.

El siguiente ejemplo encuentra todos los documentos en una colección con un valor de name de "Dunkin' Donuts". Luego imprime el primer documento en el cursor llamando a la función mongoc_cursor_next().

const bson_t *doc;
bson_t *filter = BCON_NEW("name", BCON_UTF8("Dunkin' Donuts"));
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts(collection, filter, NULL, NULL);
mongoc_cursor_next(results, &doc);
char *str = bson_as_canonical_extended_json(doc, NULL);
printf("%s\n", str);
bson_free(str);
mongoc_cursor_destroy(results);
bson_destroy(filter);

{ "_id" : { "$oid" : "..." }, ... , "name" : "Dunkin' Donuts", "restaurant_id" : "40392410" }

Cerrar un cursor

Para cerrar un cursor y liberar todos los recursos asociados, llama a la función mongoc_cursor_destroy() como se muestra en el siguiente ejemplo:

mongoc_cursor_destroy(cursor);

Cursores con seguimiento

Al hacer una consulta en una colección con tamaño fijo, puedes usar un cursor con seguimiento que permanezca abierto después de que el cliente agote los resultados en un cursor. Para crear un cursor con seguimiento en una colección con tamaño fijo, especifica las opciones tailable y awaitData al realizar una operación de búsqueda.

El siguiente ejemplo crea un cursor adaptable en una colección limitada:

collection = mongoc_client_get_collection(client, "<database>", "<capped collection>");
bson_t *filter = bson_new();
bson_t *opts = BCON_NEW("tailable", BCON_BOOL(true),
                         "awaitData", BCON_BOOL(true));
mongoc_cursor_t *tailable_cursor = 
    mongoc_collection_find_with_opts(collection, filter, opts, NULL);
// Perform operations with tailable cursor here
mongoc_cursor_destroy(tailable_cursor);
bson_destroy(filter);
bson_destroy(opts);

Para obtener más información sobre los cursores adaptables y su uso, consulte la guía Cursores adaptables en el manual del servidor MongoDB.

Solución de problemas

Documentación de la API

Para aprender más sobre alguna de las funciones tratadas en esta guía, consulta la siguiente documentación de la API:

• mongoc_collection_find_with_opts()

• mongoc_cursor_next()

• mongoc_cursor_destroy()