(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Crea un índice en el/los campo/s dado/s, 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 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:
"w"
Véase WriteConcerns. El valor predeterminado de MongoClient es 1.
"unique"
Crea un índice único.
No se puede crear un índice único en un campo si los distintos documentos
existentes no contienen dicho campo. Este es efectivamente NULL
para estos documentos y, por lo tanto, ya es no único. Se podría utilizar
indexación fluida para superar este problema, ya que prevendrá que los documentos sin
dicho cambo sean indexados.
"dropDups"
Si se estuviera creando un índice único, y existieran valores duplicados, borrar todos excepto uno de ellos.
"sparse"
Crea un índice fluido, el cual únicamente incluye documentos que contiene el campo. Esta opción solamente es compatible con índices de campo sencillo.
"expireAfterSeconds"
El valor de esta opciión debería especificar el número de segundos transcurridos para que un documento sea considerado como expirado y sea automáticamente eliminado de la colección. Esta opción solamente es compatible con índices de campo sencillo donde el campo contiene valores MongoDate.
Esta característica está disponible en MongoDB 2.2+. Véase » Expirar datos de colecciones estableciendo el TTL para más información.
"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.
"name"
Esta opción permite sobrescribir el algoritmo que usa el controlador para crear un nombre de índice y especificar el propio. Puede ser útil si se están indexando varias claves y Mongo reclama que el nombre del índice es muy extenso.
"timeout"
Entero, valor predeterminado MongoCursor::$timeout. Si se usan las escrituras reconocidas, esto estable cuánto debe esperar el cliente (en milisegundos) a una respuesta de la base de datos. Si la base de datos no responde dentro de perído de espera, se lanzará una MongoCursorTimeoutException.
"safe"
Obsoleto. Use la opción w de WriteConcern.
Devuelve un array que contiene el estado de la creación del índice si la
opción "w" está establecida. De lo contrario, devuelve TRUE.
Los campos del array de estado están descritos en la documentación de MongoCollection::insert().
| Versión | Descripció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).
|
| 1.2.11 |
Emite un error de nivel E_DEPRECATED cuando
options es de tipo scalar.
|
| 1.2.0 | Se añadió la opción "timeout". |
| 1.0.11 |
La opción "safe" desencadenará una tolerancia a fallos en el primario, si fuera necesario. Se lanzará una MongoException si el nombre del índice (generado o establecido) es mayor que 128 bytes. |
| 1.0.5 | Se añadió la opción "name" para sobrescribir la creación del nombre del índice. |
| 1.0.2 |
Cambiado el parámetro options de booleano a array.
Antes de la versión 1.0.2, el segundo parámetro era un valor booleano opcional que
especificaba si era o no un índice único.
|
Lanza MongoException si el nombre de índice es superior a 128 bytes. (Versión 1.0.11+)
Lanza una MongoCursorException si la opción "w" está establecida y la escritura falla.
Lanza una MongoCursorTimeoutException si la opción "w" está establecida a un valor mayor que uno y la operación toma más de MongoCursor::$timeout milisegundos en completarse. Esto no pondrá fin a la operación en el servidor, es un tiempo de espera del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.
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.