Dati degli indici provenienti da Azure Cosmos DB per Apache Gremlin per le query in Azure AI Search (anteprima)

Il Azure Cosmos DB per l'indicizzatore Apache Gremlin (anteprima) importa contenuto da Azure Cosmos DB per Apache Gremlin e lo rende ricercabile in Azure AI Search.

Questo articolo integra l'articolo Creare un indicizzatore con informazioni specifiche di Cosmos DB. Usa le API REST 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 dei dati si verifica quando si invia la richiesta Crea indicizzatore.

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

Prerequisiti

• Completare il modulo di registrazione dell'anteprima dell'indicizzatore. La registrazione viene approvata automaticamente.

• Un account Azure Cosmos DB, un database, un contenitore e dei documenti. Usare la stessa area per Azure AI Search e Azure Cosmos DB per ridurre la latenza ed evitare addebiti per la larghezza di banda.

• Un criterio di indicizzazione automatico nella raccolta Azure Cosmos DB, impostato su Consistent. Questa impostazione è la configurazione predefinita. L'indicizzazione lazy non è consigliata e potrebbe comportare la mancanza di dati.

• Autorizzazioni di lettura. Una stringa di connessione per l'accesso completo include una chiave che concede l'accesso al contenuto, ma se si usano i ruoli di Azure, assicurarsi che l'identità gestita del servizio di ricerca abbia le autorizzazioni del Ruolo Lettore dell'account Cosmos DB.

• Client REST per creare l'origine dati, l'indice e l'indicizzatore.

Definire l'origine dati

La definizione dell'origine dati specifica i dati da indicizzare, credenziali e criteri per identificare le modifiche nei dati. Un'origine dati viene definita come risorsa indipendente in modo che possa essere usata da più indicizzatori.

Per questa chiamata, specificare una versione di anteprima dell'API REST per creare un'origine dati che si connette tramite Azure Cosmos DB per Apache Gremlin. È possibile usare 2021-04-01-preview o versioni successive. È consigliabile usare l'API REST 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=2026-08-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 grafico.

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

5. Impostare "dataChangeDetectionPolicy" se i dati sono volatili e si vuole che l'indicizzatore rilevi solo gli elementi nuovi e aggiornati nelle esecuzioni successive. Il progresso incrementale è abilitato per impostazione predefinita utilizzando _ts come colonna high water mark.

6. Impostare "dataDeletionDetectionPolicy" se si desidera 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 a Azure Cosmos DB per Apache Gremlin, assicurati di includere "ApiKind" nella stringa di connessione.

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

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 grafico. Per il contenuto in Azure Cosmos DB, lo schema dell'indice di ricerca deve corrispondere agli elementi 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=2026-08-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 del documento ("chiave": true). Per le raccolte partizionate, la chiave del documento predefinita è la proprietà Azure Cosmos DB _rid, che Azure AI Search rinomina automaticamente in rid perché i nomi dei campi non possono iniziare con un carattere di sottolineatura. Inoltre, Azure Cosmos DB _rid valori contengono caratteri non validi nelle chiavi di Azure AI Search. Per questo motivo, i _rid valori sono codificati in Base64.

3. Creare campi aggiuntivi per un contenuto più ricercabile. Per informazioni dettagliate, vedere Creare un indice .

Mapping dei tipi di dati

Configurare ed eseguire l'indicizzatore 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 di runtime.

1. Creare o aggiornare un indicizzatore assegnando un nome e facendo riferimento all'origine dati e all'indice di destinazione:

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-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 o se sono necessarie più versioni di un campo di origine nell'indice di ricerca.

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

Un indicizzatore viene eseguito automaticamente quando viene creato. È possibile evitare 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 Get Indexer Status :To monitor the indexer status and execution history, send a Get Indexer Status request:

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

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe essere 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 delle esecuzioni completate più di recente, ordinate in ordine cronologico inverso in modo che l'esecuzione più recente venga prima.

Indicizzazione di documenti nuovi e modificati

Dopo che un indicizzatore ha popolato completamente un indice di ricerca, è possibile che l'indicizzatore successivo venga eseguito per indicizzare 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 Azure Cosmos DB, l'unico criterio supportato è il HighWaterMarkChangeDetectionPolicy usando la proprietà _ts (timestamp) fornita da Azure Cosmos DB.

L'esempio seguente mostra una definizione di 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 anche il documento corrispondente dall'indice di ricerca. Lo scopo di un criterio di rilevamento dell'eliminazione dei dati è identificare in modo efficiente gli elementi di dati eliminati ed eliminare il documento completo dall'indice. I criteri di rilevamento dell'eliminazione dei dati non sono destinati a eliminare informazioni parziali sul documento. Attualmente, l'unica politica supportata è la Soft Delete politica (l'eliminazione è contrassegnata con un flag di qualche tipo), specificata nella definizione dell'origine dati di seguito.

"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=2026-08-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 abilitano i criteri 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, string o boolean.

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

L'indicizzatore Azure Cosmos DB per Apache Gremlin mappa automaticamente un paio di elementi dei dati del grafo:

1. L'indicizzatore esegue il mapping _rid a un rid campo nell'indice, se esistente, e Base64 lo codifica.

2. L'indicizzatore mappa _id a un campo id nell'indice, se esiste.

3. Quando si interroga il database Azure Cosmos DB usando Azure Cosmos DB per Apache Gremlin, è possibile notare che l'output JSON di ogni proprietà contiene un id e un value. L'indicizzatore mappa automaticamente la value della proprietà in un campo dell'indice di ricerca che ha lo stesso nome della proprietà, se esiste. Nell'esempio seguente viene eseguito il mapping di 450 a un pages campo nell'indice di ricerca.

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

Potrebbe essere necessario usare Output Field Mappings per mappare l'output della query ai campi dell'indice. Probabilmente vorrai usare le mappature dei campi di output anziché le mappature dei campi, poiché la query personalizzata contiene 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 totalpages campo nell'indice, è possibile aggiungere il mapping dei campi di output seguente 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. Ciò è dovuto al fatto che l'indicizzatore inserisce ogni documento sotto il nodo /document quando si inseriscono i dati del grafo e l'indicizzatore ti permette anche di fare riferimento automaticamente al valore di pages semplicemente riferendoti a pages, senza dover fare riferimento al primo oggetto nella matrice di pages.

Passaggi successivi

• Per altre informazioni sulle Azure Cosmos DB per Apache Gremlin, vedere Introduzione a Azure Cosmos DB: Azure Cosmos DB per Apache Gremlin.

• Per altre informazioni su scenari e prezzi Azure AI Search, vedere la pagina del servizio Search in azure.microsoft.com.

• Per informazioni sulla configurazione di rete per gli indicizzatori, vedere l'accesso Indexer al contenuto protetto da funzionalità di sicurezza di rete Azure.