Aggiornare o ricompilare un indice in Azure AI Search

Questo articolo illustra come aggiornare un indice esistente in Azure AI Search con modifiche dello schema o modifiche al contenuto tramite l'indicizzazione incrementale.

Prerequisiti

• Un servizio Azure AI Search (qualsiasi livello). Creare un servizio o finirne uno esistente.

• Indice di ricerca esistente con documenti. In questo articolo si presuppone che sia già stato creato un indice e siano stati caricati documenti.

• Autorizzazioni per aggiornare o ricompilare gli indici:

  • Autenticazione basata su chiave: chiave API amministratore per il servizio di ricerca.
  • Autenticazione basata su ruoli: ruolo Collaboratore ai dati dell'indice di ricerca per gli aggiornamenti dei documenti o Collaboratore del servizio di ricerca per le modifiche dello schema.

• Per lo sviluppo di SDK, installare la libreria client di ricerca Azure:

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

Aggiornare il contenuto

L'indicizzazione incrementale e la sincronizzazione di un indice rispetto alle modifiche apportate ai dati di origine sono fondamentali per la maggior parte delle applicazioni di ricerca. Questa sezione illustra il flusso di lavoro per l'aggiunta, la rimozione o la sovrascrittura del contenuto di un indice di ricerca tramite l'API REST, ma l'Azure SDK fornisce funzionalità equivalenti.

Il corpo della richiesta contiene uno o più documenti da indicizzare. All'interno della richiesta, ogni documento nell'indice è:

• Identificato da una chiave univoca con distinzione tra maiuscole e minuscole.
• Associata a un'azione: "upload", "delete", "merge" o "mergeOrUpload".
• Popolato con un set di coppie nome/valore per ogni campo che aggiungi o aggiorni.

{  
  "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

• Usare prima di tutto le API per caricare documenti, ad esempio Documents - Index (REST) o un'API equivalente nel Azure SDK. Per altre informazioni sulle tecniche di indicizzazione, vedere Caricare documenti.

• Per un aggiornamento di grandi dimensioni, l'invio in batch (fino a 1.000 documenti per batch o circa 16 MB per batch, a seconda del limite previsto) è consigliato e migliora significativamente le prestazioni di indicizzazione.

• Impostare il @search.action parametro nell'API per determinare l'effetto sui documenti esistenti. Usare mergeOrUpload per gli aggiornamenti incrementali (più comuni), delete per rimuovere i documenti o merge per gli aggiornamenti parziali dei campi nei documenti esistenti.

  Azione	Effetto
  Elimina	Rimuove l'intero documento dall'indice. Se si desidera rimuovere un singolo campo, usare unisci, impostando invece il campo in questione su Null. I documenti e i campi eliminati non liberano immediatamente spazio nell'indice. Ogni pochi minuti, un processo in background esegue l'eliminazione fisica. Indipendentemente dal fatto che si usi il portale di Azure o un'API per restituire le statistiche sugli indici, è possibile prevedere un piccolo ritardo prima che l'eliminazione venga riflessa nel portale di Azure e tramite le API. Per altre informazioni, vedere Eliminare documenti in un indice di ricerca.
  Fusione	Aggiorna un documento già esistente e segnala un errore se non è possibile trovare un documento. Merge sostituisce i valori esistenti. Per questo motivo, assicurarsi di verificare la presenza di campi di raccolta contenenti più valori, ad esempio campi di tipo Collection(Edm.String). Ad esempio, se il campo tags inizia con un valore ["budget"] e si esegue un'unione con ["economy", "pool"], il valore finale del campo tags è ["economy", "pool"]. Non sarà ["budget", "economy", "pool"]. Lo stesso comportamento si applica alle raccolte complesse. Se il documento contiene un campo di raccolta complesso denominato Rooms con un valore [{ "Type": "Budget Room", "BaseRate": 75.0 }]e si esegue un merge con un valore pari [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]a , il valore finale del campo Rooms sarà [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Non aggiungerà o unisce valori nuovi ed esistenti.
  unireOCaricare	Si comporta come una fusione se il documento esiste e come un caricamento se il documento è nuovo. Questa è l'azione più comune per gli aggiornamenti incrementali.
  Caricamento	Simile a un'operazione "upsert", in cui il documento viene inserito se è nuovo, aggiornato se esiste già, o sostituito se necessario. Se il documento non contiene valori richiesti dall'indice, il valore del campo del documento viene impostato su Null.

Le query continuano a essere eseguite durante l'indicizzazione, ma se si aggiornano o si rimuovono campi esistenti, ci si può aspettare risultati misti e una maggiore incidenza della limitazione.

Risposte

Il codice di stato 200 viene restituito per una risposta con esito positivo, ovvero tutti gli elementi sono stati archiviati in modo permanente e inizieranno a essere indicizzati. L'indicizzazione viene eseguita in background e rende disponibili nuovi documenti( ovvero queryable e ricercabili) pochi secondi dopo il completamento dell'operazione di indicizzazione. Il ritardo specifico dipende dal carico del servizio.

L'indicizzazione riuscita è indicata dalla proprietà status impostata su true per tutti gli elementi, nonché la statusCode proprietà impostata su 201 (per i documenti appena caricati) o 200 (per i documenti uniti o eliminati):

{
  "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
    }
  ]
}

