MongoCollection::ensureIndex
(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à
Description
$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.
Liste de paramètres
-
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
TRUEpour créer un index unique. La valeur par défaut estFALSE. 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
TRUEpour créer un index clairsemé, qui n'indexe que des documents contenant un champ spécifié. La valeur par défaut estFALSE."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
TRUEpour une construction en arrière plan. La valeur par défaut estFALSE.AvertissementAvant 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
TRUEpour 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 estFALSE.Avertissement"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".
Valeurs de retour
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().
Historique
| 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.
|
Erreurs / Exceptions
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.
Exemples
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"));
?>
Voir aussi
- MongoCollection::createIndex() - Crée un index sur le ou les champs spécifiés s'il n'existe pas déjà
- MongoCollection::deleteIndex() - Supprime un index de la collection
- MongoCollection::deleteIndexes() - Supprime tous les index de cette collection
- La documentation MongoDB sur les » indexes et les » types d'indexes.
Version en cache
10/01/2025 18:04:04 Cette version de la page est en cache (à la date du 10/01/2025 18:04:04) afin d'accélérer le traitement. Vous pouvez activer le mode utilisateur dans le menu en haut pour afficher la dernère version de la page.Document créé le 30/01/2003, dernière modification le 26/10/2018
Source du document imprimé : https://www.gaudry.be/php-rf-mongocollection.ensureindex.html
L'infobrol est un site personnel dont le contenu n'engage que moi. Le texte est mis à disposition sous licence CreativeCommons(BY-NC-SA). Plus d'info sur les conditions d'utilisation et sur l'auteur.
Références
Ces références et liens indiquent des documents consultés lors de la rédaction de cette page, ou qui peuvent apporter un complément d'information, mais les auteurs de ces sources ne peuvent être tenus responsables du contenu de cette page.
L'auteur de ce site est seul responsable de la manière dont sont présentés ici les différents concepts, et des libertés qui sont prises avec les ouvrages de référence. N'oubliez pas que vous devez croiser les informations de sources multiples afin de diminuer les risques d'erreurs.
