MongoCollection
PHP Manual

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex Crea un índice en el campo o cmapos dados, o si el índice ya existe, no realiza nada.

Descripción

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

Este método crea un índice en la colección y los campos especificados. Al especificar la clave (parámetro keys) se puede o bien proporcionar un nombre de campo en forma de string, o un array que contenga uno o más nombres de campo con su sentido de ordenación.

Parámetros

keys

Array que contiene los campos por los que se ordenará el índice. Cada elemento del array tiene como clave el nombre del campo, y como valor, o bien 1 para orden ascendente, o bien -1 para orden desendente.

options

Este parámetro es un array asociativo de la forma array("nombredeopcion" => <boolean>, ...). Las opciones soportadas actualmente son:

  • "unique"

    Crea un índice único.

    Advertencia

    No se puede crear un índice único en un campo si los distintos docuemntos no contiene este campo. En estos documentos el campo sería NULL y por tanto no sería un valor único.

  • "dropDups"

    Si se estuviera creando un índice único, y existieran valores duplicados, borrar todos excepto uno de ellos.

  • "background"

    De manera predeterminada, la creación de un índice es una operación de bloqueo que detendrá otras operaciones sobre la base de datos hasta que sea completada. Si se especifica TRUE para esta opción, el índice se creará en segundo plano mientras toman lugar otras operaciones.

    Advertencia

    Antes de MongoDB 2.1.0, la operación de construcción de un índice no estaba en segundo plano cuando replicaba a secundarios, sin tener en cuenta esta opción. See » Building Indexes with Replica Sets for more information.

  • "safe"

    Desde la versión 1.0.4 del driver, se puede indicar mediante un booleano si se comprobará si ha habido o no éxito creando el índice. Si fallara la creación del índice, el driver emitiría una excepción de tipo MongoCursorException.

    Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro).

    Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará.

  • "name"

    Desde la versión 1.0.5 de driver, se peude especificar el nombre del índice. Puede ser muy útil si se están indexando varias claves y Mongo emite alertas porque el nombre del índice es muy extenso.

  • "timeout"

    Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto tiempo (en milisegundos) esperará el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Devuelve TRUE.

Historial de cambios

Versión Descripción
1.0.2 Cambiado el parámetro "options" de booleano a array. Antes de 1.0.2, el segundo parámetro era un booleano opcional que especificaba si era o no un índice único.
1.0.11 "safe" emitirá fallos del maestro, cuando proceda.
1.0.11 Se lanza MongoException si el nombre de índice (generado o asignado) es superior a 128 bytes.
1.2.0 Añadida la opción timeout (tiempo de expiración).
1.3.0 El parámetro options ya no acepta un booleano para identificar un índice único. En su lugar, ahora debe hacerse con array('unique' => true).

Errores/Excepciones

Lanza MongoException si el nombre de índice es superior a 128 bytes. (Versión 1.0.11+)

Lanza MongoCursorException si la opción "safe" está habilitada y falla la creación del índice.

Lanza MongoCursorTimeoutException si la opción "safe" está habilitada y la operación lleva más de MongoCursor::$timeout milisegundos para ser completada. Esto no paraliza la operación en el servidor, es sólo un límite de tiempo en el lado del cliente.

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::ensureIndex()

<?php

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

// crea un índice en 'x' ascendente
$c->ensureIndex('x');

// crea un índice en 'y' ascendente
$c->ensureIndex(array('y' => 1));

// crea un índice en 'z' ascendente y en 'zz' descendente
$c->ensureIndex(array('z' => 1'zz' => -1));

// crea un índice único en 'x'
$c->ensureIndex(array('x' => 1), array("unique" => true));

?>

Ejemplo #2 Ejemplo de borrado de duplicados

<?php

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

/*
 * falla la creación del índice; no se puede crear un índice único en una clave que no tiene
 * valores únicos
 */
$collection->ensureIndex(array("username" => 1), array("unique" => 1));

/*
 * éxito al crear índice: se ha eliminado uno de los documentos de la colección
 */
$collection->ensureIndex(array("username" => 1), array("unique" => 1"dropDups" => 1));

/* 
 * ahora tenemos un índice único, por lo que las inserciones con el mismo username (como el
 * anterior) fallarán
 */
$collection->insert(array("username" => "joeschmoe"));

?>

Ejemplo #3 Indexación Geoespacial

Mongo soporta índices geoespaciales, que permiten buscar documentos cercanos a una determinada localización o que estén dentro de una determinada forma. Por ejemplo, para crear un índice geoespacial en el campo "loc":

<?php

$collection
->ensureIndex(array("loc" => "2d"));

?>

Ver también

Documentación de MongoDB sobre » índices por defecto y sobre » índices geoespaciales.


MongoCollection
PHP Manual