Ejecute un comando de base de datos

Overview

En esta guía, puede 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 conjunto de réplicas o ejecutar una canalización 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, utilice 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 consistente entre el shell y los controladores.

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 específico 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(), que 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

Puede especificar el comportamiento del 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 obtener más información sobre un comando y las opciones que acepta, ubique 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 preferencia de lectura que haya configurado en su cliente. De forma predeterminada, estas funciones utilizan la preferencia de lectura primary.

Para especificar una preferencia de lectura distinta a la principal, debe pasarla explícitamente como argumento. El siguiente código muestra cómo especificar una preferencia de lectura y usarla 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, consulte 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 tras la ejecución del comando. Cada comando de base de datos realiza una función diferente, por lo que el contenido de la respuesta puede variar según el comando. Sin embargo, cada respuesta contiene documentos con los siguientes campos:

<command result>Proporciona campos específicos del comando de base de datos. Por ejemplo, count devuelve el campo n y explain el campo queryPlanner.
ok: Indica si el comando tuvo éxito (1) o falló (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);