MongoCollection
PHP Manual

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex — 指定したフィールドにインデックスを作成する (すでに存在する場合は何もしない)

説明

public bool MongoCollection::ensureIndex ( string|array $key|keys [, array $options = array() ] )

このメソッドは、コレクション上の指定されたフィールドにインデックスを作成します。 キーの指定方法は、単一のフィールド名を文字列で指定するか あるいはフィールド名とソート方向を対応させた配列でも指定できます。

パラメータ

keys

インデックスをソートするフィールドの配列。配列の各要素のキーがフィールド名、 そして昇順の場合は 1、降順の場合は -1 を値に指定します。

options

このパラメータは array("optionname" => <boolean>, ...) 形式の連想配列で、現在サポートしているオプションは次の通りです。

  • "unique"

    一意なインデックスを作ります。

    警告

    そのフィールドを持たないドキュメントが複数ある場合は、 そこに一意なインデックスを作成することはできません。 フィールドが存在しないときは事実上そのフィールドは NULL ということになり、それが複数存在すると既に一意ではなくなっているからです。

  • "dropDups"

    一意なインデックスを作ったときに重複する値が存在すれば、 ひとつを除いてその他すべてを削除します。

  • "background"

    MongoDB バージョン 1.3.2 以降を使っている場合は、 他の操作をしながらバックグラウンドでインデックスを作ることができます。 デフォルトでは、インデックスの作成を同期処理で行います。 このオプションを TRUE にすると、インデックスの作成が非同期で行われます。

  • "safe"

    ドライバのバージョン 1.0.4 以降では、 インデックスの作成に成功したかどうかを確認できるようになりました。 このオプションを指定すると、インデックスの作成に失敗したときに MongoCursorException をスローします。

    レプリケーションを使っていてマスタを変更している場合、もし "safe" を使っていればドライバはマスタとの接続を切断して例外をスローし、 次の操作時に新しいマスタを探そうとします (新しいマスタに対して操作を再試行するかどうかは アプリケーション側で判断しなければなりません)。

    レプリカセットで "safe" を 使わずに マスタを変更する場合は、ドライバがその変更について知るすべがありません。 そのため、何もエラーを出さずに書き込みに失敗し続けます。

  • "name"

    ドライバのバージョン 1.0.5 以降ではインデックス名を指定できます。 これは、多くのキーにインデックスをつけるときに「インデックス名が長すぎる」 と Mongo に言われた場合などに有用です。

  • "timeout"

    整数値。デフォルトは MongoCursor::$timeout です。 "safe" が設定されている場合に、クライアントがデータベースからの応答をどれだけ待つかを (ミリ秒単位で) 指定します。ここで指定した時間内にデータベースからの応答がない場合は MongoCursorTimeoutException がスローされます。

返り値

TRUE を返します。

変更履歴

バージョン 説明
1.0.2 "options" パラメータが boolean から配列に変わりました。 1.0.2 より前のバージョンでは二番目のパラメータはオプションの boolean 値で、一意なインデックスを指定するものでした。
1.0.11 "safe" は必要に応じてマスタのフェイルオーバーを行うようになりました。
1.0.11 インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローするようになりました。
1.2.0 timeout オプションが追加されました。
1.3.0 options パラメータで、boolean だけを渡してユニークインデックスを指定することができなくなりました。 同じことをするには array('unique' => true) としなければなりません。

エラー / 例外

インデックス名 (自動生成されたものあるいは設定したもののどちらでも) の長さが 128 バイトを超えた場合に MongoException をスローします (バージョン 1.0.11 以降)。

"safe" オプションを設定しているときにインデックスの作成に失敗すると MongoCursorException をスローします。

"safe" オプションを設定しているときに MongoCollection::$wtimeout ミリ秒でデータベース操作をレプリケーションできなければ MongoCursorTimeoutException をスローします。 これはサーバー上の操作を終了させるわけではなく、あくまでもクライアント側のタイムアウトです。

例

例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 を参照ください。

MongoCollection
PHP Manual