MongoCollection::createIndex

(PECL mongo >=1.5.0)

MongoCollection::createIndex — Crea un índice en el campo o campos especificados, si aún no existen

Descripción

public MongoCollection::createIndex ( array $keys [, array $options = array() ] ) : bool

Crea un índice en el/los campo/s especificado/s si aún no existe. Los campos podrían estar indexados con una dirección (p.ej., ascendente o descendente) o un tipo especial (p.ej., texto, geoespacial, hash).

Nota:

Este método utilizará el comando de base de datos » createIndexes al comunicarse con MongoDB 2.6+. Para versiones anteriores de bases de datos, este método realizará una operación de inserción en la colección especial system.indexes.

Parámetros

keys

Un array que tiene como claves los campos de índice. Para cada campo, el valor es la dirección del índice o el » tipo de índice. Si se especifica la dirección, se ha de indicar 1 para ascendente o -1 para descendente.

options

Un array de opciones para la creación del índice. Se pasan todas las opciones dadas directas al servidor, aunque se muestra una lista no exhaustiva de las opciones actualmente disponibles:

  • "unique"

    Especificar TRUE para crear un índice único. El valor predeterminado es FALSE. Esta opción se aplica únicamente a índices ascendentes/descendentes.

    Nota:

    Cuando MongoDB indexa un campo, si un documento no tiene un valor para dicho campo, se indexará un valor NULL. Si varios documentos no contienen un campo, un índice único rechazará todos excepto el primero de dichos documentos. La opción "sparse" podría usarse para superar esto, ya que prevendrá de que sean indexados los documentos sin tal campo.

  • "dropDups"

    Especificar TRUE para forzar la creación de un índice único donde la colección podría contener valores duplicados para una clave. MongoDB indexará la primera aparición de una clave y borrará todos los documentos subsiguientes de la colección que contengan un valor duplicado para dicha clave. El valor predeterminado es FALSE.

    Advertencia

    "dropDups" podría borrar datos de la base de datos. Úselo con extrema precaución.

    Nota:

    Esta opción no está soportada por MongoDB 2.8+. La creación del índice fallará si la colección contiene valores duplicados.

  • "sparse"

    Especificar TRUE para crear un índice disperso, el cual solamente indexa documentos que contienen un campo específico. El valor predeterminado es FALSE.

  • "expireAfterSeconds"

    El valor de esta opción debería especificarel número de segundos tras los cuales debería un documento ser considerado expirado y automáticamente eliminaod de la colección. Esta opción solamente es compatible con índices de campo único donde el campo contendrá valores MongoDate.

    Nota:

    Esta característica está disponible en MongoDB 2.2+. Véase » Expirar datos de colecciones estableciendo el TTL para más información.

  • "name"

    Un nombre opcional que identifica de forma única al índice.

    Nota:

    Por omisión, el controlador generará un nombre de índice basado en el/los campo/s del índice y el orden o tipo. Por ejemplo, un índice compuesto array("x" => 1, "y" => -1) would be named "x_1_y_-1" and a geospatial index array("loc" => "2dsphere") se llamaría "loc_2dsphere". Para índices con muchos campos, es posible que el nombre generado pueda exceder el » límite para nombres de índices de MongoDB. Se podría usar la opción "name" en tal caso para proporcionar un nombre más corto.

  • "socketTimeoutMS"

    Esta opción especifica el tiempo límite, en milisegundos, para las comunicaciones con socket. Si el servidor no responde en el periodo especificado, se lanzará una MongoCursorTimeoutException y no habrá forma de determinar si el servidor manejó realmente la escritura o no. Se podría especificar un valor de -1 para bloquear indefinidamente. El valor predeterminado para MongoClient es 30000 (30 segundos).

La siguiente opción podría usarse con MongoDB 2.6+:

  • "maxTimeMS"

    Especifica un tiempo límite acumulativo en milisegundos para procesar la operación en el servdiro (no incluye el tiempo improductivo). Si la operación no la completa el servidor dentro del período de tiempo límite, se lanzará una MongoExecutionTimeoutException.

Las siguientes opciones podrían usarse con versiones de MongoDB anteriores a la 2.8:

  • "dropDups"

    Especificar TRUE para forzar la creación de un índice único donde la colección podría contener valores duplicados para una clave. MongoDB indexará la primera aparición de una clave y borrará todos los documentos subsiguientes de la colección que contengan un valor duplicado para dicha clave. El valor predeterminado es FALSE.

    Advertencia

    "dropDups" podría borrar datos de la base de datos. Úselo con extrema precaución.

    Nota:

    Esta opción no está soportada por MongoDB 2.8+. La creación del índice fallará si la colección contiene valores duplicados.

Las siguientes opciones podrían usarse con versiones de MongoDB anteriores a la 2.6:

  • "w"

    Véase WriteConcerns. El valor predeterminado de MongoClient es 1.

  • "wTimeoutMS"

    Esta opción especifica el tiempo límite, en milisegundos, para el reconocimiento de un asunto de escritura. Solamente es aplicable cuando "w" sea mayor que 1, ya que el tiempo de espera está relacionado con la replecación. Si el asunto de escritura no se satisface dentro del tiempo límite, se lanzará una MongoCursorException. Se puede especificar un valor de 0 para bloquear indefinidamente. El valor predeterminado es 10000 (diez segundos).

Las siguientes opciones están obsoletas y no deberían usarse más:

  • "safe"

    Obsoleto. Use la opción w de los asuntos de escritura.

  • "timeout"

    Alias obsoleto de "socketTimeoutMS".

  • "wtimeout"

    Alias obsoleto de "wTimeoutMS".

Valores devueltos

Devuelve un array que contiene el estado de la creación del índice. El array contiene si la operación tuvo éxito ("ok"), el número de índices antes y después de la operación ("numIndexesBefore" y "numIndexesAfter"), y si la colección a la que pertenece el índice ha sido creada ("createdCollectionAutomatically"). Si el índice ya existe y no fue necesario crearlo, podría estar presente el campo "note" en lugar de "numIndexesAfter".

Con MongoDB 2.4 y anteriores, solamente se devolvía un documento de estado si el asunto de escritura es al menos 1. De lo contrario devuelve TRUE. Los campos del documento de estado son diferentes, excepto por el campo "ok", el cual describe si la creación del índice tuvo éxito. Los campos adicionales están descritos en la documentación de MongoCollection::insert().

Errores/Excepciones

Lanza una MongoException si el nombre del índice es mayor de 128, o si la especificación del índice no es un array.

Lanza una MongoDuplicateKeyException si el servidor no pudo crear el índice único debido a documentos conflictivos.

Lanza una MongoResultException si el servidor no pudo crear el índice debido a un error.

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 límite del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::ensureIndex()

<?php

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

// crear un índice sobre 'x' ascendente
$c->ensureIndex(array('x' => 1));

// crear un índice único sobre 'y'
$c->ensureIndex(array('y' => 1), array('unique' => true));

// crear un índice compuesto sobre 'za' ascendente y 'zb' descendente
$c->ensureIndex(array('za' => 1, 'zb' => -1));

?>

Ejemplo #2 Indexación geoespacial

Mongo soporta índices geoespaciales, los cuales 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

$colección->ensureIndex(array("loc" => "2d"));

?>

Ejemplo #3 Ejemplo de eliminación de duplicados

<?php

$colección->insert(array('nombreUsuario' => 'joeschmoe'));
$colección->insert(array('nombreUsuario' => 'joeschmoe'));

/* Falla la creación del índice; no se puede crear un índice único en un campo
 * cuando existen duplicados.
 */
$colección->ensureIndex(array('nombreUsuario' => 1), array('unique' => 1));

/* MongoDB uno de los documentos conflictivos y permitirá la creación del
 * índice único.
 */
$colección->ensureIndex(array('nombreUsuario' => 1), array('unique' => 1, 'dropDups' => 1));

/* Ahora tenemos un índice único, por lo que las inserciones subsiguientes con el
 * mismo nombre de usuario fallarán.
 */
$colección->insert(array('nombreUsuario' => 'joeschmoe'));

?>

Ver también