(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Crée un index sur un champ donné
$key|keys
[, array $options = array()
] )Cette méthode est obsolète depuis la version 1.5.0. Veuillez utiliser plutôt la méthode MongoCollection::createIndex().
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 :
"w"
Voir WriteConcerns. La valeur par défaut pour MongoClient est 1.
"unique"
Crée un index unique.
Un index unique ne peut être créé sur un champ si plusieurs
documents existants ne contiennent pas ce champ. Le champ sera NULL
pour ces documents et donc, non-unique. L'indexation clairsemé peut
être utilisée pour résoudre ce problème, sachant qu'elle évite d'indexer
les documents ne contenant pas ce champ.
"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.
"sparse"
Crée un index clairsemé, qui ne contient que les documents contenant le champ. Cette option n'est compatible qu'avec des indexes sur des champs seuls.
"expireAfterSeconds"
La valeur de cette option doit spécifier le nombre de secondes après lequel un document doit être considéré comme expiré, et doit être supprimé automatiquement de la collection. Cette option n'est compatible qu'avec des indexes sur des champs seuls où le champ contient des valeurs MongoDate.
Cette fonctionalité est disponible depuis MongoDB 2.2+. Pour plus d'informations, reportez-vous à la documentation sur l' » expiration de données depuis des collections en définissant un TTL.
"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.
"name"
Cette option vous permet d'écraser l'algorithme utilisé par le driver pour créer un nom d'index et de spécifier le votre. Ceci peut être utile si vous indexez plusieurs clés, et que Mongo vous alerte sur la taille trop grande des noms d'index.
"timeout"
Entier, par défaut, vaut MongoCursor::$timeout. Si la reconnaissance des écritures est utilisée, ceci va définir (en millisecondes) la durée d'attente du client d'une réponse de la base de données. Si la base de données ne répond pas durant cette période, une exception de type MongoCursorTimeoutException sera émise.
"safe"
Obsolète. Veuillez utiliser l'option w de WriteConcern w.
Retourne un tableau contenant le statut de création
de l'index si l'option "w" est défini.
Sinon, retourne TRUE.
Les champs dans le tableau de statut sont décrits dans la documentation de la méthode MongoCollection::insert().
| Version | Description |
|---|---|
| 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).
|
| 1.2.11 |
Lance une alerte de niveau E_DEPRECATED lorsque le
paramètre options est de type scalar.
|
| 1.2.0 | Ajout de l'option "timeout". |
| 1.0.11 |
L'option "safe" déclenchera le failover du primaire, si nécessaire. MongoException sera envoyée si le nom de l'index (généré ou défini) est plus long que 128 octets. |
| 1.0.5 | Ajout de l'option "name" pour écraser la création du nom de l'index. |
| 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.
|
Envoi MongoException si le nom de l'index est plus grand que 128 octets. (Version 1.0.11+)
Lance une exception MongoCursorException si l'option "w" est définie et que l'écriture échoue.
Lance une exception MongoCursorTimeoutException si l'option "w" est définie à une valeur supérieure à un, et que l'opération prend plus de temps que MongoCursor::$timeout millisecondes à se terminer. Ceci ne tue pas l'opération sur le serveur, c'est un délai d'attente maximal côté client. La mesure pour MongoCollection::$wtimeout est le milliseconde.
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"));
?>
La documentation de MongoDB concernant les» index et les » indexes géospatiales.