Mettre à jour ou reconstruire un index dans Recherche Azure AI

Cet article explique comment mettre à jour un index existant dans Recherche Azure AI avec des modifications de schéma ou des modifications de contenu via l’indexation incrémentielle.

Conditions préalables

• Un service Recherche Azure AI (n’importe quel niveau). Créer un service ou find’un service existant.

• Index de recherche existant avec des documents. Cet article part du principe que vous avez déjà créé un index et chargé des documents.

• Autorisations pour mettre à jour ou reconstruire des index :

  • Authentification basée sur des clés : clé API d’administration pour votre service de recherche.
  • Authentification basée sur les rôles : rôle Contributeur de données d’index de recherche pour les mises à jour de documents ou Contributeur de service de recherche pour les modifications de schéma.

• Pour le développement sdk, installez la bibliothèque cliente Azure Search :

  • Python : azure-search-documents
  • .NET : Azure. Search.Documents
  • JavaScript : @azure/search-documents
  • Java : azure-search-documents

Mettre à jour le contenu

L’indexation incrémentielle et la synchronisation d’un index par rapport aux modifications apportées aux données sources sont fondamentales pour la plupart des applications de recherche. Cette section explique le flux de travail pour l’ajout, la suppression ou l’écriture du contenu d’un index de recherche via l’API REST, mais les SDK Azure fournissent des fonctionnalités équivalentes.

Le corps de la requête contient un ou plusieurs documents à indexer. Dans la requête, chaque document de l’index est le suivant :

