MongoCollection
PHP Manual

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

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

説明

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

このメソッドは、バージョン 1.5.0 以降は非推奨となりました。かわりに MongoCollection::createIndex() を使いましょう。

コレクション上の指定されたフィールドが存在しない場合に、インデックスを作成します。 フィールドのインデックスは、方向 (昇順あるいは降順) で指定するか、 あるいは特定の型 (text, geospatial, hashed) で指定できます。

注意:

This method will use the » createIndexes database command when communicating with MongoDB 2.6+. For previous database versions, the method will perform an insert operation on the special system.indexes collection.

パラメータ

keys

インデックスをソートするフィールドの配列。配列の各要素のキーがフィールド名、 値には、方向あるいは » index type. を指定します。方向を指定する場合は、昇順なら 1、降順なら -1 と指定します。

options

An array of options for the index creation. Currently available options include:

  • "unique"

    Specify TRUE to create a unique index. The default value is FALSE. This option applies only to ascending/descending indexes.

    注意:

    When MongoDB indexes a field, if a document does not have a value for the field, a NULL value is indexed. If multiple documents do not contain a field, a unique index will reject all but the first of those documents. The "sparse" option may be used to overcome this, since it will prevent documents without the field from being indexed.

  • "dropDups"

    Specify TRUE to force creation of a unique index that may have duplicates. MongoDB will index the first occurrence of a key and delete all documents from the collection that contain subsequent occurrences of that key. The default value is FALSE.

    警告

    "dropDups" may delete data from your database. Use with extreme caution.

  • "sparse"

    Specify TRUE to create a sparse index, which only indexes documents containing a specified field. The default value is FALSE.

  • "expireAfterSeconds"

    The value of this option should specify the number of seconds after which a document should be considered expired and automatically removed from the collection. This option is only compatible with single-field indexes where the field will contain MongoDate values.

    注意:

    This feature is available in MongoDB 2.2+. See » Expire Data from Collections by Setting TTL for more information.

  • "name"

    A optional name that uniquely identifies the index.

    注意:

    By default, the driver will generate an index name based on the index's field(s) and ordering or type. For example, a compound index array("x" => 1, "y" => -1) would be named "x_1_y_-1" and a geospatial index array("loc" => "2dsphere") would be named "loc_2dsphere". For indexes with many fields, it is possible that the generated name might exceed MongoDB's » limit for index names. The "name" option may be used in that case to supply a shorter name.

  • 整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。

    "socketTimeoutMS"

The following option may be used with MongoDB 2.6+:

  • "maxTimeMS"

    操作を行う累積時間の制限 (アイドル時間を含まない) を、ミリ秒単位で指定します。この時間内に操作が完了しなければ、MongoExecutionTimeoutException をスローします。

The following options may be used with MongoDB versions before 2.6:

The following options are deprecated and should no longer be used:

  • "safe"

    非推奨。WriteConcern の w オプションを使いましょう。

  • "timeout"

    整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。

    警告

    非推奨です。かわりに "socketTimeoutMS" オプションを使いましょう。

  • "wtimeout"

    WriteConcern の確認をいつまで待つか。 MongoClient のデフォルトは 10000 ミリ秒です。

    警告

    非推奨です。かわりに "wTimeoutMS" オプションを使いましょう。

返り値

Returns an array containing the status of the index creation. The array contains whether the operation succeeded ("ok"), the number of indexes before and after the operation ("numIndexesBefore" and "numIndexesAfter"), and whether the collection that the index belongs to has been created ("createdCollectionAutomatically"). If the index already existed and did not need to be created, a "note" field may be present in lieu of "numIndexesAfter".

With MongoDB 2.4 and earlier, a status document is only returned if the write concern is at least 1. Otherwise, TRUE is returned. The fields in the status document are different, except for the "ok" field, which signals whether the index creation was successful. Additional fields are described in the documentation for MongoCollection::insert().

変更履歴

バージョン 説明
1.5.0

Renamed the "wtimeout" option to "wTimeoutMS". Emits E_DEPRECATED when "wtimeout" is used.

Renamed the "timeout" option to "socketTimeoutMS". Emits E_DEPRECATED when "timeout" is used.

Emits E_DEPRECATED when "safe" is used.

1.3.4 Added "wtimeout" option.
1.3.0

Added "w" option.

The options parameter no longer accepts a boolean to signify a unique index. Instead, this now has to be done with array('unique' => true).

1.2.11 Emits E_DEPRECATED when options is scalar.
1.2.0 Added "timeout" option.
1.0.11

The "safe" option will trigger a primary failover, if necessary.

MongoException will be thrown if the index name (either generated or set) is longer than 128 bytes.

1.0.5 Added the "name" option to override index name creation.
1.0.2 Changed options parameter from boolean to array. Pre-1.0.2, the second parameter was an optional boolean value specifying a unique index.

エラー / 例外

Throws MongoException if the index name is longer than 128 bytes, or if the index specification is not an array.

Throws MongoDuplicateKeyException if the server could not create the unique index due to conflicting documents.

Throws MongoResultException if the server could not create the index due to an error.

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

例

例1 MongoCollection::ensureIndex() example

<?php

$c = new MongoCollection($db, 'foo');

// create an index on 'x' ascending
$c->ensureIndex(array('x' => 1));

// create a unique index on 'y'
$c->ensureIndex(array('y' => 1), array('unique' => true));

// create a compound index on 'za' ascending and 'zb' descending
$c->ensureIndex(array('za' => 1, 'zb' => -1));

?>

例2 Geospatial Indexing

Mongo supports geospatial indexes, which allow you to search for documents near a given location or within a shape. The following example creates a geospatial index on the "loc" field:

<?php

$collection->ensureIndex(array('loc' => '2dsphere'));

?>

例3 Drop duplicates example

<?php

$collection->insert(array('username' => 'joeschmoe'));
$collection->insert(array('username' => 'joeschmoe'));

/* Index creation fails, since you cannot create a unique index on a field when
 * duplicates exist.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1));

/* MongoDB will one of the conflicting documents and allow the unique index to
 * be created.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));

/* We now have a unique index and subsequent inserts with the same username will
 * fail.
 */
$collection->insert(array('username' => 'joeschmoe'));

?>

参考

MongoCollection
PHP Manual