(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — 指定したフィールドにインデックスを作成する (すでに存在する場合は何もしない)
そのフィールドを持たないドキュメントが複数ある場合は、 そこに一意なインデックスを作成することはできません。 フィールドが存在しないときは事実上そのフィールドは NULL ということになり、それが複数存在すると既に一意ではなくなっているからです。
インデックスとして使用するフィールド。
このパラメータは array("optionname" => <boolean>, ...) 形式の連想配列で、現在サポートしているオプションは次の通りです。
"unique"
一意なインデックスを作ります。
"dropDups"
一意なインデックスを作ったときに重複する値が存在すれば、 ひとつを除いてその他すべてを削除します。
"background"
MongoDB バージョン 1.3.2 以降を使っている場合は、 他の操作をしながらバックグラウンドでインデックスを作ることができます。 デフォルトでは、インデックスの作成を同期処理で行います。 このオプションを TRUE にすると、インデックスの作成が非同期で行われます。
"safe"
ドライバのバージョン 1.0.4 以降では、 インデックスの作成に成功したかどうかを確認できるようになりました。 このオプションを指定すると、インデックスの作成に失敗したときに MongoCursorException をスローします。
レプリケーションを使っていてマスタを変更している場合、もし "safe" を使っていればドライバはマスタとの接続を切断して例外をスローし、 次の操作時に新しいマスタを探そうとします (新しいマスタに対して操作を再試行するかどうかは アプリケーション側で判断しなければなりません)。
レプリカセットで "safe" を 使わずに マスタを変更する場合は、ドライバがその変更について知るすべがありません。 そのため、何もエラーを出さずに書き込みに失敗し続けます。
"name"
ドライバの 1.0.4 より後のバージョン (1.0.4 は含みません) では、インデックスの名前を指定できます。 これは、多くのキーを作ろうとして Mongo にインデックス名が長くなりすぎると言われた場合などに有用です。
"timeout"
整数値。デフォルトは MongoCursor::$timeout です。 "safe" が設定されている場合に、クライアントがデータベースからの応答をどれだけ待つかを (ミリ秒単位で) 指定します。ここで指定した時間内にデータベースからの応答がない場合は MongoCursorTimeoutException がスローされます。
TRUE を返します。
| バージョン | 説明 | |||
|---|---|---|---|---|
| 1.0.2 | "options" パラメータが boolean から配列に変わりました。 1.0.2 より前のバージョンでは二番目のパラメータはオプションの boolean 値で、一意なインデックスを指定するものでした。 | 1.0.11 | "safe" は必要に応じてマスタのフェイルオーバーを行うようになりました。 | インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローするようになりました。 |
| 1.2.0 | timeout オプションが追加されました。 |
インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローします (バージョン 1.0.11 以降)。
"safe" オプションを設定しているときにインデックスの作成に失敗すると MongoCursorException をスローします。
"safe" オプションを設定しているときに MongoCollection::$wtimeout ミリ秒でデータベース操作をレプリケーションできなければ MongoCursorTimeoutException をスローします。 これはサーバ上の操作を終了させるわけではなく、あくまでもクライアント側のタイムアウトです。
例1 MongoCollection::ensureIndex() の例
<?php
$c = new MongoCollection($db, 'foo');
// 'x' の昇順にインデックスを作成します
$c->ensureIndex(array('x' => 1));
// 'z' の昇順、'zz' の降順にインデックスを作成します
$c->ensureIndex(array('z' => 1, 'zz' => -1));
// 'x' に一意なインデックスを作成します
$c->ensureIndex(array('x' => 1), array("unique" => true));
?>
例2 重複を削除する例
<?php
$collection->insert(array("username" => "joeschmoe"));
$collection->insert(array("username" => "joeschmoe"));
/*
* インデックスの作成に失敗します。重複する値があるキーに
* 一意なインデックスを作ることはできません。
*/
$collection->ensureIndex(array("username" => 1), array("unique" => 1));
/*
* インデックスの作成に成功します。ドキュメントのひとつがコレクションから削除されます。
*/
$collection->ensureIndex(array("username" => 1), array("unique" => 1, "dropDups" => 1));
/*
* 一意なインデックスができたあとは、同じユーザ名を
* このように追加しようとしても失敗します。
*/
$collection->insert(array("username" => "joeschmoe"));
?>
例3 地理空間のインデックス
Mongo は地理空間のインデックスをサポートしています。 これを使うと、指定した場所のそば、あるいは図形の範囲内にあるドキュメントを探すことができます。 たとえば、"loc" フィールドに地理空間のインデックスを作るには次のようにします。
<?php
$collection->ensureIndex(array("loc" => "2d"));
?>
MongoDB コアドキュメントの » vanilla indexes および » geospatial indexes を参照ください。