(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.
$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.
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.
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.
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.
Devuelve TRUE
.
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).
|
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.
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"));
?>
Documentación de MongoDB sobre » índices por defecto y sobre » índices geoespaciales.