• Identifié par une clé unique sensible à la casse.
• Associé à une action : « upload », « delete », « merge » ou « mergeOrUpload ».
• Rempli avec un ensemble de paires nom/valeur pour chaque champ que vous ajoutez ou mettez à jour.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (name/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

Reference :Documents - Index

• Tout d’abord, utilisez les API pour charger des documents, tels que Documents - Index (REST) ou une API équivalente dans le SDK Azure. Pour plus d’informations sur les techniques d’indexation, consultez Charger des documents.

• Pour une mise à jour volumineuse, le traitement par lot (jusqu’à 1 000 documents par lot, ou environ 16 Mo par lot, selon la limite qui vient en premier) est recommandé et améliore considérablement les performances d’indexation.

• Définissez le @search.action paramètre sur l’API pour déterminer l’effet sur les documents existants. Utiliser mergeOrUpload pour les mises à jour incrémentielles (les plus courantes), delete pour supprimer des documents ou merge pour les mises à jour partielles des champs sur les documents existants.

  Action	Effet
  Supprimer	Supprime l’intégralité du document de l’index. Si vous souhaitez supprimer un champ individuel, utilisez la fusion à la place, en définissant le champ en question sur Null. Les documents et les champs supprimés ne libèrent pas immédiatement de l’espace dans l’index. Toutes les quelques minutes, un processus en arrière-plan effectue la suppression physique. Que vous utilisiez le portail Azure ou une API pour retourner des statistiques d’index, vous pouvez vous attendre à un petit délai avant que la suppression ne soit reflétée dans le portail Azure et via les API. Pour plus d’informations, consultez Supprimer des documents dans un index de recherche.
  Fusionner	Met à jour un document qui existe déjà et échoue si un document est introuvable. La fusion remplace les valeurs existantes. Pour cette raison, veillez à rechercher les champs de collection qui contiennent plusieurs valeurs, telles que les champs de type Collection(Edm.String). Par exemple, si un champ tags commence avec une valeur de ["budget"] et que vous exécutez une fusion avec ["economy", "pool"], la valeur finale du champ tags est ["economy", "pool"]. Ce ne sera pas ["budget", "economy", "pool"]. Le même comportement s’applique aux collections complexes. Si le document contient un champ de collection complexe nommé Rooms avec la valeur [{ "Type": "Budget Room", "BaseRate": 75.0 }], et que vous exécutez une fusion avec une valeur [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], la valeur finale du champ Salles sera [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Il n’ajoute ni ne fusionne les valeurs nouvelles et existantes.
  fusionnerOuTéléverser	Se comporte comme fusion si le document existe et charge si le document est nouveau. Il s’agit de l’action la plus courante pour les mises à jour incrémentielles.
  Téléverser	Similaire à un « upsert », où le document est inséré s’il est nouveau, ou mis à jour, ou remplacé s’il existe déjà. Si le document ne contient pas de valeurs requises par l’index, la valeur du champ de document est définie sur Null.

Les requêtes continuent de s’exécuter pendant l’indexation, mais si vous mettez à jour ou supprimez des champs existants, vous pouvez vous attendre à des résultats incohérents et à une fréquence plus élevée de limitation du débit.

Réponses

Le code d’état 200 est retourné pour une réponse réussie, ce qui signifie que tous les éléments ont été stockés durablement et commencent à être indexés. L’indexation s’exécute en arrière-plan et rend les nouveaux documents disponibles (c’est-à-dire, interrogeables et pouvant faire l’objet d’une recherche) quelques secondes après la fin de l’opération d’indexation. Le délai spécifique dépend de la charge sur le service.

L’indexation réussie est indiquée par la propriété d’état définie sur true pour tous les éléments, ainsi que la statusCode propriété définie sur 201 (pour les documents nouvellement chargés) ou 200 (pour les documents fusionnés ou supprimés) :

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

Le code d’état 207 est retourné lorsque au moins un élément n’a pas été correctement indexé. Les éléments qui n’ont pas été indexés ont le champ d’état défini sur false. Les errorMessage propriétés et statusCode indiquent la raison de l’erreur d’indexation :

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

La errorMessage propriété indique la raison de l’erreur d’indexation si possible.

Le tableau suivant décrit les différents codes d’état par document qui peuvent être retournés dans la réponse. Certains codes d’état indiquent des problèmes avec la requête elle-même, tandis que d’autres indiquent des conditions d’erreur temporaires. Dans ce dernier cas, il est recommandé de réessayer l’opération après un certain délai.

Si votre code client rencontre fréquemment une réponse 207, une des raisons possibles est que le système est en cours de chargement. Vous pouvez le confirmer en vérifiant la propriété statusCode pour 503. Si statusCode est 503, nous vous recommandons de limiter les demandes d’indexation. Sinon, si l’indexation du trafic ne diminue pas, le système peut commencer à rejeter toutes les requêtes avec des erreurs 503.

Le code d’état 429 indique que vous avez dépassé votre quota sur le nombre de documents par index. Vous devez effectuer une mise à niveau pour des limites de capacité plus élevées ou créer un index.

Conseils pour l’indexation incrémentielle

• Les indexeurs automatisent l’indexation incrémentielle. Si vous pouvez utiliser un indexeur et si la source de données prend en charge le suivi des modifications, vous pouvez exécuter l’indexeur selon une planification périodique pour ajouter, mettre à jour ou remplacer du contenu pouvant faire l’objet d’une recherche afin qu’il soit synchronisé avec vos données externes.

• Si vous effectuez des appels d’index directement via l’API Push, utilisez mergeOrUpload en tant qu'action de recherche.

• La charge utile doit inclure les clés ou les identificateurs de chaque document que vous souhaitez ajouter, mettre à jour ou supprimer.

• Si votre index inclut des champs vectoriels et que vous définissez la stored propriété sur false, veillez à fournir le vecteur dans votre mise à jour partielle du document, même si la valeur n’est pas modifiée. Un effet secondaire de la valeur stored false est que les vecteurs sont supprimés lors d’une opération de réindexation. Fournir le vecteur dans la charge utile des documents empêche cela de se produire.

• Pour mettre à jour le contenu des champs simples et des sous-champs dans des types complexes, répertoriez uniquement les champs que vous souhaitez modifier. Par exemple, si vous devez uniquement mettre à jour un champ de description, la charge utile doit être constituée de la clé de document et de la description modifiée. L’omission d’autres champs conserve leurs valeurs existantes.

• Pour fusionner des modifications en ligne dans une collection de chaînes de caractères, fournissez la valeur complète. Rappelez-vous l’exemple tags de champ de la section précédente. Les nouvelles valeurs remplacent les anciennes valeurs d’un champ entier et il n’y a aucune fusion dans le contenu d’un champ.

Voici un exemple d’API REST illustrant ces conseils :

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2026-04-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2026-04-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2026-04-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Référence :Documents - Index, Document de recherche

Exemples de SDK

Les exemples suivants montrent comment mettre à jour des documents à l’aide de la SDK Azure.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-admin-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Update documents using merge_or_upload
documents = [
    {
        "HotelId": "1",
        "Description": "Updated description for the hotel.",
        "Tags": ["updated", "renovated"]
    }
]

result = client.merge_or_upload_documents(documents=documents)
print(f"Updated {len(result)} document(s)")

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Update documents using MergeOrUpload
var batch = IndexDocumentsBatch.MergeOrUpload(
    new[]
    {
        new Hotel { HotelId = "1", Description = "Updated description.", Tags = new[] { "updated", "renovated" } }
    });

IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(batch);
Console.WriteLine($"Updated {result.Results.Count} document(s)");

Mettre à jour un schéma d’index

Le schéma d’index définit les structures de données physiques créées sur le service de recherche. Il n’existe donc pas de nombreuses modifications de schéma que vous pouvez apporter sans entraîner de reconstruction complète.

Mises à jour sans reconstruction

La liste suivante énumère les modifications de schéma qui peuvent être introduites en toute transparence dans un index existant. En règle générale, la liste inclut de nouveaux champs et fonctionnalités utilisés lors de l’exécution de la requête.

• Ajouter une description d’index
• Ajouter un nouveau champ
• Définir l’attribut retrievable sur un champ existant
• Mettre à jour searchAnalyzer sur un champ ayant un champ existant indexAnalyzer
• Ajouter une nouvelle définition d’analyseur dans un index (qui peut être appliqué aux nouveaux champs)
• Ajouter, mettre à jour ou supprimer des profils de score
• Ajouter, mettre à jour ou supprimer des mappages de synonymes
• Ajouter, mettre à jour ou supprimer des configurations sémantiques
• Ajouter, mettre à jour ou supprimer des paramètres CORS

L’ordre des opérations est le suivant :

1. Obtenez la définition d’index.

2. Modifiez le schéma avec les mises à jour de la liste précédente.

3. Mettez à jour le schéma d’index sur le service de recherche.

4. Mettez à jour le contenu de l’index pour qu’il corresponde à votre schéma révisé si vous avez ajouté un nouveau champ. Pour toutes les autres modifications, le contenu indexé existant est utilisé as-is.

Lorsque vous mettez à jour un schéma d’index pour inclure un nouveau champ, les documents existants dans l’index reçoivent une valeur Null pour ce champ. Dans le travail d’indexation suivant, les valeurs des données sources externes remplacent les valeurs Null ajoutées par Recherche Azure AI.

Il ne doit y avoir aucune interruption de requête pendant les mises à jour, mais les résultats de la requête varient à mesure que les mises à jour prennent effet.

Mises à jour nécessitant une reconstruction

Certaines modifications nécessitent une suppression d’index et une reconstruction, en remplaçant un index actuel par un nouvel index.

L’ordre des opérations est le suivant :

1. Obtenez une définition d’index au cas où vous en avez besoin pour une référence ultérieure ou pour l’utiliser comme base pour une nouvelle version.

2. Envisagez d’utiliser une solution de sauvegarde et de restauration pour conserver une copie du contenu d’index. Il existe des solutions dans C# et dans Python. Nous vous recommandons la version Python, car elle est plus à jour.

   Si vous avez de la capacité sur votre service de recherche, conservez l’index existant lors de la création et du test de celui-ci.

3. Supprimez l’index existant. Les requêtes ciblant l’index sont immédiatement supprimées. Souvenez-vous que la suppression d’un index est irréversible, détruisant le stockage physique pour la collection de champs et d’autres constructions.

4. Publiez un index révisé, où le corps de la requête inclut des définitions et des configurations de champs modifiées.

5. Chargez l’index avec des documents à partir d’une source externe. Les documents sont indexés à l’aide des définitions de champs et des configurations du nouveau schéma.

Lorsque vous créez l’index, le stockage physique est alloué pour chaque champ du schéma d’index, avec un index inversé créé pour chaque champ pouvant faire l’objet d’une recherche et un index vectoriel créé pour chaque champ vectoriel. Les champs qui ne peuvent pas faire l’objet d’une recherche peuvent être utilisés dans des filtres ou des expressions, mais qui n’ont pas d’index inversés et qui ne peuvent pas faire l’objet d’une recherche en texte intégral ou flou. Sur une reconstruction d’index, ces index inversés et les index vectoriels sont supprimés et recréés en fonction du schéma d’index que vous fournissez.

Pour réduire la perturbation du code d’application, envisagez de créer un alias d’index. Le code d’application fait référence à l’alias, mais vous pouvez mettre à jour le nom de l’index vers lequel pointe l’alias.

Ajouter une description d’index

Un index a une description propriété que vous pouvez spécifier et utiliser lorsqu’un système doit accéder à plusieurs index et prendre une décision en fonction de la description. Considérez un serveur MCP (Model Context Protocol) qui doit choisir l’index approprié au moment de l’exécution. La décision peut être basée sur la description plutôt que sur le nom de l’index seul.

Une description d’index est une mise à jour de schéma et vous pouvez l’ajouter sans avoir à reconstruire l’index entier.

• La longueur de chaîne est de 4 000 caractères maximum.
• Le contenu doit être lisible par l’homme, en Unicode. Votre cas d’usage doit déterminer la langue à utiliser.

Vous pouvez ajouter une description d’index via le portail Azure, la dernière API REST stable ou un package Kit de développement logiciel (SDK) Azure qui fournit la fonctionnalité.

Équilibrage des charges de travail

L’indexation ne s’exécute pas en arrière-plan, mais le service de recherche équilibre les travaux d’indexation par rapport aux requêtes en cours. Lors de l’indexation, vous pouvez surveiller les requêtes dans le portail Azure pour vous assurer que les requêtes se terminent dans des délais raisonnables.

Si l’indexation des charges de travail introduit des niveaux inacceptables de latence de requête, effectuez une analyse des performances et passez en revue ces conseils de performances pour une atténuation potentielle.

Rechercher les mises à jour

Vous pouvez commencer à interroger un index dès que le premier document est chargé. Si vous connaissez l’ID d’un document, l’API REST Lookup Document retourne le document spécifique. Pour des tests plus larges, vous devez attendre que l’index soit entièrement chargé, puis utiliser des requêtes pour vérifier le contexte que vous prévoyez de voir.

Vous pouvez utiliser l’Explorateur de recherche ou un client REST pour rechercher le contenu mis à jour.

Si vous avez ajouté ou renommé un champ, utilisez sélectionner pour retourner ce champ:

"search": "*",
"select": "document-id, my-new-field, some-old-field",
"count": true

Le portail Azure fournit une taille d’index et une taille d’index vectoriel. Vous pouvez vérifier ces valeurs après la mise à jour d’un index, mais n’oubliez pas d’attendre un petit délai lorsque le service traite la modification et de tenir compte des taux d’actualisation du portail, ce qui peut être quelques minutes.

Résoudre les problèmes de réindexation

Le tableau suivant répertorie les problèmes courants lors de la mise à jour ou de la reconstruction d’index et de la façon de les résoudre.

Voir aussi

• Vue d’ensemble de l’indexeur
• Supprimer des documents d’un index de recherche
• Indexer des jeux de données volumineux à grande échelle
• Indexation dans le portail Azure
• Indexeur Azure SQL Database
• Azure Cosmos DB pour NoSQL indexeur
• Indexeur de blobs Azure
• indexeur de tables Azure
• Données, confidentialité et protections intégrées