(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Creates an index on the specified field(s) if it does not already exist.
$key|keys
[, array $options = array()
] )This method is deprecated since version 1.5.0. Please use MongoCollection::createIndex() instead.
Creates an index on the specified field(s) if it does not already exist. Fields may be indexed with a direction (e.g. ascending or descending) or a special type (e.g. 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
An array specifying the index's fields as its keys. For each field, the value is either the index direction or » index type. If specifying direction, specify 1 for ascending or -1 for descending.
options
An array of options for the index creation. Currently available options include:
"unique"
Укажите TRUE для создания уникального индекса. По умолчанию значение равно FALSE. Эта опция применяется только к возрастающим/убывающим индексам.
Замечание:
При индексации MongoDB поля, если не имеет значения для указанного поля, будет проиндексировано значение
NULL. Если несколько документов не содержат поля, то уникальный индекс отклонит все документы, кроме первого. Можно использовать опцию "sparse", чтобы обойти это ограничение, так как документы без указанного поля не будут индексироваться.
"sparse"
Укажите TRUE для создания разреженного (sparse) индекса, который индексирует только документы содержащие указанное поле. Значение по умолчанию FALSE.
"expireAfterSeconds"
Значение этой опции определяет количество секунд, после которого документ считается устаревшим и автоматически удаляется из коллекции. Эта опция совместима только с индексами на одно поле, где поле содержит значения MongoDate.
Замечание:
Эта опция доступна в MongoDB 2.2+. Смотрите » Устаревание данных в коллекциях с помощью задания TTL для получения более подробной информации.
"name"
Необязательное имя, которое уникально идентифицирует индекс.
Замечание:
По умолчанию, драйвер создает имя индекса на основе полей индекса и их порядке или типе. Например, составной индекс array("x" => 1, "y" => -1) будет назван "x_1_y_-1", а геоиндекс array("loc" => "2dsphere") будет назван "loc_2dsphere". Для индексов из нескольких полей возможно превышение именем » максимальной длины имени индекса MongoDB. В этом случае можно применить опцию "name", чтобы указать более короткое имя.
"background"
Перестраивать индекс в фоновом режиме, чтобы не блокировать другие задачи базы данных. Укажите TRUE для перестроения в фоновом режиме. Значение по умолчанию - FALSE.
До MongoDB 2.6.0, перестраивание индекса запускалось на ведомом сервере как приоритетная операция, независимо от этой опции. Смотрите » Перестроение индексов с Replica Sets для дополнительной информации.
"socketTimeoutMS"
Эта опция определяет время в миллисекундах для общения в socket. Если сервер не ответил за отведенное время, то будет брошено исключение MongoCursorTimeoutException, и не будет никакой возможности определить произвел ли сервер запись или нет. Значение -1 используется для постоянно отключения этой функции. Значением по умолчанию для MongoClient является 30000 (30 секунд).
The following option may be used with MongoDB 2.6+:
"maxTimeMS"
Указывает суммарный лимит времени в миллисекундах на обработку операции (не включая время простоя) на сервере. Если операция на стороне сервера не завершилась за это время, то вызывается исключение MongoExecutionTimeoutException.
The following options may be used with MongoDB versions before 2.8:
"dropDups"
Укажите TRUE для принудительного создания уникального индекса, где коллекция может содержать одинаковые значения для ключа. MongoDB будет индексировать первое вхождение ключа и удалять все последующие документы из коллекции, которые содержат такие же значения для ключа. Значение по умолчанию - FALSE.
"dropDups" может удалить данные из вашей базы данных. Используйте с особой осторожностью.
Замечание:
Эта опция не поддерживается в MongoDB 2.8+. Создание индекса не выполнится, если коллекция содержит одинаковые значения.
The following options may be used with MongoDB versions before 2.6:
"w"
Смотрите Контроль записи. Значение по умолчанию для MongoClient является 1.
"wTimeoutMS"
Эта опция определяет лимит времени в миллисекундах для подтверждения контроля записи. Она применима только, если "w" больше 1, так как ограничение времени относится к репликации. Если контроль записи не подтвержден за отведенное время, то будет выброшено исключение MongoCursorException. Значение 0 для постоянного отключения. Значением по умолчанию для MongoClient является 10000 (десять секунд).
The following options are deprecated and should no longer be used:
"safe"
Устаревшая опция. Используйте опцию "w" контроля записи.
"timeout"
Устаревший псевдоним для "socketTimeoutMS".
"wtimeout"
Устаревший псевдоним для "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
Renamed the "timeout" option to
"socketTimeoutMS". Emits
Emits |
| 1.3.4 | Added "wtimeout" option. |
| 1.3.0 |
Added "w" option.
The |
| 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.
Исключение MongoCursorException бросается, если установлена опция "w" и не прошла запись.
Исключение MongoCursorTimeoutException бросается, если опция "w" установлена в значение больше одного и операция заняла больше, чем MongoCursor::$timeout миллисекунд. При этом операция на сервере не прерывается, так как это ограничение времени работает на клиентской стороне. Операция в миллисекундах в 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'));
?>