MongoCollection
PHP Manual

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex 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 :

  • "unique"

    Crée un index unique.

    Avertissement

    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.

    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.

  • "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.

Valeurs de retour

Returns TRUE.

Historique

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

Erreurs / Exceptions

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.

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

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"));

?>

Voir aussi

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


MongoCollection
PHP Manual