MongoCollection::createIndex

(PECL mongo >=1.5.0)

MongoCollection::createIndex — Crée un index sur le ou les champs spécifiés s'il n'existe pas déjà

Description

public MongoCollection::createIndex ( array $keys [, array $options = array() ] ) : bool

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 sur un type spécial (i.e. texte, géospatial, hashé).

Note:

Cette méthode utilise la commande de base de données » createIndexes lors de la communication avec MongoDB 2.6+. Pour les anciennes versions de base 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 de l'index, sous forme de 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, utilisez 1 pour croissant, ou -1 pour décroissant.

options

Un tableau d'options pour la création de l'index. Toutes les options fournies seront passées au serveur ; voici une liste non-exhaustive des options actuellement disponibles :

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

    Avertissement

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

L'option suivante peut être utilisé 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.

L'option suivante peut être utilisé avec les versions de 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.

    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 de 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 doivent 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 soit le 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 de l'index a été créée ("createdCollectionAutomatically"). Si l'index existe déjà, et n'a pas été créé, un champ "note" peut être présent au lieu de "numIndexesAfter".

Avec MongoDB 2.4 et antérieurs, le statut du document n'est retourné que si la préoccupation d'écriture vaut au moins 1. Sinon, TRUE sera retourné. Les champs dans le statut du document sont différents, sauf pour le champ "ok" qui signale si la création de l'index a réussi. Les champs additionnels sont décrits dans la documentation de la méthode MongoCollection::insert().

Erreurs / Exceptions

Lance une exception MongoException si le nom de l'index est supérieur à 128 octets, ou si la spécification de l'index n'est pas un tableau.

Lance une exception MongoDuplicateKeyException si le serveur n'a pas réussi à créer l'index unique en raison d'un conflit de documents.

Lance une exception MongoResultException si le serveur n'a pas réussi à créer l'index en raison d'une erreur.

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::createIndex()

<?php

$c = new MongoCollection($db, 'foo');

// Crée un index sur 'x' croissant
$c->createIndex(array('x' => 1));

// Crée un index unique sur 'y'
$c->createIndex(array('y' => 1), array('unique' => true));

// Crée un index calculé sur 'za' croissant et sur 'zb' décroissant
$c->createIndex(array('za' => 1, 'zb' => -1));

?>

Exemple #2 Indexation géospatiale

Mongo supporte les indexes géospatiaux, qui vous permet de chercher des documents proches d'une localisation précise, ou dans un espace. L'exemple suivant crée un index géospatial sur le champ "loc" :

<?php

$collection->createIndex(array('loc' => '2dsphere'));

?>

Exemple #3 Exemple de suppression de doublons

<?php

$collection->insert(array('username' => 'joeschmoe'));
$collection->insert(array('username' => 'joeschmoe'));

/* La création d'index échoue, sachant que vous ne pouvez pas créer d'index unique
 * sur un champ lorsqu'un doublon existe.
 */
$collection->createIndex(array('username' => 1), array('unique' => 1));

/* MongoDB va supprimer le conflit de documents et autoriser
 * la création de l'index unique.
 */
$collection->createIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));

/* Nous avons maintenant un index unique et une sous-séquence d'insertions avec le
 * même nom va échouer.
 */
$collection->insert(array('username' => 'joeschmoe'));

?>

Voir aussi