Edit Report a Bug

    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

    public MongoCollection::ensureIndex ( string|array $key|keys [, array $options = array() ] ) : bool
    Avertissement

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

    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.

      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 E_DEPRECATED lorsque "wtimeout" est utilisée.

    Renommage de l'option "timeout" en "socketTimeoutMS". Emets une alerte de niveau E_DEPRECATED lorsque "timeout" est utilisée.

    Emets une alerte de niveau E_DEPRECATED lorsque "safe" est utilisée.

    1.3.4 Ajout de l'option "wtimeout".
    1.3.0

    Ajout de l'option "w".

    Le paramètre options n'accepte plus de booléen pour signifier un index unique. A la place, vous devez utiliser la syntaxe 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

    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

    add a note add a note

    User Contributed Notes 2 notes

    up
    1
    mcuadros at gmail dot com
    11 years ago
    Ensuring a text index, needed by text search command.

    <?php
    $collection    ->ensureIndex(
        array(
                'title' => 'text',
                'desc' => 'text',
        ),
        array(
                'name' => 'ExampleTextIndex',
                'weights' => array(
                    'title' => 100,
                    'desc' => 30,
            )
        )
    );
    up
    0
    alan dot lake at lakeinfoworks dot com
    14 years ago
    The statement
    <?php
    $c    ->ensureIndex(array('x' => 1), array("unique" => true));
    ?>
    will prevent a document with a duplicate key ('x') from being added to the connection, but will not throw an exception.  To cause an exception to be thrown, use the "safe"=>true option in the insert statement.
    add a note add a note
    To Top