(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Crée un index sur le ou les champs spécifiés s'il n'existe pas déjà
$key|keys
[, array $options = array()
] ) : boolCette méthode est obsolète depuis la version 1.5.0. Veuillez utiliser plutôt la méthode MongoCollection::createIndex().
Crée un index sur le ou les champs spécifiés s'il n'existe pas déjà. Les champs peuvent être indexés avec une direction (i.e. croissant ou décroissant) ou avec un type spécial (e.g. text, geospatial, hashed).
Note:
Cette méthode utilisera la commande de base de données » createIndexes lors de la communication avec MongoDB 2.6+. Pour les versions antérieures de bases de données, la méthode va effectuer une opération d'insertion sur la collection spéciale system.indexes.
keys
Un tableau spécifiant les champs d'index comme clés. Pour chaque champ, la valeur est soit la direction de l'index, soit le » type d'index. Si la direction est spécifiée, vous devez utiliser 1 pour le sens croissant, ou -1 pour le sens décroissant.
options
Un tableau d'options pour la création de l'index. Les options actuellement disponibles sont :
"unique"
Spécifiez TRUE pour créer un index unique. La valeur par défaut est FALSE. Cette option s'applique uniquement sur les indexes croissants/décroissants.
Note:
Lorsque MongoDB indexe un champ, si un document n'a pas une valeur pour ce champ, la valeur
NULLsera indexée. Si plusieurs documents ne contiennent pas un champ, un index unique rejètera tout, sauf le premier de ces documents. L'option "sparse" peut être utilisée pour remédier à cela, sachant qu'il va éviter que les documents ne contenant pas ce champ ne soient indexés.
"sparse"
Spécifiez TRUE pour créer un index clairsemé, qui n'indexe que des documents contenant un champ spécifié. La valeur par défaut est FALSE.
"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 automatiquement supprimé de la collection. Cette option n'est compatible qu'avec des indexes sur un seul champ où le champ contient une valeur MongoDate.
Note:
Cette fonctionnalité est disponible depuis MongoDB 2.2+. Voir » l'expiration des données d'une collection en définissant un TTL pour plus d'informations.
"name"
Un nom optionnel qui identifie de façon unique l'index.
Note:
Par défaut, le driver va générer un nom d'index basé sur le(s) champ(s) d'index, leur tri, ou leur type. Par exemple, un index calculé array("x" => 1, "y" => -1) sera nommé "x_1_y_-1" et un index géospacial array("loc" => "2dsphere") sera nommé "loc_2dsphere". Pour les indexes avec beaucoup de champs, il est possible que le nom généré puisse excéder la » limite des noms d'index MongoDB. L'option "name" peut être utilisée dans ce cas pour fournir un nom plus court.
"background"
Construit l'index en arrière plan faisant ainsi que la construction de l'index ne bloquera pas les autres activités de la base de données. Spécifiez TRUE pour une construction en arrière plan. La valeur par défaut est FALSE.
Avant MongoDB 2.6.0, les constructions d'index sur les secondaires étaient exécutés comme des opérations de premier plan, sans respecter cette option. Voir » la construction d'index sur les jeux de réplication pour plus d'informations.
"socketTimeoutMS"
Cette option spécifie la durée limite, en millisecondes, pour la communication avec un socket. Si le serveur ne répond pas pendant cette période, une exception MongoCursorTimeoutException sera émise et il n'y a aucune façon de déterminer si le serveur gère actuellement l'écriture ou non. Une valeur de -1 peut être spécifiée pour bloquer indéfiniement. La valeur par défaut pour MongoClient est 30000 (30 secondes).
Les options suivants peuvent être utilisées avec MongoDB 2.6+ :
"maxTimeMS"
Spécifie une limite cumulative de temps, en millisecondes, pour procéder à l'opération (n'inclut pas le temps d'inactivité). Si l'opération n'est pas terminée durant cette période, une exception MongoExecutionTimeoutException sera émise.
Les options suivantes peuvent être utilisées avec les versions MongoDB avant 2.8 :
"dropDups"
Spécifiez TRUE pour forcer la création d'un index unique lorsque la collection peut contenir des valeurs dupliqués pour une même clé. MongoDB va indexer la première occurrence dans la clé et supprimer les documents suivants dans la collection qui contiennent une valeur dupliquée pour cette clé. La valeur par défaut est FALSE.
"dropDups" peut supprimer des données dans votre base de données. A utiliser avec une extrême attention.
Note:
Cette option n'est pas supporté sur MongoDB 2.8+. La création d'index sera refusé si la collection contient des clés dupliquées.
Les options suivantes peuvent être utilisées avec les versions MongoDB avant 2.6 :
"w"
Voir les préoccupatios d'écriture. La valeur par défaut pour MongoClient est 1.
"wTimeoutMS"
Cette option spécifie la durée limite, en millisecondes, pour la reconnaissance des préoccupations d'écriture.Ceci n'est applicable que lorsque "w" est supérieur à 1, sachant que le délai d'attente maximal est en relation avec la réplication. Si la préoccupation d'écriture n'est pas spécifiée dans la durée limite, une exception MongoCursorException sera émise. Une valeur de 0 peut être spécifiée pour un blocage permanent. La valeur par défaut pour MongoClient est 10000 (dix secondes).
Les options suivantes sont obsolètes et ne devraient plus être utilisées :
"safe"
Deprecated. Please use the write concern "w" option.
"timeout"
Alias obsolète pour "socketTimeoutMS".
"wtimeout"
Alias obsolète pour "wTimeoutMS".
Retourne un tableau contenant le statut de la création de l'index. Le tableau contient une indication du succès de l'opération ("ok"), le nombre d'indexes avant et après l'opération ("numIndexesBefore" et "numIndexesAfter"), et si la collection auquelle appartient l'index a été créée ("createdCollectionAutomatically"). Si l'index existait déjà, et n'avait donc pas besoin d'être créé, un champ "note" peut être présent au lieu du champ "numIndexesAfter".
Avec MongoDB 2.4 et antérieures, le statut du document n'est retourné que si le
write concern vaut au moins
1. Sinon, TRUE est retourné. Les champs dans le statut
du document sont différents, sauf pour le champ "ok",
qui signale le succès de la création de l'index. Les champs additionnels sont
décrits dans la documentation de la méthode
MongoCollection::insert().
| Version | Description |
|---|---|
| 1.5.0 |
Renommage de l'option "wtimeout" en
"wTimeoutMS". Emets une alerte de niveau
Renommage de l'option "timeout" en
"socketTimeoutMS". Emets une alerte de niveau
Emets une alerte de niveau |
| 1.3.4 | Ajout de l'option "wtimeout". |
| 1.3.0 |
Ajout de l'option "w".
Le paramètre |
| 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.
|
Emets une exception MongoException si le nom de l'index a une longueur supérieure à 128 octets, ou si la spécification de l'index n'est pas un tableau.
Emets une exception MongoDuplicateKeyException si le serveur n'a pas réussi à créer l'index en raison d'une conflit de documents.
Emets une exception MongoResultException si le serveur n'a pas réussi à créer l'index en raison d'une erreur interne.
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 à 1 et que l'opération prend plus de temps que MongoCursor::$timeout millisecondes à se terminer. Ceci ne va pas mettre fin à l'opération sur le serveur, ce n'est qu'un délai d'attente maximal côté client. L'unité pour MongoCollection::$wtimeout est la milliseconde.
Exemple #1 Exemple avec MongoCollection::ensureIndex()
<?php
$c = new MongoCollection($db, 'foo');
// crée un index sur 'x', croissant
$c->ensureIndex(array('x' => 1));
// crée un index unique sur 'y'
$c->ensureIndex(array('y' => 1), array('unique' => true));
// crée un index composé sur 'za', croissant, et sur 'zb', décroissant
$c->ensureIndex(array('za' => 1, 'zb' => -1));
?>
Exemple #2 indexation géospatiale
Mongo supporte l'indexation géospatiale, qui vous permet de rechercher des documents à côté d'une localisation fournie, ou dans un espace donné. L'exemple suivant crée un index géospatial sur le champ "loc" :
<?php
$collection->ensureIndex(array('loc' => '2dsphere'));
?>
Exemple #3 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"));
?>