MongoCollection::ensureIndex
(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'));
?>
Смотрите также
- MongoCollection::createIndex() - Creates an index on the specified field(s) if it does not already exist.
- MongoCollection::deleteIndex() - Deletes an index from this collection
- MongoCollection::deleteIndexes() - Delete all indices for this collection
- The MongoDB » index and » index type documentation.
- PHP Руководство
- Функции по категориям
- Индекс функций
- Справочник функций
- Расширения для работы с базами данных
- Расширения для работы с базами данных отдельных производителей
- MongoDB
- Базовые классы
- Функция MongoCollection::aggregate() - Perform an aggregation using the aggregation framework
- Функция MongoCollection::aggregateCursor() - Execute an aggregation pipeline command and retrieve results through a cursor
- Функция MongoCollection::batchInsert() - Inserts multiple documents into this collection
- Функция MongoCollection::__construct() - Creates a new collection
- Функция MongoCollection::count() - Counts the number of documents in this collection
- Функция MongoCollection::createDBRef() - Creates a database reference
- Функция MongoCollection::createIndex() - Creates an index on the specified field(s) if it does not already exist.
- Функция MongoCollection::deleteIndex() - Deletes an index from this collection
- Функция MongoCollection::deleteIndexes() - Delete all indices for this collection
- Функция MongoCollection::distinct() - Retrieve a list of distinct values for the given key across a collection.
- Функция MongoCollection::drop() - Drops this collection
- Функция MongoCollection::ensureIndex() - Creates an index on the specified field(s) if it does not already exist.
- MongoCollection::find
- Функция MongoCollection::findAndModify() - Update a document and return it
- Функция MongoCollection::findOne() - Queries this collection, returning a single element
- Функция MongoCollection::__get() - Gets a collection
- Функция MongoCollection::getDBRef() - Fetches the document pointed to by a database reference
- Функция MongoCollection::getIndexInfo() - Returns information about indexes on this collection
- Функция MongoCollection::getName() - Returns this collection's name
- Функция MongoCollection::getReadPreference() - Get the read preference for this collection
- Функция MongoCollection::getSlaveOkay() - Get slaveOkay setting for this collection
- Функция MongoCollection::getWriteConcern() - Get the write concern for this collection
- Функция MongoCollection::group() - Performs an operation similar to SQL's GROUP BY command
- Функция MongoCollection::insert() - Inserts a document into the collection
- Функция MongoCollection::parallelCollectionScan() - Returns an array of cursors to iterator over a full collection in parallel
- Функция MongoCollection::remove() - Remove records from this collection
- Функция MongoCollection::save() - Saves a document to this collection
- Функция MongoCollection::setReadPreference() - Set the read preference for this collection
- Функция MongoCollection::setSlaveOkay() - Change slaveOkay setting for this collection
- Функция MongoCollection::setWriteConcern() - Set the write concern for this database
- Функция MongoCollection::toIndexString() - Converts keys specifying an index to its identifying string
- Функция MongoCollection::__toString() - String representation of this collection
- Функция MongoCollection::update() - Update records based on a given criteria
- Функция MongoCollection::validate() - Validates this collection
Коментарии
The statement<?php
$c->ensureIndex(array('x' => 1), array("unique" => true));
?>
will prevent a document with a duplicate key ('x') from being added to the connection, but will not throw an exception. To cause an exception to be thrown, use the "safe"=>true option in the insert statement.
Ensuring a text index, needed by text search command.
<?php
$collection->ensureIndex(
array(
'title' => 'text',
'desc' => 'text',
),
array(
'name' => 'ExampleTextIndex',
'weights' => array(
'title' => 100,
'desc' => 30,
)
)
);