Ejecute un comando de base de datos

Overview

En esta guía, puedes aprender a ejecutar un comando de base de datos con el controlador C. Puede usar comandos de base de datos para realizar una variedad de tareas administrativas y de diagnóstico, como obtener estadísticas del servidor, inicializar un set de réplicas o ejecutar un pipeline de agregación.

Importante

Prefiera las funciones del controlador a los comandos de la base de datos

El controlador proporciona funciones de contenedor para numerosos comandos de base de datos. Recomendamos usar funciones de controlador en lugar de ejecutar comandos de base de datos siempre que sea posible.

Para realizar tareas administrativas, usa el MongoDB Shell en lugar del controlador C. Llamando al db.runCommand() El método dentro del shell es el método preferido para emitir comandos de base de datos, ya que proporciona una interfaz coherente entre el shell y los drivers.

Ejecutar un comando

Para ejecutar un comando de base de datos, debe especificar el comando y los parámetros relevantes en un documento BSON y, a continuación, pasar este documento BSON a una función de ejecución de comandos. El controlador de C proporciona las siguientes funciones para ejecutar comandos de base de datos:

mongoc_client_command_simple(), que ejecuta un comando especificado en el servidor y almacena el primer documento del resultado en el documento BSON reply. Esta función proporciona una forma simplificada de enviar un comando directamente al servidor.
mongoc_client_command_with_opts()Se ejecuta un comando específico en el servidor e interpreta opts según la versión del servidor MongoDB. Esta función ofrece flexibilidad al permitir opciones adicionales.

El siguiente código muestra cómo puede utilizar la función mongoc_client_command_simple() para ejecutar el comando hello, que devuelve información sobre el rol del miembro actual en el conjunto de réplicas, en una base de datos:

bson_t reply;
bson_error_t error;
bson_t *command = BCON_NEW("hello", BCON_INT32(1));
bool retval = mongoc_client_command_simple(client, "admin", command, NULL, &reply, &error);
if (!retval) {
    fprintf(stderr, "Failed to run command: %s\n", error.message);
} else {
    char *str = bson_as_canonical_extended_json(&reply, NULL);
    printf("%s\n", str);
    bson_free(str);
}
bson_destroy(command);
bson_destroy(&reply);

Para una lista completa de comandos de base de datos y sus parámetros correspondientes, consulta la sección Información adicional.

Opciones de comando

Puedes especificar el comportamiento de comando opcional para la función mongoc_client_command_with_opts(). Esta función acepta un documento BSON para el parámetro opts.

Puede pasar un documento BSON que especifique las siguientes opciones:

readConcern
writeConcern
sessionId
collation
serverId

Para aprender más sobre un comando y las opciones que acepta, localice el comando y siga el enlace en la sección Comandos de Base de Datos del manual del servidor.

El siguiente código muestra cómo especificar un comando grantRolesToUsers con una preocupación de escritura majority:

bson_t reply;
bson_error_t error;
bson_t *command = BCON_NEW(
    "grantRolesToUser", BCON_UTF8("user011"),
    "roles", "[", BCON_UTF8("readWrite"), "]"
);
mongoc_write_concern_t *write_concern = mongoc_write_concern_new();
mongoc_write_concern_set_w(write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
bson_t *opts = bson_new();
mongoc_write_concern_append(write_concern, opts);
bool retval = mongoc_client_command_with_opts(client, "admin", command, NULL, opts, &reply, &error);
if (!retval) {
    fprintf(stderr, "Failed to run command: %s\n", error.message);
} else {
    char *str = bson_as_canonical_extended_json(&reply, NULL);
    printf("Command Result: %s\n", str);
    bson_free(str);
}
bson_destroy(command);
bson_destroy(opts);
bson_destroy(&reply);
mongoc_write_concern_destroy(write_concern);

Nota

preferencia de lectura

Las funciones mongoc_client_command_simple() y mongoc_client_command_with_opts() ignoran la configuración de preferencia de lectura que hayas establecido en tu cliente. Por defecto, estas funciones utilizan la preferencia de lectura primary.

Para especificar una preferencia de lectura distinta a la preferencia de lectura primaria, debes pasarla explícitamente como argumento. El siguiente código demuestra cómo especificar una preferencia de lectura y utilizarla con la función mongoc_client_command_simple():

read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY);
command = BCON_NEW("hello", BCON_INT32(1));
retval = mongoc_client_command_simple(client, "admin", command,
read_prefs, &reply, &error);

Para obtener más información sobre las opciones de preferencia de lectura, consulta Preferencia de lectura en el Manual del servidor.

Respuesta

Cada función devuelve un documento BSON o un cursor que contiene la respuesta de la base de datos después de que se ejecuta el comando. Cada comando de base de datos realiza una función diferente, por lo que el contenido de la respuesta puede variar entre comandos. Sin embargo, cada respuesta contiene documentos con los siguientes campos:

<command result>: Proporciona campos específicos para el comando de base de datos. Por ejemplo, count devuelve el campo n y explain devuelve el campo queryPlanner.
ok: Indica si el comando se ha ejecutado correctamente (1) o si ha fallado (0).

Ejemplo

El siguiente código muestra cómo usar la función mongoc_client_write_command_with_opts() para ejecutar el comando cloneCollectionAsCapped con la opción writeConcern. Luego, usa la función mongoc_client_read_command_with_opts() para ejecutar el comando distinct con las opciones collation y readConcern.