Il codice di stato 207 viene restituito quando almeno un elemento non è stato indicizzato correttamente. Gli elementi che non sono stati indicizzati hanno il campo di stato impostato su false. Le errorMessage proprietà e statusCode indicano il motivo dell'errore di indicizzazione:

{
  "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 proprietà indica il motivo dell'errore di indicizzazione, se possibile.

Nella tabella seguente vengono illustrati i vari codici di stato per documento che possono essere restituiti nella risposta. Alcuni codici di stato indicano problemi con la richiesta stessa, mentre altri indicano condizioni di errore temporanee. Quest'ultimo è necessario riprovare dopo un ritardo.

Se il codice client rileva spesso una risposta 207, un possibile motivo è che il sistema è sotto carico. Per confermarlo, controllare che la proprietà statusCode sia 503. Se statusCode è 503, è consigliabile limitare le richieste di indicizzazione. Altrimenti, se il traffico di indicizzazione non diminuisce, il sistema potrebbe iniziare a rifiutare tutte le richieste con errori 503.

Il codice di stato 429 indica che è stata superata la quota per il numero di documenti per indice. È necessario eseguire l'aggiornamento per i limiti di capacità più elevati o creare un nuovo indice.

Suggerimenti per l'indicizzazione incrementale

• Gli indicizzatori automatizzano l'indicizzazione incrementale. Se è possibile usare un indicizzatore e se l'origine dati supporta il rilevamento delle modifiche, è possibile eseguire l'indicizzatore in base a una pianificazione ricorrente per aggiungere, aggiornare o sovrascrivere il contenuto ricercabile in modo che venga sincronizzato con i dati esterni.

• Se si effettuano chiamate di indice direttamente tramite l'API push, usare mergeOrUpload come azione di ricerca.

• Il payload deve includere le chiavi o gli identificatori di ogni documento da aggiungere, aggiornare o eliminare.

• Se l'indice include campi vettoriali e si imposta la stored proprietà su false, assicurarsi di fornire il vettore nell'aggiornamento parziale del documento, anche se il valore è invariato. Un effetto collaterale dell'impostazione stored su false è che i vettori vengono eliminati in un'operazione di reindicizzazione. Se si specifica il vettore nel payload dei documenti, si impedisce che ciò accada.

• Per aggiornare il contenuto di campi semplici e campi secondari in tipi complessi, elencare solo i campi da modificare. Ad esempio, se è sufficiente aggiornare un campo di descrizione, il payload deve essere costituito dalla chiave del documento e dalla descrizione modificata. L'omissione di altri campi mantiene i valori esistenti.

• Per unire le modifiche inline nella raccolta di stringhe, specificare l'intero valore. Richiama l'esempio del campo tags dalla sezione precedente. I nuovi valori sovrascrivono i valori precedenti per un intero campo e non esiste un'unione all'interno del contenuto di un campo.

Ecco un esempio di API REST che illustra questi suggerimenti:

### 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}}

Reference:Documents - Index, Lookup Document

Esempi di SDK

Negli esempi seguenti viene illustrato come aggiornare i documenti usando il Azure SDK.

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

Aggiornare uno schema di indice

Lo schema dell'indice definisce le strutture di dati fisiche create nel servizio di ricerca, pertanto non sono presenti molte modifiche allo schema che è possibile apportare senza incorrere in una ricompilazione completa.

Aggiornamenti senza ricompilazione

Nell'elenco seguente vengono enumerate le modifiche dello schema che possono essere introdotte facilmente in un indice esistente. In genere, l'elenco include nuovi campi e funzionalità usati durante l'esecuzione della query.

• Aggiungere una descrizione dell'indice
• Aggiungere un nuovo campo
• Impostare l'attributo retrievable in un campo esistente
• Aggiornare searchAnalyzer in un campo con un oggetto esistente indexAnalyzer
• Aggiungere una nuova definizione dell'analizzatore in un indice (che può essere applicato ai nuovi campi)
• Aggiungere, aggiornare o eliminare profili di punteggio
• Aggiungere, aggiornare o eliminare mappe sinonimi
• Aggiungere, aggiornare o eliminare configurazioni semantiche
• Aggiungere, aggiornare o eliminare le impostazioni CORS

L'ordine delle operazioni è:

1. Ottenere la definizione dell'indice.

2. Rivedere lo schema con gli aggiornamenti dell'elenco precedente.

3. Aggiornare lo schema dell'indice nel servizio di ricerca.

4. Aggiornare il contenuto dell'indice in modo che corrisponda allo schema modificato se è stato aggiunto un nuovo campo. Per tutte le altre modifiche, il contenuto indicizzato esistente viene usato as-is.

Quando si aggiorna uno schema di indice per includere un nuovo campo, ai documenti esistenti nell'indice viene assegnato un valore Null per tale campo. Nel processo di indicizzazione successivo i valori dei dati di origine esterna sostituiscono i valori Null aggiunti da Azure AI Search.

Non dovrebbero verificarsi interruzioni delle query durante gli aggiornamenti, ma i risultati delle query variano in base all'effetto degli aggiornamenti.

Aggiornamenti che richiedono una ricompilazione

Alcune modifiche richiedono un'eliminazione e la ricompilazione dell'indice, sostituendo un indice corrente con uno nuovo.

L'ordine delle operazioni è:

1. Ottenere una definizione di indice nel caso in cui sia necessario per riferimento futuro o usare come base per una nuova versione.

2. Prendere in considerazione l'uso di una soluzione di backup e ripristino per mantenere una copia del contenuto dell'indice. Esistono soluzioni in C# e in Python. È consigliabile usare la versione Python perché è più aggiornata.

   Se hai capacità nel tuo servizio di ricerca, mantieni l'indice esistente durante la creazione e il test di quello nuovo.

3. Eliminare l'indice esistente. Le query destinate all'indice vengono eliminate immediatamente. Tenere presente che l'eliminazione di un indice è irreversibile, eliminando l'archiviazione fisica per la raccolta di campi e altri costrutti.

4. Pubblicare un indice modificato, in cui il corpo della richiesta include definizioni e configurazioni di campo modificate.

5. Caricare l'indice con i documenti da un'origine esterna. I documenti vengono indicizzati usando le definizioni dei campi e le configurazioni del nuovo schema.

Quando si crea l'indice, l'archiviazione fisica viene allocata per ogni campo nello schema dell'indice, con un indice invertito creato per ogni campo ricercabile e un indice vettoriale creato per ogni campo vettoriale. I campi che non sono ricercabili possono essere usati nei filtri o nelle espressioni, ma non hanno indici invertiti e non sono ricercabili per il testo completo o in modo approssimativo. In una ricompilazione dell'indice, questi indici invertiti e gli indici vettoriali vengono eliminati e ricreati in base allo schema di indice specificato.

Per ridurre al minimo l'interruzione del codice dell'applicazione, è consigliabile creare un alias di indice. Il codice dell'applicazione fa riferimento all'alias, ma è possibile aggiornare il nome dell'indice a cui punta l'alias.

Aggiungere una descrizione dell'indice

Un indice ha una description proprietà che è possibile specificare e usare quando un sistema deve accedere a più indici e prendere una decisione in base alla descrizione. Si consideri un server MCP (Model Context Protocol) che deve selezionare l'indice corretto in fase di esecuzione. La decisione può essere basata sulla descrizione anziché solo sul nome dell'indice.

Una descrizione dell'indice è un aggiornamento dello schema ed è possibile aggiungerla senza dover ricompilare l'intero indice.

• La lunghezza della stringa è massima di 4.000 caratteri.
• Il contenuto deve essere leggibile, in Unicode. Il caso d'uso deve determinare quale lingua usare.

È possibile aggiungere una descrizione dell'indice tramite il portale di Azure, l'API REST stabile più recente o un pacchetto Azure SDK che fornisce la funzionalità.

Bilanciamento dei carichi di lavoro

L'indicizzazione non viene eseguita in background, ma il servizio di ricerca bilancia tutti i processi di indicizzazione rispetto alle query in corso. Durante l'indicizzazione, è possibile monitorare le richieste di query nel portale di Azure per assicurarsi che le query vengano completate in modo tempestivo.

Se l'indicizzazione dei carichi di lavoro introduce livelli inaccettabili di latenza delle query, eseguire l'analisi delle prestazioni ed esaminare questi suggerimenti sulle prestazioni per una potenziale mitigazione.

Verificare la disponibilità di aggiornamenti

È possibile iniziare a eseguire query su un indice non appena viene caricato il primo documento. Se si conosce l'ID di un documento, l'API REST Ricerca documento restituisce il documento specifico. Per un test più ampio, è necessario attendere fino a quando l'indice non viene caricato completamente e quindi usare le query per verificare il contesto previsto.

È possibile usare Esplora ricerche o un client REST per verificare la disponibilità di contenuto aggiornato.

Se è stato aggiunto o rinominato un campo, usare select per restituire il campo:

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

Il portale di Azure fornisce le dimensioni dell'indice e le dimensioni dell'indice vettoriale. È possibile controllare questi valori dopo l'aggiornamento di un indice, ma ricordarsi di aspettarsi un piccolo ritardo durante l'elaborazione della modifica e per tenere conto delle frequenze di aggiornamento del portale, che possono essere pochi minuti.

Risolvere i problemi di reindicizzazione

Nella tabella seguente sono elencati i problemi comuni durante l'aggiornamento o la ricompilazione degli indici e come risolverli.

Vedere anche

• Panoramica dell'indicizzatore
• Eliminare documenti da un indice di ricerca
• Indicizzare set di dati di grandi dimensioni su larga scala
• Indicizzazione nel portale di Azure
• database SQL di Azure indicizzatore
• Azure Cosmos DB per NoSQL indicizzatore
• Indicizzatore di BLOB di Azure
• indicizzatore di tabelle Azure
• Dati, privacy e protezioni predefinite