(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — 指定したフィールドが存在しない場合にインデックスを作成する
$key|keys
[, array $options = array()
] )このメソッドは、バージョン 1.5.0 以降は非推奨となりました。かわりに MongoCollection::createIndex() を使いましょう。
コレクション上の指定されたフィールドが存在しない場合に、インデックスを作成します。 フィールドのインデックスは、方向 (昇順あるいは降順) で指定するか、 あるいは特定の型 (text, geospatial, hashed) で指定できます。
注意:
このメソッドは、MongoDB 2.6 以降との通信の際には、データベースコマンド » createIndexes を使います。それ以前のバージョンのデータベースでは、特別なコレクション system.indexes 上での insert 操作を実行します。
keys
インデックスをソートするフィールドの配列。配列の各要素のキーがフィールド名、 値には、方向あるいは » index type. を指定します。方向を指定する場合は、昇順なら 1、降順なら -1 と指定します。
options
インデックス作成操作についてのオプションの配列。 現在利用可能なオプションは、以下のとおりです。
"unique"
TRUE を指定すると、一意なインデックスを作ります。デフォルト値は FALSE です。このオプションを使えるのは、昇順もしくは降順のインデックスだけです。
注意:
MongoDB がフィールドをインデックスするとき、もしそのフィールドに値を含まないドキュメントがあれば、
NULL値をインデックスします。このフィールドを含まないドキュメントが複数あった場合、一意なインデックスは、最初に出現したドキュメント以外を受け付けません。これを防ぐには "sparse" オプションを使います。このオプションを指定すれば、インデックス対象のフィールドが存在しないドキュメントはインデックスしなくなります。
"sparse"
TRUE を指定すると、疎なインデックスを作ります。これは、指定したフィールドを含むドキュメントだけをインデックスします。デフォルト値は FALSE です。
"expireAfterSeconds"
このオプションの値に指定するのは、ドキュメントを有効期限切れとみなしてコレクションから自動削除するまでの秒数です。このオプションが使えるのは、単一フィールドインデックスで、フィールドに MongoDate の値を含む場合のみです。
注意:
この機能が使えるのは、MongoDB 2.2 以降です。詳細は » Expire Data from Collections by Setting TTL を参照ください。
"name"
オプションの、インデックスを一意に特定するための名前。
注意:
ドライバーがデフォルトで生成するインデックス名は、インデックスのフィールドと、並び順あるいは型に基づくものです。たとえば、複合インデックス array("x" => 1, "y" => -1) の名前は "x_1_y_-1" であり、地理空間インデックス array("loc" => "2dsphere") の名前は "loc_2dsphere" となります。多数のフィールドからなるインデックスの場合、自動生成される名前が MongoDB の » インデックス名の制限 を超えてしまう可能性があります。"name" オプションは、そんな場合に短い名前を用意するときなどに使えます。
"background"
Builds the index in the background so that building an index does not block other database activities. Specify TRUE to build in the background. The default value is FALSE.
Prior to MongoDB 2.6.0, index builds on secondaries were executed as foreground operations, irrespective of this option. See » Building Indexes with Replica Sets for more information.
"socketTimeoutMS"
このオプションは、ソケット通信の制限時間を、ミリ秒単位で指定します。この時間内にサーバーからの反応がなければ、MongoCursorTimeoutException をスローします。この場合、サーバー側で書き込み処理が行われたのかどうかを判断できなくなります。-1 を指定すると、永遠にブロックします。MongoClient のデフォルト値は 30000 (30 秒) です。
以下のオプションは、MongoDB 2.6 以降で使えます。
"maxTimeMS"
サーバー上で操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内にサーバー側の操作が完了しなければ、MongoExecutionTimeoutException をスローします。
以下のオプションは、MongoDB 2.8 より前のバージョンで使えます。
"dropDups"
TRUE を指定すると、一意なインデックスを強制的に作成します。このとき、コレクション内でキーの値が重複してしまう可能性があります。MongoDB は最初に出現したキーをインデックスし、それ以降に出現する同じキーのすべてのドキュメントを削除します。デフォルト値は FALSE です。
"dropDups" はデータベースのデータを削除することがあるので、使う際には十分な注意が必要です。
注意:
このオプションは、MongoDB 2.8 以降には対応していません。コレクションに値の重複がある場合は、インデックスの作成に失敗します。
以下のオプションは、MongoDB 2.6 より前のバージョンで使えます。
"w"
WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。
"wTimeoutMS"
このオプションは、書き込み確認を待つ制限時間をミリ秒単位で指定します。これが書き込み操作に適用されるのは、"w" が 1 より大きい場合のみです。というのも、タイムアウトはレプリケーションに関する機能だからです。この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。0 を指定すると、永遠にブロックし続けます。MongoClient でのデフォルトは 10000 ミリ秒 (10 秒) です。
以下のオプションは廃止予定です。使ってはいけません。
"safe"
非推奨。write concern の w オプションを使いましょう。
"timeout"
非推奨。"socketTimeoutMS" のエイリアス。
"wtimeout"
廃止予定。"wTimeoutMS" のエイリアスです。
インデックスの作成状況を含む配列を返します。 作成に成功したかどうか ("ok")、 作成前と作成後のインデックス数 ("numIndexesBefore" および "numIndexesAfter")、 そのインデックスが属するコレクションを作成したかどうか ("createdCollectionAutomatically") が含まれます。 インデックスが既に存在していて作成の必要がない場合は、 "numIndexesAfter" に代わって "note" フィールドが含まれます。
MongoDB 2.4 以前のバージョンでは、
書き込み確認 が少なくとも
1 以上である場合は、ステータスを表すドキュメントを返します。
それ以外の場合は TRUE を返します。
ステータスを表すドキュメントのフィールドは場合によって異なりますが、
"ok" フィールドは常に存在し、インデックスの作成に成功したかどうかを示します。
その他のフィールドについては
MongoCollection::insert() のドキュメントを参照ください。
| バージョン | 説明 |
|---|---|
| 1.5.0 |
"wTimeoutMS" オプションが追加されました。これは
"wtimeout" を置き換えるものです。
"wtimeout" を使うと
"socketTimeoutMS" オプションが追加されました。これは
"timeout" を置き換えるものです。
"timeout" を使うと
"safe" を使うと
|
| 1.3.4 | "wtimeout" オプションが追加されました。 |
| 1.3.0 |
"w" オプションが追加されました。
|
| 1.2.11 |
options が scalar のときに E_DEPRECATED を発行するようになりました。
|
| 1.2.0 | "timeout" オプションが追加されました。 |
| 1.0.11 |
"safe" は必要に応じてプライマリのフェイルオーバーを行うようになりました。 インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローするようになりました。 |
| 1.0.5 | "name" オプションで、インデックス名の作成を上書きできるようになりました。 |
| 1.0.2 |
options パラメータが boolean から配列に変わりました。
1.0.2 より前のバージョンでは二番目のパラメータはオプションの boolean
値で、一意なインデックスを指定するものでした。
|
インデックス名が 128 バイトより長い場合、あるいはインデックスを配列以外で指定した場合に MongoException をスローします。
ドキュメントの衝突のせいでサーバーが一意なインデックスを作成できない場合に MongoDuplicateKeyException をスローします。
エラーが発生してサーバーがインデックスを作成できない場合に MongoResultException をスローします。
"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。
"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。
例1 MongoCollection::ensureIndex() の例
<?php
$c = new MongoCollection($db, 'foo');
// 'x' の昇順にインデックスを作成します
$c->ensureIndex(array('x' => 1));
// 'y' に一意なインデックスを作成します
$c->ensureIndex(array('y' => 1), array('unique' => true));
// 'za' の昇順、'zb' の降順に複合インデックスを作成します
$c->ensureIndex(array('za' => 1, 'zb' => -1));
?>
例2 地理空間のインデックス
Mongo は地理空間のインデックスをサポートしています。 これを使うと、指定した場所のそば、あるいは図形の範囲内にあるドキュメントを探すことができます。 たとえば、"loc" フィールドに地理空間のインデックスを作るには次のようにします。
<?php
$collection->ensureIndex(array('loc' => '2dsphere'));
?>
例3 重複を削除する例
<?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'));
?>