1 bson_t reply;
2 bson_error_t error;
3 
4 bson_t *cmd = BCON_NEW("cloneCollectionAsCapped",
5         BCON_UTF8("my_collection"),
6         "toCollection",
7         BCON_UTF8("my_capped_collection"),
8         "size",
9         BCON_INT64(1024 * 1024));
10 
11 /* Includes write concern "majority" in command options */
12 mongoc_write_concern_t *write_concern = mongoc_write_concern_new();
13 mongoc_write_concern_set_w(write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
14 bson_t *opts = bson_new();
15 mongoc_write_concern_append(write_concern, opts);
16 
17 if (mongoc_client_write_command_with_opts(client, "test", cmd, opts, &reply, &error)) {
18     char *str = bson_as_canonical_extended_json(&reply, NULL);
19     printf("cloneCollectionAsCapped: %s\n", str);
20     bson_free(str);
21 } else {
22     fprintf(stderr, "cloneCollectionAsCapped: %s\n", error.message);
23 }
24 
25 bson_free(cmd);
26 bson_free(opts);
27 bson_destroy(&reply);
28 
29 /* Defines distinct values of "x" in "my_collection" where "y" sorts after "one" */
30 cmd = BCON_NEW("distinct",
31         BCON_UTF8("my_collection"),
32         "key",
33         BCON_UTF8("x"),
34         "query",
35         "{",
36         "y",
37         "{",
38         "$gt",
39         BCON_UTF8("one"),
40         "}",
41         "}");
42 
43 mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY);
44 
45 /* Specifies "One" sorts after "one" to override default behavior */
46 opts = BCON_NEW("collation", "{", "locale", BCON_UTF8("en_US"), "caseFirst", BCON_UTF8("lower"), "}");
47 
48 /* Adds a read concern to "opts" */
49 mongoc_read_concern_t *read_concern = mongoc_read_concern_new();
50 mongoc_read_concern_set_level(read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);
51 mongoc_read_concern_append(read_concern, opts);
52 
53 if (mongoc_client_read_command_with_opts(client, "test", cmd, read_prefs, opts, &reply, &error)) {
54     char* str = bson_as_canonical_extended_json(&reply, NULL);
55     printf("distinct: %s\n", str);
56     bson_free(str);
57 } else {
58     fprintf(stderr, "distinct: %s\n", error.message);
59 }
60 
61 bson_destroy(cmd);
62 bson_destroy(opts);
63 bson_destroy(&reply);
64 mongoc_read_prefs_destroy(read_prefs);
65 mongoc_read_concern_destroy(read_concern);
66 mongoc_write_concern_destroy(write_concern);

Salida

El comando cloneCollectionAsCapped clona una colección como una colección limitada. A continuación, el comando distinct obtiene los valores distintos de un campo con un filtro y una intercalación determinados. El ejemplo genera el siguiente resultado:

cloneCollectionAsCapped: { "ok": 1, ... } distinct: { "values": ["value1",
"value2", "value3"], "ok": 1, ... }

Información Adicional

Para más información sobre los conceptos de esta guía, consulta la siguiente documentación:

Documentación de la API

Volver

MongoDB búsqueda

1	bson_t reply;
2	bson_error_t error;
3
4	bson_t *cmd = BCON_NEW("cloneCollectionAsCapped",
5	BCON_UTF8("my_collection"),
6	"toCollection",
7	BCON_UTF8("my_capped_collection"),
8	"size",
9	BCON_INT64(1024 * 1024));
10
11	/* Includes write concern "majority" in command options */
12	mongoc_write_concern_t *write_concern = mongoc_write_concern_new();
13	mongoc_write_concern_set_w(write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
14	bson_t *opts = bson_new();
15	mongoc_write_concern_append(write_concern, opts);
16
17	if (mongoc_client_write_command_with_opts(client, "test", cmd, opts, &reply, &error)) {
18	char *str = bson_as_canonical_extended_json(&reply, NULL);
19	printf("cloneCollectionAsCapped: %s\n", str);
20	bson_free(str);
21	} else {
22	fprintf(stderr, "cloneCollectionAsCapped: %s\n", error.message);
23	}
24
25	bson_free(cmd);
26	bson_free(opts);
27	bson_destroy(&reply);
28
29	/* Defines distinct values of "x" in "my_collection" where "y" sorts after "one" */
30	cmd = BCON_NEW("distinct",
31	BCON_UTF8("my_collection"),
32	"key",
33	BCON_UTF8("x"),
34	"query",
35	"{",
36	"y",
37	"{",
38	"$gt",
39	BCON_UTF8("one"),
40	"}",
41	"}");
42
43	mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY);
44
45	/* Specifies "One" sorts after "one" to override default behavior */
46	opts = BCON_NEW("collation", "{", "locale", BCON_UTF8("en_US"), "caseFirst", BCON_UTF8("lower"), "}");
47
48	/* Adds a read concern to "opts" */
49	mongoc_read_concern_t *read_concern = mongoc_read_concern_new();
50	mongoc_read_concern_set_level(read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);
51	mongoc_read_concern_append(read_concern, opts);
52
53	if (mongoc_client_read_command_with_opts(client, "test", cmd, read_prefs, opts, &reply, &error)) {
54	char* str = bson_as_canonical_extended_json(&reply, NULL);
55	printf("distinct: %s\n", str);
56	bson_free(str);
57	} else {
58	fprintf(stderr, "distinct: %s\n", error.message);
59	}
60
61	bson_destroy(cmd);
62	bson_destroy(opts);
63	bson_destroy(&reply);
64	mongoc_read_prefs_destroy(read_prefs);
65	mongoc_read_concern_destroy(read_concern);
66	mongoc_write_concern_destroy(write_concern);