データベースコマンドを実行する

# MongoDB::command

(PECL mongo >=0.9.2)

MongoDB::command — データベースコマンドを実行する

### 説明

public MongoDB::command ( array `$command` [, array `$options` = array() [, string `&$hash` ]] ) : array

CRUD 操作以外のほとんどすべての操作は、データベースコマンドで行います。 データベースのバージョンを知りたい? それ用のコマンドがあります。 集約が必要ですって? そのためのコマンドがあります。 ログを記録したい? もちろん可能です。

このメソッドは、次のような関数と同じ働きをします。

`<?php
public function command($data) {
return $this->selectCollection('$cmd')->findOne($data);
}
?>`

### パラメータ

`command`

  送信したいクエリ。

`options`

  インデックスを作るオプションの配列です。現在サポートするオプションは次のとおりです。

  - "socketTimeoutMS"

    このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。

  以下のオプションは非推奨で、使ってはいけません。

  - "timeout"

    非推奨。"socketTimeoutMS" のエイリアス。

`hash`

  コマンドを実行するサーバーの接続ハッシュを設定します。 コマンドの結果が MongoCommandCursor の作成に適したものである場合、このハッシュは MongoCommandCursor::createFromDocument() に渡されます。

  このハッシュは、 MongoClient::getConnections() が返す接続に対応しています。

### 変更履歴

バージョン | 説明
--- | ---
1.5.0 | オプション "timeout" の名前が "socketTimeoutMS" に変わりました。 "wtimeout" を使うと、`E_DEPRECATED` が発生します。 参照渡しの hash パラメータが追加されました。
1.2.0 | options パラメータと、そのオプション "timeout" が追加されました。

### 返り値

データベースの応答を返します。データベースの応答はすべて、 最大で 1 件のドキュメントになります。つまり、データベースへのコマンドの結果は決して 16MB を超えないということです。結果のドキュメントの構造はコマンドによって異なりますが、 大半の結果には ok フィールドがあって、これが成功したか失敗したかを表します。 また、同じく大半の結果には results フィールドもあって、 ここにドキュメントの配列が含まれます。

### 例

例1 MongoDB::command() による "distinct" の例

あるキーの、すべての異なる値を探します。

`<?php
$people = $db->people;
$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));
$ages = $db->command(array("distinct" => "people", "key" => "age"));
foreach ($ages['values'] as $age) {
echo "$age\n";
}
?>`

上の例の出力は、 たとえば以下のようになります。

4
22
87

例2 MongoDB::command() での "distinct" の例

重複を排除したすべての値をキーから取得します。条件は、値が 18 以上であることです。

`<?php
$people = $db->people;
$people->insert(array("name" => "Joe", "age" => 4));
$people->insert(array("name" => "Sally", "age" => 22));
$people->insert(array("name" => "Dave", "age" => 22));
$people->insert(array("name" => "Molly", "age" => 87));
$ages = $db->command(
array(
"distinct" => "people",
"key" => "age",
"query" => array("age" => array('$gte' => 18))
)
);
foreach ($ages['values'] as $age) {
echo "$age\n";
}
?>`

上の例の出力は、 たとえば以下のようになります。

22
87

例3 MongoDB::command() での MapReduce の例

"sale" イベント上のすべてのユーザーと、各ユーザーが何回販売したかを取得します。

`<?php
// サンプルイベントドキュメント
$events->insert(array("user_id" => $id,
"type" => $type,
"time" => new MongoDate(),
"desc" => $description));
// map 関数と reduce 関数を作ります
$map = new MongoCode("function() { emit(this.user_id,1); }");
$reduce = new MongoCode("function(k, vals) { ".
"var sum = 0;".
"for (var i in vals) {".
"sum += vals[i];".
"}".
"return sum; }");
$sales = $db->command(array(
"mapreduce" => "events",
"map" => $map,
"reduce" => $reduce,
"query" => array("type" => "sale"),
"out" => array("merge" => "eventCounts")));
$users = $db->selectCollection($sales['result'])->find();
foreach ($users as $user) {
echo "{$user['_id']} had {$user['value']} sale(s).\n";
}
?>`

上の例の出力は、 たとえば以下のようになります。

User 47cc67093475061e3d9536d2 had 3 sale(s).
User 49902cde5162504500b45c2c had 14 sale(s).
User 4af467e4fd543cce7b0ea8e2 had 1 sale(s).

> 注意: MongoCode の使用

> この例で使っている MongoCode には、引数でスコープを渡すこともできます。しかし現時点では、 MongoDB は MapReduce におけるスコープの使用に対応していません。 クライアントサイドの変数を MapReduce 関数で使いたい場合は、 データベースコマンドでオプションの scope フィールドを使って グローバルスコープに追加してください。詳細な情報は » MapReduce のドキュメント を参照ください。

> 注意: out 引数

> 1.8.0 より前は out 引数がオプションでした。指定しなければ、 MapReduce の結果はテンポラリコレクションに書き出されます。これは、 接続が閉じるときに削除されます。1.8.0 以降では out 引数が必須となります。詳細な情報は » MapReduce のドキュメント を参照ください。

例4 MongoDB::command() での "geoNear" の例

この例は、geoNear コマンドの使い方を示すものです。

`<?php
$m = new MongoClient();
$d = $m->demo;
$c = $d->poiConcat;
$r = $d->command(array(
'geoNear' => "poiConcat", // poiConcat コレクション内を検索します
'near' => array(-0.08, 51.48), // 北緯 51.48°、東経 0.08° 近辺を検索します
'spherical' => true, // 球状検索を有効にします
'num' => 5, // 最大 5 件までの結果を返します
));
print_r($r);
?>`

### 参考

- MongoCollection::aggregate() - aggregation フレームワークを使って集約する
- MongoCollection::findAndModify() - ドキュメントを更新して返す
- MongoCollection::group() - SQL の GROUP BY コマンドと似た処理を行う

MongoDB コアドキュメントの » database commands