Manuel PHP - 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 :

"w"
Voir WriteConcerns. La valeur par défaut pour MongoClient est 1.
"unique"

Crée un index unique.

Avertissement
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.

Avertissement
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.

Valeurs de retour

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().

Historique

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.

Erreurs / Exceptions

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.

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

<?php

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

?>

Voir aussi

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