Condividi tramite

Indicizzare dati da Azure Cosmos DB for NoSQL per query in Azure AI Search

  • Articolo

Questo articolo illustra come configurare un indicizzatore che importa contenuto da Azure Cosmos DB for NoSQL e lo rende ricercabile in Azure AI Search.

Questo articolo integra Creare un indicizzatore con informazioni specifiche per Cosmos DB. Usa le API REST e portale di Azure per illustrare un flusso di lavoro in tre parti comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione di dati si verifica all’invio della richiesta Crea indicizzatore.

Poiché la terminologia può talvolta creare confusione, vale la pena notare che l'indicizzazione di Azure Cosmos DB e l'indicizzazione di Azure AI Search sono operazioni diverse. L'indicizzazione in Azure AI Search crea e carica un indice di ricerca nel servizio di ricerca.

Prerequisiti

Per esaminare gli esempi in questo articolo, è necessario il portale di Azure o un client REST. Se si usa portale di Azure, assicurarsi che l'accesso a tutte le reti pubbliche sia abilitato. Altri approcci per la creazione di un indicizzatore Cosmos DB includono Azure SDK.

Provare con i dati di esempio

Usare queste istruzioni per creare un contenitore e un database in Cosmos DB a scopo di test.

  1. Scaricare HotelsData_toCosmosDB.JSON da GitHub per creare un contenitore in Cosmos DB che contiene un subset del set di dati degli hotel di esempio.

  2. Accedere al portale di Azure e creare un account, un database e un contenitore in Cosmos DB.

  3. In Cosmos DB selezionare Esplora dati per il nuovo contenitore, specificare i valori seguenti.

    Proprietà valore
    Database Crea nuovo
    ID database hotelsdb
    Produttività condivisa tra contenitori Non selezionare
    ID contenitore hotels
    Chiave di partizione /HotelId
    Produttività del contenitore (scalabilità automatica) Scalabilità automatica
    Valore massimo di UR/sec del contenitore 1000

  4. In Esplora dati espandere hotelsdb e *hotels" e quindi selezionare Elementi.

  5. Selezionare Carica elemento e quindi selezionare HotelsData_toCosmosDB.JSON file scaricato da GitHub.

  6. Fare clic con il pulsante destro del mouse su Elementi e scegliere Nuova query SQL. La query predefinita è SELECT * FROM c.

  7. Selezionare Esegui query per eseguire la query e visualizzare i risultati. Dovresti avere 50 documenti hotel.

Ora che si dispone di un contenitore, è possibile usare il portale di Azure, il client REST o Azure SDK per indicizzare i dati.

Il campo Descrizione fornisce il contenuto più dettagliato. È consigliabile specificare come destinazione questo campo per la ricerca full-text e le query vettoriali facoltative.

Usare il portale di Azure

È possibile usare la procedura guidata Importa dati o Importare e vettorizzare i dati per automatizzare l'indicizzazione da una tabella o una vista di database SQL. La configurazione dell'origine dati è simile per entrambe le procedure guidate.

  1. Avvia la procedura guidata.

  2. In Connetti ai dati selezionare o verificare che il tipo di origine dati sia Azure Cosmos DB o un account NoSQL.

    Il nome dell'origine dati fa riferimento all'oggetto connessione all'origine dati in Ricerca di intelligenza artificiale di Azure. Se si usa la procedura guidata vettoriale, il nome dell'origine dati viene generato automaticamente usando un prefisso personalizzato specificato alla fine del flusso di lavoro della procedura guidata.

  3. Specificare il nome e la raccolta del database. La query è facoltativa. È utile se si hanno dati gerarchici e si vuole importare una sezione specifica.

  4. Specificare un metodo di autenticazione, ovvero un'identità gestita o una chiave API predefinita. Se non si specifica una connessione di identità gestita, il portale di Azure usa la chiave.

    Se si configura Ricerca intelligenza artificiale di Azure per l'uso di un'identità gestita e si crea un'assegnazione di ruolo in Cosmos DB che concede autorizzazioni di lettura e lettura dati predefinita di Cosmos DB all'identità, l'indicizzatore può connettersi a Cosmos DB usando l'ID e i ruoli di Microsoft Entra.

  5. Per la procedura guidata Importa e vettorizza dati , è possibile specificare le opzioni per il rilevamento delle modifiche e dell'eliminazione.

    Il rilevamento delle modifiche è supportato per impostazione predefinita tramite un _ts campo (timestamp). Se si carica il contenuto usando l'approccio descritto in Provare con i dati di esempio, la raccolta viene creata con un _ts campo.

    Per il rilevamento dell'eliminazione è necessario disporre di un campo di primo livello preesistente nella raccolta che può essere usato come flag di eliminazione temporanea. Deve essere un campo booleano (è possibile denominarlo IsDeleted). Specificare true come valore di eliminazione temporanea. Nell'indice di ricerca aggiungere un campo di ricerca corrispondente denominato IsDeleted impostato su recuperabile e filtrabile.

  6. Continuare con i passaggi rimanenti per completare la procedura guidata:

Usare le API REST

Questa sezione illustra le chiamate API REST che creano un'origine dati, un indice e un indicizzatore.

Definire l'origine dati

La definizione dell'origine dati specifica i dati da indicizzare e credenziali e criteri per identificare modifiche nei dati. Un'origine dati è una risorsa indipendente che può essere usata da più indicizzatori.

  1. Creare o aggiornare un'origine dati per impostarne la definizione:

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
      "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": {
      "name": "[my-cosmos-db-collection]",
      "query": null
    },
    "dataChangeDetectionPolicy": {
      "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "  highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": null,
    "encryptionKey": null,
    "identity": null
}

  2. Impostare "type" su "cosmosdb" (obbligatorio). Se si usa un'API di ricerca precedente, versione 2017-11-11, la sintassi per "type" è "documentdb". In caso contrario, per 2019-05-06 e versioni successive, usare "cosmosdb".

  3. Impostare "credentials" su una stringa di connessione. Nella sezione successiva vengono descritti i formati supportati.

  4. Impostare "container" sulla raccolta. La proprietà "name" è obbligatoria e specifica l'ID della raccolta di database da indicizzare. La proprietà "query" è facoltativa. Usarla per rendere flat un documento JSON arbitrario così da ottenere uno schema flat che può essere indicizzato da Azure AI Search.

  5. Impostare "dataChangeDetectionPolicy" se i dati sono volatili e si desidera che l'indicizzatore rilevi solo gli elementi nuovi e aggiornati nelle esecuzioni successive.

  6. Impostare "dataDeletionDetectionPolicy" se si vogliono rimuovere i documenti di ricerca da un indice di ricerca quando l'elemento di origine viene eliminato.

Credenziali e stringhe di connessione supportate

Gli indicizzatori possono connettersi a una raccolta usando le connessioni seguenti.

Evitare i numeri di porta nell'URL dell'endpoint. Se si include il numero di porta, la connessione non riesce.

Stringa di connessione per accesso completo
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }`
È possibile ottenere la stringa di connessione dalla pagina dell'account Azure Cosmos DB nel portale di Azure selezionando Chiavi nel riquadro di spostamento a sinistra. Assicurarsi di selezionare una stringa di connessione completa e non soltanto una chiave.
Stringa di connessione con identità gestita
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }
Questa stringa di connessione non richiede una chiave dell'account, ma necessita che si disponga di un servizio di ricerca in grado di connettersi usando un'identità gestita. Per connessioni indirizzate all'API SQL, è possibile omettere ApiKind dalla stringa di connessione. Per altre informazioni su ApiKind, IdentityAuthType vedere Configurare una connessione dell'indicizzatore a un database di Azure Cosmos DB tramite un'identità gestita.

Utilizzo di query per formare dati indicizzati

Nella proprietà "query" in "contenitore" è possibile specificare una query SQL per rendere flat proprietà o matrici annidate, proiettare proprietà JSON e filtrare i dati da indicizzare.

Documento di esempio:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Query di filtro:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Query di appiattimento:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Query di proiezione:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Query di appiattimento matrici:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Query non supportate (DISTINCT e GROUP BY)

Le query che usano la parola chiave DISTINCT o clausola GROUP BY non sono supportate. Ricerca di intelligenza artificiale di Azure si basa sulla paginazione query SQL per elencare completamente i risultati della query. Né la clausola DISTINCT né GROUP BY sono compatibili con i token di continuazione usati per impaginare risultati.

Esempi di query non supportate:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Sebbene Azure Cosmos DB offra una soluzione alternativa per supportare la paginazione di query SQL con la parola chiave DISTINCT usando la clausola ORDER BY, questa non è compatibile con Azure AI Search. La query restituisce un singolo valore JSON, mentre Azure AI Search necessita di un oggetto JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Aggiungere campi di ricerca a un indice

In un indice di ricerca, aggiungere campi per accettare i documenti JSON di origine o l'output della proiezione di query personalizzata. Verificare che lo schema dell'indice di ricerca sia compatibile con i dati di origine. Per contenuto in Azure Cosmos DB, lo schema dell'indice di ricerca deve corrispondere agli elementi di Azure Cosmos DB nell'origine dati.

  1. Creare o aggiornare un indice per definire i campi di ricerca in cui sono archiviati i dati:

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

  2. Creare un campo chiave documento ("chiave": true). Per le raccolte partizionate, la chiave di documento predefinita è la proprietà _rid di Azure Cosmos DB, che Azure AI Search rinomina automaticamente come rid perché i nomi di campo non possono iniziare con un carattere di sottolineatura. Inoltre, i valori _rid di Azure Cosmos DB contengono caratteri non validi per chiavi di Azure AI Search. Per questo motivo, i valori _rid presentano la codificata Base64.

  3. Creare altri campi per rendere il contenuto più ricercabile. Per altri dettagli, vedere Creare un indice.

Mapping di tipi di dati

Tipi di dati JSON Tipi di campo di Azure AI Search
Bool Edm.Boolean, Edm.String
Numeri che rappresentano numeri interi Edm.Int32, Edm.Int64, Edm.String
Numeri che rappresentano numeri a virgola mobile Edm.Double, Edm.String
String Edm.String
Matrici di tipi primitivi, ad esempio ["a", "b", "c"] Collection(Edm.String)
Stringhe che rappresentano date Edm.DateTimeOffset, Edm.String
Oggetti GeoJSON, ad esempio { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Altri oggetti JSON N/D

Configurare ed eseguire l'indicizzatore Azure Cosmos DB for NoSQL

Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore. La configurazione dell'indicizzatore specifica gli input, i parametri e le proprietà che controllano i comportamenti della fase di esecuzione.

  1. Creare o aggiornare l'indicizzatore assegnandogli un nome e il riferimento all’origine dati e all'indice di destinazione:

    POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo oppure se sono necessarie più versioni di un campo di origine nell'indice di ricerca.

  3. Per ulteriori informazioni su altre proprietà, vedere Creare un indicizzatore.

Un indicizzatore viene eseguito automaticamente al momento della sua creazione. È possibile ovviare a questo problema impostando "disabilitato" su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.

Controllare lo stato dell'indicizzatore

Per monitorare lo stato dell'indicizzatore e la cronologia di esecuzione, controllare la cronologia di esecuzione dell'indicizzatore nella portale di Azure o inviare un'API REST Get Indexer Status (Ottieni stato dell'indicizzatore)

  1. Nella pagina del servizio di ricerca aprire Indicizzatori di gestione>della ricerca.

  2. Selezionare un indicizzatore per accedere alla cronologia di configurazione ed esecuzione.

  3. Selezionare un processo dell'indicizzatore specifico per visualizzare dettagli, avvisi ed errori.

La cronologia di esecuzione contiene fino a 50 esecuzioni completate più recenti in ordine cronologico inverso, in modo che l'esecuzione più recente venga visualizzata per prima.

Indicizzazione di documenti nuovi e modificati

Dopo che un indicizzatore ha popolato completamente un indice di ricerca, può essere utile che le esecuzioni successive indicizzino in modo incrementale solo i documenti nuovi e modificati nel database.

Per abilitare l'indicizzazione incrementale, impostare la proprietà "dataChangeDetectionPolicy" nella definizione dell'origine dati. Questa proprietà indica all'indicizzatore quale meccanismo di rilevamento delle modifiche viene usato sui dati.

Per gli indicizzatori di Azure Cosmos DB, l'unico criterio supportato è HighWaterMarkChangeDetectionPolicy che usa la proprietà _ts (timestamp) fornita da Azure Cosmos DB.

L'esempio seguente mostra una definizione dell'origine dati con un criterio di rilevamento delle modifiche:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Nota

Quando si assegna un valore null a un campo in Azure Cosmos DB, l'indicizzatore di ricerca di intelligenza artificiale non è in grado di distinguere tra null e un valore di campo mancante. Pertanto, se un campo nell'indice è vuoto, non verrà sostituito con un valore null, anche se tale modifica è stata apportata specificamente nel database.

Indicizzazione incrementale e query personalizzate

Se si usa una query personalizzata per recuperare documenti, assicurarsi che la query ordini i risultati in base alla colonna _ts. Ciò consente la creazione di checkpoint periodici, che vengono usati da Azure AI Search per fornire l'avanzamento incrementale in caso di errori.

In alcuni casi, anche se la query contiene una clausola ORDER BY [collection alias]._ts, è possibile che Azure AI Search non deduca che la query è ordinata in base a _ts. È possibile indicare ad Azure AI Search che i risultati sono ordinati impostando la proprietà di configurazione assumeOrderByHighWaterMarkColumn.

Per specificare questo hint, creare o aggiornare la definizione dell'indicizzatore come indicato di seguito:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Indicizzazione di documenti eliminati

Quando si eliminano righe dalla raccolta, in genere le si elimina anche dall'indice di ricerca. Scopo dei criteri di rilevamento dell'eliminazione dei dati è quello di identificare in modo efficace gli elementi di dati eliminati. Attualmente, l'unico criterio supportato è il criterio Soft Delete (l'eliminazione è contrassegnata da un tipo di flag), specificato nella definizione dell'origine dati come segue:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Se si usa una query personalizzata, assicurarsi che la proprietà a cui fa riferimento softDeleteColumnName sia proiettata dalla query.

softDeleteColumnName deve essere un campo di primo livello nell'indice. L'uso di campi annidati all'interno di tipi di softDeleteColumnName dati complessi non è supportato.

L'esempio seguente crea un'origine dati con criteri di eliminazione temporanea:

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Usare .NET

Per dati ai quali si è effettuato l’accesso tramite il protocollo API SQL, è possibile usare .NET SDK per automatizzare con indicizzatori. È consigliabile esaminare le sezioni precedenti dell'API REST per apprenderne concetti, flussi di lavoro e requisiti. Consultare quindi la seguente documentazione di riferimento sull'API .NET per implementare un indicizzatore JSON nel codice gestito:

Passaggi successivi

Ora è possibile controllare come eseguire l'indicizzatore, monitorare lo stato o pianificare l'esecuzione dell'indicizzatore. Gli articoli seguenti riguardano gli indicizzatori che eseguono il pull di contenuto da Azure Cosmos DB: