Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Executar um comando de banco de dados

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.

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 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:

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 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 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.

bson_t reply;bson_error_t error; bson_t *cmd = BCON_NEW("cloneCollectionAsCapped", BCON_UTF8("my_collection"), "toCollection", BCON_UTF8("my_capped_collection"), "size", BCON_INT64(1024 * 1024)); /* Includes write concern "majority" in command options */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); if (mongoc_client_write_command_with_opts(client, "test", cmd, opts, &reply, &error)) { char *str = bson_as_canonical_extended_json(&reply, NULL); printf("cloneCollectionAsCapped: %s\n", str); bson_free(str);} else { fprintf(stderr, "cloneCollectionAsCapped: %s\n", error.message);} bson_free(cmd);bson_free(opts);bson_destroy(&reply); /* Defines distinct values of "x" in "my_collection" where "y" sorts after "one" */cmd = BCON_NEW("distinct", BCON_UTF8("my_collection"), "key", BCON_UTF8("x"), "query", "{", "y", "{", "$gt", BCON_UTF8("one"), "}", "}"); mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY); /* Specifies "One" sorts after "one" to override default behavior */opts = BCON_NEW("collation", "{", "locale", BCON_UTF8("en_US"), "caseFirst", BCON_UTF8("lower"), "}"); /* Adds a read concern to "opts" */mongoc_read_concern_t *read_concern = mongoc_read_concern_new();mongoc_read_concern_set_level(read_concern, MONGOC_READ_CONCERN_LEVEL_MAJORITY);mongoc_read_concern_append(read_concern, opts); if (mongoc_client_read_command_with_opts(client, "test", cmd, read_prefs, opts, &reply, &error)) { char* str = bson_as_canonical_extended_json(&reply, NULL); printf("distinct: %s\n", str); bson_free(str);} else { fprintf(stderr, "distinct: %s\n", error.message);} bson_destroy(cmd);bson_destroy(opts);bson_destroy(&reply);mongoc_read_prefs_destroy(read_prefs);mongoc_read_concern_destroy(read_concern);mongoc_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: