Docs 菜单
Docs 主页
/ / /
C 驱动程序
/

运行数据库命令

在此页面上

  • Overview
  • 执行命令
  • 命令选项
  • 响应
  • 例子
  • 输出
  • 更多信息
  • API 文档

在本指南中,您可以学习;了解如何使用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);

有关读取偏好选项的更多信息,请参阅 MongoDB Server手册中的 读取偏好 。

命令运行后,每个函数都会返回一个BSON文档或一个包含数据库响应的游标。每个数据库命令执行不同的功能,因此响应内容可能因命令而异。但是,每个响应都包含具有以下字段的文档:

  • <command result>:提供特定于数据库命令的字段。示例,count 返回 n字段,explain 返回 queryPlanner字段。

  • ok:指示命令是成功 (1) 还是失败 (0)。

以下代码展示了如何使用 mongoc_client_write_command_with_opts() 函数运行带有 writeConcern 选项的 cloneCollectionAsCapped 命令。然后,它使用 mongoc_client_read_command_with_opts() 函数运行带有 collationreadConcern 选项的 distinct 命令。

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);

cloneCollectionAsCapped 命令将集合克隆为固定固定大小集合。然后,distinct 命令使用给定的过滤和排序规则获取字段的非重复值。该示例输出以下结果:

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

有关本指南中概念的更多信息,请参阅以下文档:

后退

时间序列