[edit] Last updated: Fri, 25 May 2012

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex — Crée un index sur un champ donné

Description

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

Cette méthode crée un index sur la collection et les champs spécifiés. La spécification de la clé peut soit être un simple nom de champ sous la forme d'une chaîne de caractères, soit un tableau contenant un ou plusieurs noms de champs avec les directions de tri

Liste de paramètres

keys

Un tableau de champs utilisés pour trier l'index. Chaque élément du tableau contient un nom de champ comme clé, et la valeur devra être soit 1 pour un tri croissant, soit -1 pour un tri décroissant.

options

Ce paramètre est un tableau associatif sous la forme array("optionname" => <boolean>, ...). Actuellement, les options supportées sont :

"unique"

Crée un index unique.

Avertissement
Un index unique ne peut être créé sur un champ si plusieurs documents existants ne contiennent ce champ. Le champ sera NULL pour ces documents et donc, non-unique.
"dropDups"

Si un index unique est sur le point d'être créé et que les valeurs dupliquées existent, les valeurs existantes seront supprimées.
"background"

Si vous utilisez la version 1.3.2+ de MongoDB, vous pouvez créer des index en arrière plan pendant que d'autres opérations se déroulent. Par défaut, la création des index est synchrone. Si vous précisez TRUE à cette option, la création d'index sera asynchrone.
"safe"

Depuis la version 1.0.4 du driver, vous pouvez spécifier une valeur booléenne pour vérifier si la création de l'index a réussi. Le driver lancera une exception MongoCursorException si la création de l'index échoue.

Si vous utilisez la réplication et que le maitre a changé, utiliser "safe" fera que le pilote se déconnectera du maitre, enverra une exception, et tentera de trouver un nouveau maitre à l'opération suivante (votre application doit décider si oui ou non l'opération devra être rééssayée sur le nouveau maitre).

Si vous n'utilisez pas "safe" avec une paire de réplication et que le maitre change, il n'y aura aucun moyen pour le pilote d'avoir connaissance de ce changement et il continuera des écritures en échec.
"name"

Depuis la version 1.0.5 du driver, vous pouvez spécifier un nom d'index. Il peut être utile si vous indexez plusieurs clés et que Mongo signale que le nom de l'index est trop long.
"timeout"

Entier, par défaut, vaut MongoCursor::$timeout. Si "safe" est défini, il définira (en millisecondes) le temps d'attente du client d'une réponse de la base de données. Si la base de données ne répond pas dans la période de timeout, une exception MongoCursorTimeoutException sera émise.

Valeurs de retour

Returns TRUE.

Historique

Version	Description
1.0.2	Le paramètre "options" passe de booléen à un tableau. En version Pre-1.0.2, le second paramètre était une valeur booléenne optionnelle spécifiant un index unique.
1.0.11	"safe" déclenchera le failover du maitre, si nécessaire.
1.0.11	MongoException sera envoyée si le nom de l'index (généré ou défini) est plus long que 128 octets.
1.2.0	Ajout de l'option timeout.
1.3.0	Le paramètre `options` n'accepte plus que les booléens pour identifier un index unique. A la place, il peut contenir un tableau dont la syntaxe est la suivante : array('unique' => true).

Erreurs / Exceptions

Envoi MongoException si le nom de l'index est plus grand que 128 octets. (Version 1.0.11+)

Envoi MongoCursorException si l'option "safe" est utilisée et que la création d'index échoue.

Envoi une exception MongoCursorTimeoutException si l'option "safe" est définie et que l'opération prend plus de temps que MongoCollection::$wtimeout millisecondes. Ceci ne tue pas le processus serveur, mais uniquement le délai d'attente côté client.

Exemples

Exemple #1 Exemple avec MongoCollection::ensureIndex()


<?php

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

// Crée un index montant sur 'x'
$c->ensureIndex('x');

// Crée un index sur 'y' décroissant
$c->ensureIndex(array('y' => 1));

// Crée un index montant sur 'z' et descendant sur 'zz'
$c->ensureIndex(array('z' => 1, 'zz' => -1));

// Crée un index unique sur 'x'
$c->ensureIndex(array('x' => 1), array("unique" => true));
?>

Exemple #2 Exemple de suppression de données dupliquées


<?php

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

/*
 * La création d'index a échoué, vous ne pouvez pas créer d'index unique
 * sur une clé ne possédant pas de valeurs non-uniques
 */
$collection->ensureIndex(array("username" => 1), array("unique" => 1));

/*
 * La création d'index a réussi : un des documents est supprimé de la collection
 */
$collection->ensureIndex(array("username" => 1), array("unique" => 1, "dropDups" => 1));

/*
 * Maintenant que nous avons un index unique, les prochaines insertions
 * avec le même nom d'utilisateur (comme ci-dessous) échoueront
 */
$collection->insert(array("username" => "joeschmoe"));

?>

Exemple #3 Indexation géospatiales

Mongo supporte l'indexation géospatiales, vous permettant de chercher des documents se trouvant près d'un endroit donné, ou dans une forme. Par exemple, pour créer un index géospatial sur le champ "loc" :


<?php

$collection->ensureIndex(array("loc" => "2d"));

?>

Voir aussi

Documentation de MongoDB concernant les» index et les » indexes géospatiales.

add a note User Contributed Notes MongoCollection::ensureIndex

coffee dot stone at gmail dot com 17-Apr-2012 10:04


be careful when using ensureIndex('loc'=>'2d')



for example, if the data structure of loc is array('lng'=>120, 'lat'=>-30), when it is saved into database, its structure will be ['lat':-30, 'lng':120], it is because the array in PHP is the ordered map, not the order of literal in your code. so the 2d-index is mapped as (lat, lng). when you find your location with (lng, lat), the wrong results are returned.



be careful

alan dot lake at lakeinfoworks dot com 26-Aug-2010 10:45


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