Menu Docs
Página inicial do Docs
/ / /
Driver C
/

Executar um comando de banco de dados

Nesta página

  • Visão geral
  • Executar um comando
  • Opções de comando
  • Resposta
  • Exemplo
  • Saída
  • Informações adicionais
  • Documentação da API

Neste guia, você pode aprender como executar um comando de banco de dados de dados com o driver C. Você pode usar comandos de banco de dados de dados para executar uma variedade de tarefas administrativas e de diagnóstico, como buscar estatísticas do servidor , inicializar um conjunto de réplicas ou executar um pipeline de agregação .

Importante

Preferir funções de driver a comandos de banco de dados

O driver fornece funções de wrapper para muitos comandos de banco de dados de dados. Recomendamos usar funções de driver em vez de executar comandos de banco de dados de dados quando possível.

Para executar tarefas administrativas, use o MongoDB Shell em vez do driver C. Chamar o db.runCommand() método dentro do shell é o método preferido para emitir comandos do banco de dados de dados, pois ele fornece uma interface consistente entre o shell e os drivers.

Para executar um comando de banco de dados de dados, você deve especificar o comando e quaisquer parâmetros relevantes em um documento BSON e, em seguida, passar esse documento BSON para uma função de execução de comando. O driver C fornece as seguintes funções para executar comandos de banco de dados de dados:

  • mongoc_client_command_simple(), que executa um comando especificado no servidor e armazena o primeiro documento do resultado no documento BSON reply. Esta função oferece uma maneira simplificada de enviar um comando diretamente ao servidor.

  • mongoc_client_command_with_opts(), que executa um comando especificado no servidor e interpreta o opts de acordo com a versão do servidor MongoDB . Esta função oferece flexibilidade ao permitir opções adicionais.

O código a seguir mostra como usar a função mongoc_client_command_simple() para executar o comando hello, que retorna informações sobre a função do membro atual no conjunto de réplicas, em um banco de dados de dados:

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 obter uma lista completa dos comandos do banco de dados e dos parâmetros correspondentes, consulte a seção Informações adicionais.

Você pode especificar o comportamento de comando opcional para a função mongoc_client_command_with_opts(). Esta função aceita um documento BSON para o parâmetro opts.

Você pode passar um documento BSON que especifique as seguintes opções:

  • readConcern

  • writeConcern

  • sessionId

  • collation

  • serverId

Para saber mais sobre um comando e as opções que ele aceita, localize o comando e siga o link na seção Comandos do banco de dados do manual do servidor.

O código abaixo mostra como especificar um comando grantRolesToUsers com uma preocupação de gravação 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);

Observação

readPreference

As funções mongoc_client_command_simple() e mongoc_client_command_with_opts() ignoram a configuração de preferência de leitura que você pode ter definido no seu cliente. Por padrão, essas funções usam a preferência de leitura primary.

Para especificar uma preferência de leitura diferente da preferência de leitura primária, você deve explicitamente passá-la como um argumento. O código abaixo demonstra como especificar uma preferência de leitura e usá-la com a função 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 obter mais informações sobre as opções de read preference, consulte Read preference no manual do servidor MongoDB.

Cada função retorna um documento BSON ou um cursor contendo a resposta do banco de banco de dados após a execução do comando. Cada comando de banco de dados de dados executa uma função diferente, portanto, o conteúdo da resposta pode variar entre comandos. No entanto, cada resposta contém documentos com os seguintes campos:

  • <command result>: Fornece campos específicos para o comando de banco de dados de dados . Por exemplo, count retorna o campo n e explain retorna o campo queryPlanner .

  • ok: indica se o comando obteve êxito (1) ou falhou (0).

O código a seguir mostra como você pode usar a função mongoc_client_write_command_with_opts() para executar o comando cloneCollectionAsCapped com a opção writeConcern. Em seguida, ele usa a função mongoc_client_read_command_with_opts() para executar o comando distinct com as opções collation e readConcern.

1bson_t reply;
2bson_error_t error;
3
4bson_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 */
12mongoc_write_concern_t *write_concern = mongoc_write_concern_new ();
13mongoc_write_concern_set_w (write_concern, MONGOC_WRITE_CONCERN_W_MAJORITY);
14bson_t *opts = bson_new ();
15mongoc_write_concern_append (write_concern, opts);
16
17if (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
25bson_free (cmd);
26bson_free (opts);
27bson_destroy (&reply);
28
29/* Defines distinct values of "x" in "my_collection" where "y" sorts after "one" */
30cmd = 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
43mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new (MONGOC_READ_SECONDARY);
44
45/* Specifies "One" sorts after "one" to override default behavior */
46opts = BCON_NEW ("collation", "{", "locale", BCON_UTF8 ("en_US"), "caseFirst", BCON_UTF8 ("lower"), "}");
47
48/* Adds a read concern to "opts" */
49mongoc_read_concern_t *read_concern = mongoc_read_concern_new ();
50mongoc_read_concern_set_level (read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);
51mongoc_read_concern_append (read_concern, opts);
52
53if (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
61bson_destroy (cmd);
62bson_destroy (opts);
63bson_destroy (&reply);
64mongoc_read_prefs_destroy (read_prefs);
65mongoc_read_concern_destroy (read_concern);
66mongoc_write_concern_destroy (write_concern);

O comando cloneCollectionAsCapped clona uma collection como uma collection limitada. Em seguida, o comando distinct obtém os valores distintos de um campo com um determinado filtro e agrupamento. O exemplo gera o seguinte resultado:

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

Para obter mais informações sobre os conceitos deste guia, consulte a seguinte documentação:

Voltar

Séries temporais