MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex — Creates an index on the specified field(s) if it does not already exist

Descrierea

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

This method is deprecated since version 1.5.0. Please use MongoCollection::createIndex() instead.

Creates an index on the specified field(s) if it does not already exist. Fields may be indexed with a direction (e.g. ascending or descending) or a special type (e.g. text, geospatial, hashed).

Notă:

This method will use the » createIndexes database command when communicating with MongoDB 2.6+. For previous database versions, the method will perform an insert operation on the special system.indexes collection.

Parametri

keys

An array specifying the index's fields as its keys. For each field, the value is either the index direction or » index type. If specifying direction, specify 1 for ascending or -1 for descending.

options

An array of options for the index creation. Currently available options include:

  • "unique"

    Specificați TRUE pentru a crea un indice unic. Valoarea implicită este FALSE. Această opțiune se aplică doar pentru indici ascendenți/descendenți.

    Notă:

    Când MongoDB indexează un câmp, dacă un document nu are valoare pentru acel câmp, o valoare NULL este indexată. Dacă mai multe documente nu conțin câmpul, un indice unic va respinge toate documentele în afară de primul. Opiunea "sparse" poate fi utilizată pentru a depăși aceasta, deoarece ea va preveni indexarea documentelor fără valoarea câmpului.

  • "sparse"

    Specificați TRUE pentru a crea un indice distribuit, ce indexează doar documente ce conțin un anumit câmp. Valoarea implicită e FALSE.

  • "expireAfterSeconds"

    Valoarea acestei opțiuni ar trebui să specifice numărul de secunde după care un document ar trebui să fie considerat expirat și automat eliminat din colecție. Această opțiune este compatibilă doar cu indici pe un singur câmp, unde câmpul va conține valori MongoDate.

    Notă:

    Această facilitate este disponibilă în MongoDB 2.2+. A se vedea » Expirarea Datelor din Colecții prin Stabilirea TTL pentru informații suplimentare.

  • "name"

    Un nume opțional care identifică univoc indicele.

    Notă:

    Implicit driver-ul va genera un nume al indicelui bazat pe câmpurile lui și ordinea de sortare sau tip. De exemplu, un indice compus array("x" => 1, "y" => -1) va fi numit "x_1_y_-1" și un indice geospațial array("loc" => "2dsphere") va fi numit "loc_2dsphere". Pentru indici cu mai multe câmpuri este posibil ca numele generat să depășească » limita pentru denumirile indicilor din MongoDB. Opțiunea "name" poate fi folosită în acest caz pentru a furniza un nume mai scurt.

  • "background"

    Calculează indicele în fundal, pentru ca aceasta să nu blocheze alte activități ale bazei de date. Specificați TRUE pentru a calcula în fundal. Valoarea implicită e FALSE.

    Avertizare

    Înainte de MongoDB 2.6.0, calculele indicilor erau executate ca operațiuni în prim plan, indiferent de această opțiune. A se vedea » Calcularea Indicilor cu Seturi de Replici pentru informații suplimentare.

  • "socketTimeoutMS"

    Această opțiune specifică limita de timp în milisecunde pentru comunicarea prin socket. Dacă serverul nu răspunde în limita intervalului de timp, se va emite o MongoCursorTimeoutException și nu va fi nici o posibilitate de a determina dacă serverul a efectuat înscrierea, sau nu. Valoarea -1 poate fi specificată pentru a suspenda pentru o perioadă nedefinită. Valoarea implicită pentru MongoClient este 30000 (30 secunde).

The following option may be used with MongoDB 2.6+:

  • "maxTimeMS"

    Specifică o limită de timp cumulativă în milisecunde pentru procesarea operațiunii pe server (nu include timpul de așteptare). Dacă operațiunea nu este terminată pe server în timpul rezervat, va fi emisă o MongoExecutionTimeoutException.

The following options may be used with MongoDB versions before 2.8:

  • "dropDups"

    Specificați TRUE pentru a forța crearea unui indice unic, când colecția poate conține dubluri pentru o cheie. MongoDB va indexa prima apariție a cheii și va elimina toate documentele din colecție care conțin următoarele apariții ale acelei chei. Valoarea implicită e FALSE.

    Avertizare

    "dropDups" poate să elimine date din baza dumneavoastră de date. Folosiți cu mare precauție.

    Notă:

    Această opțiune nu este susținută de MongoDB 2.8+. Crearea indicelui va eșua dacă colecția conține dubluri.

