(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Crée un index sur un champ donné
$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
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.
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"
Par défaut, la création de l'index est une opération bloquante
et stoppera les autres opérations sur la base de données tant
que la création ne sera pas terminée. Si vous positionnez cette
option à TRUE, l'index sera créé en arrière-plan et les autres
opérations pourront continuer normalement.
Avant la version 2.1.0 de MongoDB, l'opération de création d'index n'est pas une opération d'arrière-plan lorsqu'elle réplique vers les secondaires, quelque soit la valeur de cette option. Voir le chapitre sur » la construction des indexes avec des jeux de réplication pour plus d'informations.
"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.
Returns TRUE.
| 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.2.11 |
Lance une alerte de niveau E_DEPRECATED lorsque le
paramètre options est de type scalar.
|
| 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).
|
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.
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"));
?>
Documentation de MongoDB concernant les» index et les » indexes géospatiales.