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'));

?>

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

© 2008—2024 «phpm.ru | Документация и сервисы»       PHP | MySQL | Smarty | PEAR | PHP-GTK | Типограф | Сокращатель ссылок