データベースコマンドの実行
Overview
このガイドでは、 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
コマンドを実行します。
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
コマンドは、コレクションをCappedコレクションコレクションとしてクローンします。次に、distinct
コマンドは、指定されたフィルターと照合を使用してフィールドの個別の値を取得します。この例では、次の結果が出力されます。
cloneCollectionAsCapped: { "ok": 1, ... } distinct: { "values": ["value1", "value2", "value3"], "ok": 1, ... }
詳細情報
このガイドの概念の詳細については、次のドキュメントを参照してください。