Indicizzare i dati da Azure Cosmos DB for Apache Gremlin per le query in Azure AI Search

  • Articolo

Importante

L'indicizzatore di Azure Cosmos DB for Apache Gremlin è attualmente disponibile in anteprima pubblica nel quadro delle Condizioni supplementari per l'utilizzo. Attualmente l'SDK non è supportato.

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

Questo articolo integra Creare un indicizzatore con informazioni specifiche per Cosmos DB. Esso usa le API REST per illustrare un flusso di lavoro a tre passaggi 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

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 è definita come risorsa indipendente affinché possa essere usata da più indicizzatori.

Per questa chiamata, specificare una versione dell'API REST di anteprima per creare un'origine dati che si connette tramite Azure Cosmos DB for Apache Gremlin. È possibile usare 2021-04-01-preview o versione successiva. È consigliabile usare l'API di anteprima più recente.

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

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

  2. Impostare "type" su "cosmosdb" (obbligatorio).

  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 del grafo.

    La proprietà "query" è facoltativa. Per impostazione predefinita, l'indicizzatore di Azure AI Search per Azure Cosmos DB for Apache Gremlin rende ogni vertice nel grafo un documento nell'indice. Gli archi verranno ignorati. Il valore predefinito della query è g.V(). In alternativa, è possibile impostare la query in modo da indicizzare solo gli archi. Per indicizzare gli archi, impostare la query su g.E().

  5. Impostare "dataChangeDetectionPolicy" se i dati sono volatili e si vuole che l'indicizzatore recuperi solo gli elementi nuovi e aggiornati nelle esecuzioni successive. L'avanzamento incrementale verrà abilitato per impostazione predefinita usando _ts come colonna del limite massimo.

  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. Per le connessioni destinate ad Azure Cosmos DB for Apache Gremlin, assicurarsi di includere "ApiKind" nella stringa di connessione.

Evitare di inserire numeri di porta nell'URL dell'endpoint. Se si include il numero di porta, la connessione avrà esito negativo.

Stringa di connessione per l'accesso completo
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
È possibile ottenere la stringa di connessione dalla pagina dell'account Azure Cosmos DB nel portale di Azure selezionando Chiavi nel riquadro di spostamento sinistro. Assicurarsi di selezionare una stringa di connessione completa e non soltanto una chiave.
Stringa di connessione dell'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];)" }
Questa stringa di connessione non richiede una chiave dell'account, ma è necessario aver precedentemente configurato un servizio di ricerca per la connessione tramite un'identità gestita e aver creato un'assegnazione di ruolo che concede le autorizzazioni del Ruolo Lettore dell'account Cosmos DB. Per altre informazioni, vedere Configurare una connessione dell'indicizzatore a un database di Azure Cosmos DB usando un'identità gestita.

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 il grafo. Per il 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 che archivieranno i dati:

     POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
    "name": "mysearchindex",
    "fields": [
     {
         "name": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     },{
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

  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 campi aggiuntivi per rendere il contenuto più ricercabile. Per altri dettagli, vedere Creare un indice.

Mapping di tipi di dati

Tipo 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 di Azure Cosmos DB

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-05-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-gremlin-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, inviare una richiesta Ottieni stato dell’indicizzatore:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe risultare simile all'esempio seguente:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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"
},

Indicizzazione di documenti eliminati

Quando i dati del grafo vengono eliminati, è possibile eliminare dall'indice di ricerca anche il documento corrispondente. Lo scopo di un criterio di rilevamento dell'eliminazione dei dati è quello di identificare in modo efficace gli elementi di dati eliminati ed eliminare l'intero documento dall'indice. Il criterio di rilevamento dell'eliminazione dei dati non è progettato per eliminare informazioni parziali del documento. 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"
}

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

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

{
    "name": "[my-cosmosdb-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "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"
    }
}

Anche se si abilita il criterio di rilevamento dell'eliminazione, l'eliminazione di campi complessi (Edm.ComplexType) dall'indice non è supportata. Questo criterio richiede che la colonna 'active' nel database Gremlin sia di tipo Integer, stringa o booleano.

Mapping dei dati del grafo ai campi in un indice di ricerca

L'indicizzatore di Azure Cosmos DB for Apache Gremlin eseguirà automaticamente il mapping di alcune parti di dati del grafo:

  1. L'indicizzatore eseguirà il mapping di _rid a un campo rid nell'indice, se esistente, e ne eseguirà la codifica Base64.

  2. L'indicizzatore eseguirà il mapping di _id a un campo id nell'indice, se esistente.

  3. Quando si eseguono query sul database di Azure Cosmos DB usando Azure Cosmos DB for Apache Gremlin, è possibile notare che l'output JSON per ogni proprietà ha un id e un value. L'indicizzatore eseguirà automaticamente il mapping delle proprietà value in un campo nell'indice di ricerca con lo stesso nome della proprietà, se esistente. Nell'esempio seguente viene eseguito il mapping di 450 a un campo pages nell'indice di ricerca.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

Potrebbe essere necessario usare mapping dei campi di output per eseguire il mapping dell'output della query ai campi nell'indice. Probabilmente si vorranno usare mapping dei campi di output anziché mapping dei campi poiché la query personalizzata avrà probabilmente dati complessi.

Si supponga, ad esempio, che la query produca questo output:

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

Se si vuole eseguire il mapping del valore di pages nel codice JSON precedente a un campo totalpages nell'indice, è possibile aggiungere il mapping dei campi di output alla definizione dell'indicizzatore:

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

Si noti che il mapping dei campi di output inizia con /document e non include un riferimento alla chiave delle proprietà nel codice JSON. Questo perché l'indicizzatore inserisce ogni documento nel nodo /document al momento dell'inserimento dei dati del grafo. L'indicizzatore consente inoltre di fare riferimento automaticamente al valore di pages con un riferimento semplice a pages, senza bisogno di fare riferimento al primo oggetto nella matrice di pages.

Passaggi successivi