PHP 8.0.6 Released!

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex Создаёт индекс для указанных полей, если он ещё не существует

Описание

public MongoCollection::ensureIndex ( string|array $key|keys , array $options = array() ) : bool
Внимание

Этот метод устарел с версии 1.5.0. Пожалуйста, используйте MongoCollection::createIndex() вместо этого.

Создаёт индекс для указанных полей, если он ещё не существует. Поля могут быть проиндексированы с направлением (например, по возрастанию или по убыванию) или специальным типом (например, текст, геопространственный, хешированный).

Замечание:

Этот метод будет использовать команду базы данных » createIndexes при взаимодействии с MongoDB 2.6+. ля предыдущих версий базы данных метод выполняет операцию вставки в специальную коллекцию system.indexes.

Список параметров

keys

Массив, определяющий поля индекса в качестве его ключей. Для каждого поля значением является либо направление индекса, либо » тип индекса. Если указано направление, укажите 1 для возрастания или -1 для убывания.

options

Массив опций для создания индекса. В настоящее время доступны следующие варианты:

  • "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 секунд).

Следующая опция может использоваться с MongoDB 2.6+:

  • "maxTimeMS"

    Указывает суммарный лимит времени в миллисекундах на обработку операции (не включая время простоя) на сервере. Если операция на стороне сервера не завершилась за это время, то вызывается исключение MongoExecutionTimeoutException.

Следующие опции могут использоваться с версиями MongoDB до 2.8:

  • "dropDups"

    Укажите true для принудительного создания уникального индекса, где коллекция может содержать одинаковые значения для ключа. MongoDB будет индексировать первое вхождение ключа и удалять все последующие документы из коллекции, которые содержат такие же значения для ключа. Значение по умолчанию - false.

    Внимание

    "dropDups" может удалить данные из вашей базы данных. Используйте с особой осторожностью.

    Замечание:

    Эта опция не поддерживается в MongoDB 2.8+. Создание индекса не выполнится, если коллекция содержит одинаковые значения.

Следующие параметры могут использоваться с версиями MongoDB до 2.6:

  • "w"

    Смотрите Контроль записи. Значение по умолчанию для MongoClient является 1.

  • "wTimeoutMS"

    Эта опция определяет лимит времени в миллисекундах для подтверждения контроля записи. Она применима только, если "w" больше 1, так как ограничение времени относится к репликации. Если контроль записи не подтверждён за отведённое время, то будет выброшено исключение MongoCursorException. Значение 0 для постоянного отключения. Значением по умолчанию для MongoClient является 10000 (десять секунд).

Следующие параметры устарели и больше не должны использоваться:

  • "safe"

    Устаревшая опция. Используйте опцию "w" контроля записи.

  • "timeout"

    Устаревший псевдоним для "socketTimeoutMS".

  • "wtimeout"

    Устаревший псевдоним для "wTimeoutMS".

Возвращаемые значения

Возвращает массив, содержащий состояние создания индекса. В массиве указывается, была ли операция выполнена успешно ("ok"), количество индексов до и после операции ("numIndexesBefore" и "numIndexesAfter"), а также была ли создана коллекция, которой принадлежит индекс ("createdCollectionAutomatically"). Если индекс уже существует и его не нужно создавать, вместо "numIndexesAfter" может присутствовать поле "note".

В MongoDB 2.4 и более ранних версиях документ о статусе возвращается только в том случае, если гарантии записи равны как минимум 1. В противном случае возвращается true. Поля в документе состояния отличаются, за исключением поля "ok", которое указывает, было ли создание индекса успешным. Дополнительные поля описаны в документации для MongoCollection::insert().

Список изменений

Версия Описание
PECL mongo 1.5.0

Переименован параметр "wtimeout" в "wTimeoutMS". Выдаёт E_DEPRECATED, когда используется "wtimeout".

Переименован параметр "timeout" в "socketTimeoutMS". Выдаёт E_DEPRECATED, когда используется "timeout".

Выдаёт E_DEPRECATED, когда используется "safe".

PECL mongo 1.3.4 Добавлена опция "wtimeout".
PECL mongo 1.3.0

Добавлена опция "w".

Параметр options больше не принимает логическое значение для обозначения уникального индекса. Вместо этого это теперь должно быть передано array('unique' => true).

PECL mongo 1.2.11 Выдаёт E_DEPRECATED, когда options являются скалярными.
PECL mongo 1.2.0 Добавлена опция "timeout".
PECL mongo 1.0.11

Опция "safe" запускает первичное аварийное переключение, если это необходимо.

MongoException будет выброшено, если имя индекса (либо сгенерированное, либо установленное) длиннее 128 байт.

PECL mongo 1.0.5 Добавлена опция "name" для переопределения создания имени индекса.
PECL mongo 1.0.2 Изменён параметр options с логического на массив. До версии 1.0.2 вторым параметром было необязательное логическое значение, указывающее уникальный индекс.

Ошибки

Выдаёт исключение MongoException, если имя индекса длиннее 128 байт или если спецификация индекса не является массивом.

Выдаёт исключение MongoDuplicateKeyException, если серверу не удалось создать уникальный индекс из-за конфликтующих документов.

Выдаёт исключение MongoResultException, если серверу не удалось создать индекс из-за ошибки.

Исключение MongoCursorException бросается, если установлена опция "w" и не прошла запись.

Исключение MongoCursorTimeoutException бросается, если опция "w" установлена в значение больше одного и операция заняла больше, чем MongoCursor::$timeout миллисекунд. При этом операция на сервере не прерывается, так как это ограничение времени работает на клиентской стороне. Операция в миллисекундах в MongoCollection::$wtimeout.

Примеры

Пример #1 Пример использования MongoCollection::ensureIndex()

<?php

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

// создаём индекс по возрастанию на 'х'
$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));

/* MongoDB будет одним из конфликтующих документов
/* и позволит создать уникальный индекс.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1'dropDups' => 1));

/* Теперь у нас есть уникальный индекс, и последующие вставки
/* с тем же именем пользователя завершатся неудачно.
 */
$collection->insert(array('username' => 'joeschmoe'));

?>

Смотрите также

add a note add a note

User Contributed Notes 2 notes

up
1
mcuadros at gmail dot com
8 years ago
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,
        )
    )
);
up
0
alan dot lake at lakeinfoworks dot com
10 years ago
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.
To Top