运行数据库命令
Overview
在本指南中,您可以学习;了解如何使用C驾驶员运行数据库命令。您可以使用数据库命令执行各种管理和诊断任务,例如获取服务器统计信息、初始化副本集或运行聚合管道。
重要
首选驱动程序函数而非数据库命令
驾驶员程序为许多数据库命令提供了包装器函数。我们建议尽可能使用驾驶员函数,而不是执行数据库命令。
要执行管理任务,请使用 MongoDB Shell而不是C驾驶员。在Shell内调用db.runCommand()
方法是发出数据库命令的首选方法,因为它在Shell和驱动程序之间提供了一致的接口。
执行命令
要运行数据库命令,必须在BSON文档中指定该命令和所有相关参数,然后将此BSON文档传递给命令执行函数。 C驾驶员提供以下函数来运行数据库命令:
mongoc_client_command_simple()
,它会在服务器上运行指定的命令,并将结果中的第一个文档存储在reply
BSON文档中。此函数提供了一种直接向服务器发送命令的简化方法。mongoc_client_command_with_opts()
,它会在服务器上运行指定的命令并根据MongoDB服务器版本解释opts
。此功能通过允许附加选项来提供灵活性。
以下代码显示如何使用 mongoc_client_command_simple()
函数运行hello
命令,该命令会返回有关数据库中副本集当前成员角色的信息:
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);
有关数据库命令和相应参数的完整列表,请参阅“其他信息”部分。
命令选项
您可以为 mongoc_client_command_with_opts()
函数指定可选命令行为。此函数接受BSON文档作为 opts
参数。
您可以传递指定以下选项的BSON文档:
readConcern
writeConcern
sessionId
collation
serverId
要学习;了解有关命令及其接受的选项的更多信息,请找到该命令并点击服务器手册数据库命令部分中的链接。
以下代码展示了如何指定具有 majority
写关注(write concern)的 grantRolesToUsers
命令:
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);
注意
读取偏好
mongoc_client_command_simple()
和 mongoc_client_command_with_opts()
函数忽略您可能在客户端上设立的读取偏好(read preference)设置。默认,这些函数使用 primary
读取偏好(read preference)。
要指定主节点 (primary node in the replica set)节点读取读取偏好(read preference)以外的读取偏好(read preference),必须将其作为参数显式传递。以下代码演示了如何指定读取偏好(read preference)并将其与 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);
响应
命令运行后,每个函数都会返回一个BSON文档或一个包含数据库响应的游标。每个数据库命令执行不同的功能,因此响应内容可能因命令而异。但是,每个响应都包含具有以下字段的文档:
<command result>
:提供特定于数据库命令的字段。示例,count
返回n
字段,explain
返回queryPlanner
字段。ok
:指示命令是成功 (1
) 还是失败 (0
)。
例子
以下代码展示了如何使用 mongoc_client_write_command_with_opts()
函数运行带有 writeConcern
选项的 cloneCollectionAsCapped
命令。然后,它使用 mongoc_client_read_command_with_opts()
函数运行带有 collation
和 readConcern
选项的 distinct
命令。
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);
输出
cloneCollectionAsCapped
命令将集合克隆为固定固定大小集合。然后,distinct
命令使用给定的过滤和排序规则获取字段的非重复值。该示例输出以下结果:
cloneCollectionAsCapped: { "ok": 1, ... } distinct: { "values": ["value1", "value2", "value3"], "ok": 1, ... }
更多信息
有关本指南中概念的更多信息,请参阅以下文档: