Création d'index Supprimer les index Déterminer la sélection de l'indice et fournir un indice

Gestion des index dans Amazon DocumentDB avec Java

Les index permettent de récupérer efficacement les données d'une collection Amazon DocumentDB. Sans index, DocumentDB doit scanner chaque document de la collection pour renvoyer des résultats qui répondent à une requête donnée. Cette rubrique explique comment créer, supprimer et répertorier des index à l'aide des pilotes Java MongoDB. Il explique également comment déterminer si un index particulier est utilisé dans la requête et comment donner des conseils à Amazon DocumentDB pour utiliser un index spécifique.

Rubriques

Création d'index
Supprimer les index
Déterminer la sélection de l'indice et fournir un indice

Amazon DocumentDB prend en charge de nombreux types d'index. Pour une vue d'ensemble complète de tous les index pris en charge, consultez Comment indexer sur Amazon DocumentDB sur le blog de la AWS base de données.

Création d'index avec Java

Il existe deux mécanismes pour créer des index dans Amazon DocumentDB à l'aide des pilotes Java MongoDB : via runCommand() et par la createIndex() méthode pour un index unique ou la createIndexes() méthode pour plusieurs index. L'une des raisons d'utiliser les createIndexes() méthodes createIndex() et est que vous pouvez améliorer la gestion des erreurs en détectant des erreurs spécifiques liées à la création d'index. Une autre raison de recourir à ces méthodes runCommand() est que le pilote Java MongoDB fournit un ensemble complet de classes de support pour la création et la manipulation d'index. Notez que ces classes de support ne peuvent être utilisées que lorsque vous utilisez les createIndexes() méthodes createIndex() ou. Il existe trois classes de soutien :

Indexes— Cette classe sert de classe utilitaire proposant des méthodes de fabrique statiques pour créer différents types d'index. Il simplifie le processus de création de définitions d'index complexes et est couramment utilisé conjointement avec d'autres classes liées aux index.
IndexModel— Il s'agit d'une classe fondamentale qui encapsule à la fois la définition des clés d'index et ses options. Il représente une spécification d'index complète, combinant les éléments à indexer (les clés) et la manière d'indexer (les options). Cette classe est particulièrement utile lors de la création simultanée de plusieurs index, car elle vous permet de définir un ensemble de spécifications d'index qui peuvent être transmises à la createIndexes() méthode.
IndexOptions— Il s'agit d'une classe de configuration complète qui fournit un ensemble complet de méthodes permettant de personnaliser le comportement des index. Il inclut des paramètres pour les index uniques, les index fragmentés, le délai d'expiration (TTL) et les expressions de filtre partielles. Grâce au chaînage de méthodes, vous pouvez configurer plusieurs options, telles que la création d'index en arrière-plan et les contraintes uniques.

Création d'un index unique

Cet exemple montre comment créer un index unique à l'aide de la méthodecreateIndex() en arrière-plan. Pour comprendre la création d'index d'arrière-plan et de premier plan, reportez-vous àTypes de création d'index. L'exemple de code suivant permet IndexOptions de créer un index unique avec le nom « unique_restaurant Id_idx » en arrière-plan. Cet IndexOptions objet est ensuite transmis à la createIndex() méthode.


collection.createIndex(
    Indexes.ascending("restaurantId"),
    new IndexOptions()
        .unique(true)
        .name("unique_restaurantId_idx")
        .background(true));

Création de plusieurs index

Cet exemple crée plusieurs index à l'aide de createIndexes() cette méthode. Il crée d'abord l'option pour chaque index à l'aide de l'IndexModelobjet, puis transmet une liste d'IndexModelobjets à la createIndexes() méthode. L'exemple de code suivant montre comment créer un index composite à l'aide de la classe Indexes utilitaire. Cette classe est également utilisée pour spécifier si vous souhaitez créer un index en utilisant un ordre de tri croissant ou décroissant. Après avoir créé plusieurs index, il vérifie la création de l'index en appelant la listIndexes() méthode.


// Single Field Index on cuisine
IndexModel singleIndex = new IndexModel(
    Indexes.ascending("cuisine"),
    new IndexOptions().name("cuisine_idx"));

// Compound Index
IndexModel compoundIndex = new IndexModel(
    Indexes.compoundIndex(
        Indexes.ascending("address.state"),
        Indexes.ascending("priceRange")),
    new IndexOptions().name("location_price_idx"));

// Build a list of IndexModel for the indexes
List < IndexModel > indexes = Arrays.asList(
    singleIndex,
    compoundIndex
);

collection.createIndexes(indexes);

// Verify created indexes
collection.listIndexes().forEach(index - > System.out.println("Created index: " + index.toJson()));

Création d'index fragmentés et partiels

Cet exemple montre comment créer un index fragmenté et un index partiel en créant un IndexModel pour chaque type d'index.


// Sparse Index Model, this will identify only those documents that have a
// michelin star rating
IndexModel sparseIndex = new IndexModel(
    Indexes.ascending("michelin.star"),
    new IndexOptions()
    .name("michelin_sparse_idx")
    .sparse(true));

// Partial Index Model where the restaurant is active and has a rating of 4 and above
IndexModel partialIndex = new IndexModel(
    Indexes.ascending("rating.average"),
    new IndexOptions()
    .name("high_rated_active_idx")
    .partialFilterExpression(
        Filters.and(
            Filters.eq("isActive", true),
            Filters.gte("rating.average", 4.0))));

Création d'un index de texte

Cet exemple montre comment créer un index de texte. Un seul index de texte est autorisé dans une collection, mais cet index de texte peut être un index composé couvrant plusieurs champs. Lorsque vous utilisez plusieurs champs dans l'index de texte, vous pouvez également attribuer des pondérations à chacun des champs de l'index. Les index de texte sur les champs de tableau ne sont pas pris en charge par Amazon DocumentDB et même si vous pouvez utiliser jusqu'à 30 champs dans l'index de texte composé, seuls trois champs peuvent être pondérés.


IndexModel textIndex = new IndexModel(
    new Document()
    .append("name", "text")
    .append("description", "text")
    .append("cuisine", "text"),
    new IndexOptions()
    .name("restaurant_text_idx")
    .weights(new Document()
        .append("name", 10) // Restaurant name gets highest weight
        .append("description", 5) // Description get medium weight
        .append("cuisine", 2) // Cuisine type gets low weight
    ));

collection.createIndex(textIndex.getKeys(), textIndex.getOptions());

Créez un index à l'aide de runCommand()

Amazon DocumentDB prend en charge la création d'index en parallèle afin de réduire le temps nécessaire à la création des index. L'indexation parallèle utilise plusieurs outils de travail simultanés. Les travailleurs par défaut utilisés pour la création d'index sont deux. Pour plus d'informations, consultez Exploitez toute la puissance de l'indexation parallèle dans Amazon DocumentDB sur le blog de la AWS base de données. Actuellement, les pilotes Java MongoDB ne prennent pas en charge la spécification de l'option worker lorsque vous utilisez createIndex() or createIndexes() et, par conséquent, la seule façon de spécifier des workers est d'utiliser le. runCommand L'exemple de code suivant montre comment runCommand créer un index qui augmente le nombre de travailleurs à quatre :


Document command = new Document("createIndexes", "Restaurants")
    .append("indexes", Arrays.asList(
        new Document("key", new Document("name", 1))
        .append("name", "restaurant_name_idx")
        .append("workers", 4) // Specify number of workers
    ));

Document commendResult = connectedDB.runCommand(command);

Supprimer les index

Le pilote Java MongoDB propose plusieurs méthodes pour supprimer des index, en fonction de différents scénarios et de vos préférences. Vous pouvez supprimer des index par nom, par spécification de clé, ou supprimer tous les index en même temps. Les méthodes dropIndex() et dropIndexes() peuvent être invoquées sur un objet de collection pour supprimer un index. Lorsque vous supprimez un index par son nom, vous devez vous assurer qu'il utilise le nom d'index correct, ce qui n'est pas toujours intuitif, en particulier pour les index composés ou générés automatiquement. Si vous tentez de supprimer un index inexistant, vous obtiendrez un MongoCommandException. L'default _idindex ne peut pas être supprimé car il garantit l'unicité des documents au sein de la collection.

L'exemple de code suivant montre comment supprimer un index en fournissant le nom du champ dans lequel l'index est créé ou en supprimant tous les index :


String indexName = "unique_restaurantId_idx";
Document keys = new Document("cuisine", 1);
// Drop index by name
collection.dropIndex(indexName);
            
// Drop index by keys
collection.dropIndex(keys);
            
// Drop all indexes
collection.dropIndexes();

Lorsque vous supprimez des index à l'aide de plusieurs clés, assurez-vous qu'il existe un index composé contenant toutes les clés spécifiées et que l'ordre des clés est correct. L'exemple de code de création d'index ci-dessus montre une clé composée sur la « cuisine » et les fonctionnalités. Si vous essayez de supprimer cette clé composée mais que l'ordre n'est pas celui utilisé pour la création, MongoCommnadException l'erreur suivante se produit :


Document keys = new Document("features", 1)
    .append("cuisine", 1);
try {
    // Drop index by keys
    collection.dropIndex(keys);
    System.out.println("Successfully dropped index with keys: " + keys.toJson());

} catch (MongoCommandException commErr) {
    System.out.println("Error dropping index: " + commErr.getErrorMessage());
    throw new RuntimeException("MongoCommandException was thrown while dropping index", commErr);
}

L'erreur suivante s'affiche :


Error dropping index: Cannot drop index: index not found.
Tests run: 3, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.819 sec <<< FAILURE!
com.amazon.docdb.guide.DocDBGuideTest.testindexGuide()  Time elapsed: 0.817 sec  <<< FAILURE!
org.opentest4j.AssertionFailedError: Unexpected exception thrown: java.lang.RuntimeException: MongoCommandException was thrown while dropping index

Déterminer la sélection de l'indice et fournir un indice

L'utilisation de la fonctionnalité d'explication d'Amazon DocumentDB est essentielle pour comprendre les performances des requêtes et l'utilisation des index. Lors de l'exécution d'une requête, vous pouvez ajouter la explain() méthode pour obtenir des informations détaillées sur le plan de requête, y compris les index utilisés, le cas échéant. Le explain() résultat fournit des informations sur les étapes d'exécution des requêtes, le nombre de documents examinés et le temps nécessaire à chaque étape. Ces informations sont précieuses pour déterminer si un index particulier est utilisé efficacement ou si la requête pourrait bénéficier d'une structure d'index différente.

Le explain() procédé peut être enchaîné avec le find() procédé. La explain() méthode peut prendre une ExplainVerbosity énumération facultative qui détermine le niveau de verbosité renvoyé par. explain() À l'heure actuelle, seuls les QUERY_PLANNER énumérateurs EXECUTION_STATS et sont pris en charge par DocumentDB. L'exemple de code suivant montre comment obtenir un planificateur de requêtes pour une requête spécifique :


// Query we want to analyze
Document query = new Document()
    .append("cuisine", "Thai")
    .append("rating.average", new Document("$gte", 4.0));


Document allPlansExplain = collection.find(query).explain(ExplainVerbosity.QUERY_PLANNER);
System.out.println("All Plans Explain:\n" + allPlansExplain.toJson());

Le document JSON suivant est renvoyé pour le niveau de verbosité du planificateur de requêtes :


{
  "queryPlanner": {
    "plannerVersion": 1,
    "namespace": "ProgGuideData.Restaurants",
    "winningPlan": {
      "stage": "IXSCAN",
      "indexName": "cuisine_idx",
      "direction": "forward"
    }
  },
  "serverInfo": {
    "host": "guidecluster3",
    "port": 27017,
    "version": "5.0.0"
  },
  "ok": 1,
  "operationTime": {
    "$timestamp": {
      "t": 1739221668,
      "i": 1
    }
  }
}

Plusieurs options s'offrent à vous pour influencer ou forcer Amazon DocumentDB à utiliser un index spécifique. Les hintString() méthodes hint() et vous permettent de modifier le comportement de sélection d'index par défaut de l'optimiseur de requêtes en spécifiant explicitement quel index doit être utilisé pour une requête. Bien que l'optimiseur de requêtes de DocumentDB fasse généralement de bons choix pour la sélection d'index, il existe des scénarios dans lesquels forcer le passage d'un index spécifique hintString() peut s'avérer bénéfique, par hint() exemple lorsqu'il s'agit de traiter des données asymétriques ou de tester les performances d'un index.

L'exemple de code suivant force l'utilisation de l'index composé « cuisine_features_idx » pour la même requête que celle exécutée dans le code ci-dessus :


// Query we want to analyze
Document query = new Document()
    .append("cuisine", "Thai")
    .append("rating.average", new Document("$gte", 4.0));

List < Document > queryDocs = new ArrayList < > ();
collection.find(query).hintString("cuisine_features_idx").forEach(doc - > queryDocs.add(doc));

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Opérations CRUD avec Java

Event-driven programmation