文档菜单
文档首页
/
语言
/
C 驱动程序
/
C 驱动程序
/
数据库和集合

运行数据库命令

本页内容

  • 概述
  • 执行命令
  • 命令选项
  • 响应
  • 示例
  • 输出
  • 附加信息
  • 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() 函数指定可选的命令行为。此函数接受一个用于 opts 参数的 BSON 文档。

您可以通过传递一个指定以下选项的 BSON 文档

  • readConcern

  • writeConcern

  • sessionId

  • collation

  • serverId

要了解有关命令及其接受的选项的更多信息，请在服务器手册的数据库命令部分中找到该命令并点击链接。

以下代码演示了如何使用具有 majority 写关注度的 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() 函数忽略您可能在客户端设置的读偏好设置。默认情况下，这些函数使用 primary 读偏好。

要指定除主要读偏好之外的读偏好，必须显式将其作为参数传递。以下代码演示了如何指定读偏好并使用它与 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文档或一个包含数据库命令执行后响应的游标。每个数据库命令执行不同的功能，因此响应内容可能因命令而异。然而，每个响应都包含以下字段

  • <命令结果>：提供特定于数据库命令的字段。例如，count 返回 n 字段，而 explain 返回 queryPlanner 字段。

  • ok：指示命令是否成功（1）或失败（0）。

示例

以下代码展示了如何使用 mongoc_client_write_command_with_opts() 函数运行带有 writeConcern 选项的 cloneCollectionAsCapped 命令。然后，它使用 mongoc_client_read_command_with_opts() 函数运行带有 collation 和 readConcern 选项的 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, ... }

附加信息

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

API 文档

返回

时间序列数据

下一页

将数据写入 MongoDB