Executar um comando de banco de dados
Nesta página
Visão geral
Neste guia, você pode aprender como executar um comando de banco de dados com o driver C. Você pode usar comandos de banco 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 . Recomendamos usar funções de driver em vez de executar comandos de banco de dados quando possível.
Para executar tarefas administrativas, use o shell MongoDB em vez do driver C. Chamar o método db.runCommand()
dentro do shell é o método preferido para emitir comandos do banco de dados , pois ele fornece uma interface consistente entre o shell e os drivers.
Executar um comando
Para executar um comando de banco 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 :
mongoc_client_command_simple()
, que executa um comando especificado no servidor e armazena o primeiro documento do resultado no documentoreply
BSON. 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 interpretaopts
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:
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.
Opções de comando
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.
Resposta
Cada função retorna um documento BSON ou um cursor contendo a resposta do banco de dados após a execução do comando. Cada comando de banco 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. Por exemplo,count
retorna o campon
eexplain
retorna o campoqueryPlanner
.ok
: Indica se o comando obteve êxito (1
) ou falhou (0
).
Exemplo
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
.
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);
Saída
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, ... }
Informações adicionais
Para obter mais informações sobre os conceitos deste guia, consulte a seguinte documentação: