Azure AI Search trasforma dati grezzi in un index interrogabile a bassa latenza. Nei carichi di lavoro reali raramente si popola l’indice a mano via push API: si usa la pipeline pull, cioè un indexer che estrae automaticamente i documenti da una data source (Azure Blob Storage, Azure SQL, Cosmos DB, ADLS Gen2) e li proietta nell’index. Capire come questi tre oggetti si incastrano è il cuore della sezione “implement indexing” dell’AI-102.

Anatomia dell’index e attributi dei field

L’index è definito da uno schema di field, ognuno con un tipo (Edm.String, Edm.Int32, Collection(Edm.String), ecc.) e un set di attributi che ne governano il comportamento. La scelta degli attributi è una decisione architetturale, non cosmetica, perché ognuno costa storage e/o performance:

  • searchable — abilita la ricerca full-text con analisi linguistica (tokenizzazione, stemming). Solo per stringhe.
  • filterable — consente clausole $filter (match esatto, niente analisi linguistica).
  • facetable — abilita la navigazione a faccette (conteggi per categoria).
  • sortable — consente l’ordinamento con $orderby.
  • retrievable — determina se il valore torna nei risultati (disattivarlo su campi usati solo per filtrare riduce il payload).
  • key — il campo chiave univoco (un solo Edm.String per indice).

Regola pratica d’esame: attiva solo gli attributi che ti servono. Un campo lungo di testo descrittivo va searchable ma non filterable/facetable/sortable; un campo category va tipicamente filterable + facetable; un prezzo va filterable + sortable.

Data source e indexer

La data source è un oggetto che incapsula il tipo di origine, la connection string e il container/tabella target. L’indexer collega la data source all’index ed esegue l’estrazione secondo una schedule (schedule.interval, minimo 5 minuti) oppure on-demand. Con Blob Storage l’indexer sa estrarre testo e metadati da PDF, Office, JSON, CSV: il parsing mode (default, json, jsonArray, delimitedText) dice come interpretare i blob.

Field mapping

Spesso i nomi dei campi sorgente non coincidono con quelli dell’index, o servono trasformazioni. I field mappings collegano sourceFieldName → targetFieldName e possono applicare mapping functions, tipiche all’esame:

  • base64Encode / base64Decode — indispensabile quando il document key deriva da metadata_storage_path, che contiene caratteri non ammessi in una key: va codificato in Base64.
  • jsonArrayToStringCollection, splitting, urlEncode.

Esistono anche gli output field mappings, usati quando c’è uno skillset (AI enrichment) per portare i valori arricchiti dal document cracking verso i campi finali.

Change e deletion detection

Per gli aggiornamenti incrementali, l’indexer con Blob Storage usa nativamente la change detection basata su LastModified: alle esecuzioni successive reindicizza solo i blob modificati dopo l’ultimo timestamp (tracciato dall’high-water mark). La deletion detection invece NON è automatica: per rimuovere documenti cancellati si configura una soft delete policy, tipicamente:

  • Native blob soft delete (rileva i blob eliminati con soft delete di Storage), oppure
  • Custom metadata: un flag come IsDeleted = true sul blob che l’indexer interpreta per eliminare il documento dall’index.

Sicurezza dell’accesso alla sorgente

L’indexer deve autenticarsi verso la data source. Le opzioni: connection string con chiave/SAS, oppure — approccio raccomandato e molto testato — la managed identity (system-assigned o user-assigned) del servizio Search a cui si assegna un ruolo RBAC come Storage Blob Data Reader. Con storage dietro firewall serve una private endpoint / shared private link o l’eccezione “trusted Microsoft services”.

Trappole tipiche d’esame

  • Devi rendere filterable un campo dopo aver caricato milioni di documenti → gli attributi dei field sono immutabili dopo la creazione dell’index: occorre ricreare l’index (nuovo schema) e reindicizzare, non un semplice update.
  • L’indexer fallisce con “invalid document key” su Blob → la key deriva da metadata_storage_path: applica la mapping function base64Encode nel field mapping.
  • I documenti eliminati dallo storage restano nei risultati → la deletion detection non è automatica: configura una soft delete policy (native blob soft delete o custom metadata flag).
  • L’indexer restituisce 403 verso lo Storage → mancano i permessi: assegna una managed identity al servizio Search con ruolo Storage Blob Data Reader (o usa SAS), non basta la connection string se lo storage ha firewall.
  • Serve arricchimento AI (OCR, key phrase) prima di indicizzare → aggiungi uno skillset e usa gli output field mappings, non i semplici field mappings, per popolare i campi finali.