Edit Report a Bug

    MongoCollection::ensureIndex

    (PECL mongo >=0.9.0)

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

    Descripción

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

    Este método está obsoleto desde la versión 1.5.0. Use MongoCollection::createIndex() en su lugar.

    Crea un índice con el campo o campos especificados si aún no existen. Los campos podría indexarse con una dirección (p.ej., ascendente o descendente) o un tipo especial (p.ej., texto, geoespacial, de tipo 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. Las opciones actualmente disponibles son:

    • "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.

    • "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.

    • "background"

      Construye el índice en segundo plano para no bloquear otras actividades de la base de datos. Especificar TRUE para la construcción en segundo plano. El valor predeterminado es FALSE.

      Advertencia

      Antes de MongoDB 2.6.0, la construcción de índices en secundarios era ejecutada como operaciones de primer plano, independientemente de esta opción. Véase » Construir índices con Conjuntos de Réplica para más información.

    • "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().

    Historial de cambios

    Versión Descripción
    1.5.0

    Se renombró la opción "wtimeout" a "wTimeoutMS". Emite un error de nivel E_DEPRECATED cuando se usa "wtimeout".

    Se renombró la opción "wtimeout" a "socketTimeoutMS". Emite un error de nivel E_DEPRECATED cuando se usa "timeout".

    Emite un error de nivel E_DEPRECATED cuando se usa "safe".

    1.3.4 Se añadió la opción "wtimeout".
    1.3.0

    Se añadió la opción "w".

    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 Se cambió 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.

    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

    add a note add a note

    User Contributed Notes 2 notes

    up
    1
    mcuadros at gmail dot com
    11 years ago
    Ensuring a text index, needed by text search command.

    <?php
    $collection    ->ensureIndex(
        array(
                'title' => 'text',
                'desc' => 'text',
        ),
        array(
                'name' => 'ExampleTextIndex',
                'weights' => array(
                    'title' => 100,
                    'desc' => 30,
            )
        )
    );
    up
    0
    alan dot lake at lakeinfoworks dot com
    14 years ago
    The statement
    <?php
    $c    ->ensureIndex(array('x' => 1), array("unique" => true));
    ?>
    will prevent a document with a duplicate key ('x') from being added to the connection, but will not throw an exception.  To cause an exception to be thrown, use the "safe"=>true option in the insert statement.
    add a note add a note
    To Top