AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

データベースコマンドの実行

このガイドでは、 Cドライバーを使用してデータベースコマンドを実行する方法を学習できます。 データベースコマンドを使用して、サーバー統計の取得、レプリカセットを初期化、集計パイプラインの実行中など、さまざまな管理および診断タスクを実行できます。

重要

データベースコマンドよりもドライバー関数を優先

このドライバーは、多くのデータベースコマンドのラッパー関数を提供します。 可能な場合は、データベースコマンドを実行する代わりにドライバー関数を使用することをお勧めします。

管理タスクを実行するには、 Cドライバーの代わりにMongoDB Shell を使用します。データベースコマンドを発行するには、 シェル内で db.runCommand() メソッドを呼び出すことをお勧めします。これにより、 シェルとドライバー間の一貫したインターフェースが提供されます。

データベースコマンド を実行するには、 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 書込み書込み保証 (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);

注意

読み込み設定 (read preference)

mongoc_client_command_simple() 関数と mongoc_client_command_with_opts() 関数は、クライアントに設定した読み込み設定(読み込み設定 (read preference)を無視します。 デフォルトでは 、これらの関数は primary読み込み設定 (read preference)を使用します。

プライマリの読み込み設定 (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);

読み込み設定(read preference)オプションの詳細については、サーバー マニュアルの読み込み設定(read preference) を参照してください。

各関数は、コマンドの実行後に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 コマンドを実行します。

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

cloneCollectionAsCapped コマンドは、コレクションをCappedコレクションとしてクローンします。 次に、distinct コマンドは、指定されたフィルターと照合を使用してフィールドの個別の値を取得します。 この例では、次の結果が出力されます。

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

このガイドの概念の詳細については、次のドキュメントを参照してください。