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 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.
Executar um comando
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 BSONreply
. 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 oopts
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.
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 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 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: