(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — 指定したフィールドにインデックスを作成する (すでに存在する場合は何もしない)
$key|keys
[, array $options = array()
] )このメソッドは、コレクション上の指定されたフィールドにインデックスを作成します。 キーの指定方法は、単一のフィールド名を文字列で指定するか あるいはフィールド名とソート方向を対応させた配列でも指定できます。
keys
インデックスをソートするフィールドの配列。配列の各要素のキーがフィールド名、 そして昇順の場合は 1、降順の場合は -1 を値に指定します。
options
このパラメータは array("optionname" => <boolean>, ...) 形式の連想配列で、現在サポートしているオプションは次の通りです。
"w"
WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。
"unique"
一意なインデックスを作ります。
そのフィールドを持たないドキュメントが複数ある場合は、
そこに一意なインデックスを作成することはできません。
フィールドが存在しないときは事実上そのフィールドは
NULL ということになり、それが複数存在すると既に一意ではなくなっているからです。
スパースなインデキシングを使えばこれを回避できるかもしれません。
そのフィールドを持たないドキュメントをインデックスしないようになるからです。
"dropDups"
一意なインデックスを作ったときに重複する値が存在すれば、 ひとつを除いてその他すべてを削除します。
"sparse"
スパースなインデックスを作り、そのフィールドを含むドキュメントだけを含めるようにします。 このオプションは、単一フィールドインデックスでしか使えません。
"expireAfterSeconds"
このオプションの値には、ドキュメントが期限切れになって自動的にコレクションから削除されるようになるまでの秒数を指定します。 このオプションは、単一フィールドインデックスかつそのフィールドに MongoDate の値を含む場合しか使えません。
この機能が使えるのは MongoDB 2.2 以降です。詳細は » Expire Data from Collections by Setting TTL を参照ください。
"background"
デフォルトではインデックスの作成はブロック操作になり、
処理が完了するまではデータベース上で他の操作を進めることができません。
このオプションを TRUE にすると、
インデックスの作成をバックグラウンドで行うようになり、
作成中にも他の操作ができるようになります。
MongoDB 2.1.0 より前のバージョンでのインデックス作成は、 セカンダリへのレプリケートのときには このオプションの値にかかわらずバックグラウンド処理になりませんでした。 詳細は » Building Indexes with Replica Sets を参照ください。
"name"
ドライバのバージョン 1.0.5 以降ではインデックス名を指定できます。 これは、多くのキーにインデックスをつけるときに「インデックス名が長すぎる」 と Mongo に言われた場合などに有用です。
"timeout"
整数で、デフォルトは MongoCursor::$timeout です。 "safe" が設定されている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。 この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。
"safe"
非推奨。WriteConcern の w オプションを使いましょう。
"w" オプションが設定されている場合は、
インデックスの作成の状態を含む配列を返します。それ以外の場合は
TRUE を返します。
配列のフィールドについての説明は MongoCollection::insert() を参照ください。
| バージョン | 説明 |
|---|---|
| 1.3.0 |
options パラメータで、boolean
だけを渡してユニークインデックスを指定することができなくなりました。
同じことをするには array('unique' => true)
としなければなりません。
|
| 1.2.11 |
options が scalar のときに E_DEPRECATED を発行するようになりました。
|
| 1.2.0 | "timeout" オプションが追加されました。 |
| 1.0.11 |
"safe" は必要に応じてプライマリのフェイルオーバーを行うようになりました。 インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローするようになりました。 |
| 1.0.2 |
options パラメータが boolean から配列に変わりました。
1.0.2 より前のバージョンでは二番目のパラメータはオプションの boolean
値で、一意なインデックスを指定するものでした。
|
インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローします (バージョン 1.0.11 以降)。
"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。
"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。
例1 MongoCollection::ensureIndex() の例
<?php
$c = new MongoCollection($db, 'foo');
// 'x' の昇順にインデックスを作成します
$c->ensureIndex('x');
// 'y' の昇順にインデックスを作成します
$c->ensureIndex(array('y' => 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 を参照ください。