The following options may be used with MongoDB versions before 2.6:

  • "w"

    Vedeți WriteConcerns. Valoarea implicită pentru MongoClient este 1.

  • "wTimeoutMS"

    Această opțiune specifică limita de timp în milisecunde pentru confirmarea write concern. Aceasta este aplicabilă doar atunci când "w" este mai mare decât 1, deoarece expirarea timpului ține de replicare. Dacă "write concern" nu este satisfăcută în limita intervalului de timp, se va emite o MongoCursorException. Valoarea 0 poate fi specificată pentru a suspenda pentru o perioadă nedefinită. Valoarea implicită pentru MongoClient este 10000 (zece secunde).

The following options are deprecated and should no longer be used:

  • "safe"

    Învechită. Utilizați opțiunea WriteConcern w.

  • "timeout"

    Un pseudonim învechit pentru "socketTimeoutMS".

  • "wtimeout"

    Un pseudonim învechit pentru "wTimeoutMS".

Valorile întoarse

Returns an array containing the status of the index creation. The array contains whether the operation succeeded ("ok"), the number of indexes before and after the operation ("numIndexesBefore" and "numIndexesAfter"), and whether the collection that the index belongs to has been created ("createdCollectionAutomatically"). If the index already existed and did not need to be created, a "note" field may be present in lieu of "numIndexesAfter".

With MongoDB 2.4 and earlier, a status document is only returned if the write concern is at least 1. Otherwise, TRUE is returned. The fields in the status document are different, except for the "ok" field, which signals whether the index creation was successful. Additional fields are described in the documentation for MongoCollection::insert().

Istoricul schimbărilor

Versiune Descriere
1.5.0

Renamed the "wtimeout" option to "wTimeoutMS". Emits E_DEPRECATED when "wtimeout" is used.

Renamed the "timeout" option to "socketTimeoutMS". Emits E_DEPRECATED when "timeout" is used.

Emits E_DEPRECATED when "safe" is used.

1.3.4 Added "wtimeout" option.
1.3.0

Added "w" option.

The options parameter no longer accepts a boolean to signify a unique index. Instead, this now has to be done with array('unique' => true).

1.2.11 Emits E_DEPRECATED when options is scalar.
1.2.0 Added "timeout" option.
1.0.11

The "safe" option will trigger a primary failover, if necessary.

MongoException will be thrown if the index name (either generated or set) is longer than 128 bytes.

1.0.5 Added the "name" option to override index name creation.
1.0.2 Changed options parameter from boolean to array. Pre-1.0.2, the second parameter was an optional boolean value specifying a unique index.

Erori/Excepții

Throws MongoException if the index name is longer than 128 bytes, or if the index specification is not an array.

Throws MongoDuplicateKeyException if the server could not create the unique index due to conflicting documents.

Throws MongoResultException if the server could not create the index due to an error.

Generează o excepție MongoCursorException dacă opțiunea "w" este stabilită și înscrierea eșuează.

Generează o excepție MongoCursorTimeoutException dacă opțiunea "w" este stabilită la o valoare mai mare decât unu și operațiunea durează mai mult de MongoCursor::$timeout milisecunde. Aceasta nu va întrerupe operațiunea pe server, este un timeout de partea clientului. Operațiunea din MongoCollection::$wtimeout este în milisecunde.

Exemple

Example #1 MongoCollection::ensureIndex() example

<?php

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

// create an index on 'x' ascending
$c->ensureIndex(array('x' => 1));

// create a unique index on 'y'
$c->ensureIndex(array('y' => 1), array('unique' => true));

// create a compound index on 'za' ascending and 'zb' descending
$c->ensureIndex(array('za' => 1, 'zb' => -1));

?>

Example #2 Geospatial Indexing

Mongo supports geospatial indexes, which allow you to search for documents near a given location or within a shape. The following example creates a geospatial index on the "loc" field:

<?php

$collection->ensureIndex(array('loc' => '2dsphere'));

?>

Example #3 Drop duplicates example

<?php

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

/* Index creation fails, since you cannot create a unique index on a field when
 * duplicates exist.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1));

/* MongoDB will one of the conflicting documents and allow the unique index to
 * be created.
 */
$collection->ensureIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));

/* We now have a unique index and subsequent inserts with the same username will
 * fail.
 */
$collection->insert(array('username' => 'joeschmoe'));

?>

A se vedea și