Dela via

Indexering av data från Azure Cosmos DB för Apache Gremlin för frågor i Azure AI Search

  • Artikel

Viktigt!

Azure Cosmos DB för Apache Gremlin-indexeraren är för närvarande i offentlig förhandsversion under kompletterande användningsvillkor. För närvarande finns det inget SDK-stöd.

I den här artikeln får du lära dig hur du konfigurerar en indexerare som importerar innehåll från Azure Cosmos DB för Apache Gremlin och gör det sökbart i Azure AI Search.

Den här artikeln kompletterar Skapa en indexerare med information som är specifik för Cosmos DB. Den använder REST-API:er för att demonstrera ett arbetsflöde i tre delar som är gemensamt för alla indexerare: skapa en datakälla, skapa ett index, skapa en indexerare. Dataextrahering sker när du skickar begäran skapa indexerare.

Eftersom terminologin kan vara förvirrande är det värt att notera att Azure Cosmos DB-indexering och Azure AI Search-indexering är olika åtgärder. Indexering i Azure AI Search skapar och läser in ett sökindex i söktjänsten.

Förutsättningar

  • Registrera dig för förhandsversionen för att ge feedback om scenariot. Du kan komma åt funktionen automatiskt efter att formuläret har lämnats in.

  • Ett Azure Cosmos DB-konto, en databas, en container och ett objekt. Använd samma region för både Azure AI Search och Azure Cosmos DB för lägre svarstid och för att undvika bandbreddsavgifter.

  • En automatisk indexeringsprincip för Azure Cosmos DB-samlingen, inställd på Konsekvent. Det här är standardkonfigurationen. Lat indexering rekommenderas inte och kan leda till att data saknas.

  • Läsbehörigheter. En "fullständig åtkomst" niska veze innehåller en nyckel som ger åtkomst till innehållet, men om du använder Azure-roller kontrollerar du att söktjänstens hanterade identitet har behörigheter för Cosmos DB-kontoläsare.

  • En REST-klient för att skapa datakällan, indexet och indexeraren.

Definiera datakällan

Datakällans definition anger vilka data som ska indexeras, autentiseringsuppgifter och principer för att identifiera ändringar i data. En datakälla definieras som en oberoende resurs så att den kan användas av flera indexerare.

För det här anropet anger du en REST API-förhandsversion för att skapa en datakälla som ansluter via en Azure Cosmos DB för Apache Gremlin. Du kan använda 2021-04-01-preview eller senare. Vi rekommenderar det senaste förhandsversions-API:et.

  1. Skapa eller uppdatera en datakälla för att ange dess definition:

     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. Ange "typ" till "cosmosdb" (krävs).

  3. Ange "autentiseringsuppgifter" till en niska veze. I nästa avsnitt beskrivs de format som stöds.

  4. Ange "container" till samlingen. Egenskapen "name" krävs och anger diagrammets ID.

    Egenskapen "query" är valfri. Som standard gör Azure AI Search-indexeraren för Azure Cosmos DB för Apache Gremlin varje hörn i diagrammet till ett dokument i indexet. Kanter ignoreras. Frågestandarden är g.V(). Du kan också ange att frågan endast ska indexeras i kanterna. Om du vill indexeras kanterna ställer du in frågan på g.E().

  5. Ange "dataChangeDetectionPolicy" om data är flyktiga och du vill att indexeraren bara ska hämta de nya och uppdaterade objekten vid efterföljande körningar. Inkrementell förlopp aktiveras som standard med som _ts högvattenmärkeskolumn.

  6. Ange "dataDeletionDetectionPolicy" om du vill ta bort sökdokument från ett sökindex när källobjektet tas bort.

Autentiseringsuppgifter och niska veze som stöds

Indexerare kan ansluta till en samling med hjälp av följande anslutningar. För anslutningar som riktar in sig på Azure Cosmos DB för Apache Gremlin måste du inkludera "ApiKind" i niska veze.

Undvik portnummer i slutpunkts-URL:en. Om du inkluderar portnumret misslyckas anslutningen.

Fullständig åtkomst niska veze
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Du kan hämta niska veze från Azure Cosmos DB-kontosidan i Azure-portalen genom att välja Nycklar i det vänstra navigeringsfönstret. Se till att välja en fullständig niska veze och inte bara en nyckel.
Hanterad identitet niska veze
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Den här niska veze kräver ingen kontonyckel, men du måste tidigare ha konfigurerat en söktjänst för att ansluta med hjälp av en hanterad identitet och skapat en rolltilldelning som ger behörigheter för Cosmos DB-kontoläsare. Mer information finns i Konfigurera en indexerareanslutning till en Azure Cosmos DB-databas med hjälp av en hanterad identitet .

Lägga till sökfält i ett index

I ett sökindex lägger du till fält för att acceptera JSON-källdokumenten eller utdata från din anpassade frågeprojektion. Kontrollera att sökindexschemat är kompatibelt med diagrammet. För innehåll i Azure Cosmos DB ska ditt sökindexschema motsvara Azure Cosmos DB-objekten i datakällan.

  1. Skapa eller uppdatera ett index för att definiera sökfält som lagrar data:

     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. Skapa ett dokumentnyckelfält ("nyckel": sant). För partitionerade samlingar är standarddokumentnyckeln egenskapen Azure Cosmos DB _rid , som Azure AI Search automatiskt byter namn till rid eftersom fältnamn inte kan börja med ett understreck. Azure Cosmos DB-värden _rid innehåller också tecken som är ogiltiga i Azure AI Search-nycklar. Därför _rid är värdena Base64-kodade.

  3. Skapa ytterligare fält för mer sökbart innehåll. Mer information finns i Skapa ett index .

Mappa datatyper

JSON-datatyp Fälttyper för Azure AI Search
Bool Edm.Boolean, Edm.String
Tal som ser ut som heltal Edm.Int32, Edm.Int64, Edm.String
Tal som ser ut som flyttalspunkter Edm.Double, Edm.String
String Edm.String
Matriser med primitiva typer som ["a", "b", "c"] Collection(Edm.String)
Strängar som ser ut som datum Edm.DateTimeOffset, Edm.String
GeoJSON-objekt som { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Andra JSON-objekt Ej tillämpligt

Konfigurera och köra Azure Cosmos DB-indexeraren

När indexet och datakällan har skapats är du redo att skapa indexeraren. Indexerarens konfiguration anger indata, parametrar och egenskaper som styr körningstidsbeteenden.

  1. Skapa eller uppdatera en indexerare genom att ge den ett namn och referera till datakällan och målindexet:

    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. Ange fältmappningar om det finns skillnader i fältnamn eller typ, eller om du behöver flera versioner av ett källfält i sökindexet.

  3. Mer information om andra egenskaper finns i Skapa en indexerare .

En indexerare körs automatiskt när den skapas. Du kan förhindra detta genom att ange "inaktiverad" till true. Om du vill kontrollera indexerarens körning kör du en indexerare på begäran eller sätter den enligt ett schema.

Kontrollera status för indexerare

Om du vill övervaka indexerarens status och körningshistorik skickar du en get indexer-statusbegäran :

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

Svaret innehåller status och antalet bearbetade objekt. Det bör se ut ungefär som i följande exempel:

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

Körningshistoriken innehåller upp till 50 av de senast slutförda körningarna, som sorteras i omvänd kronologisk ordning så att den senaste körningen kommer först.

Indexera nya och ändrade dokument

När en indexerare har fyllt i ett sökindex helt kan det vara bra att efterföljande indexerare körs för att stegvis indexera bara de nya och ändrade dokumenten i databasen.

Om du vill aktivera inkrementell indexering anger du egenskapen "dataChangeDetectionPolicy" i datakälldefinitionen. Den här egenskapen talar om för indexeraren vilken mekanism för ändringsspårning som används för dina data.

För Azure Cosmos DB-indexerare är HighWaterMarkChangeDetectionPolicy den enda princip som stöds att använda _ts egenskapen (tidsstämpel) som tillhandahålls av Azure Cosmos DB.

I följande exempel visas en datakällans definition med en princip för ändringsidentifiering:

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

Indexera borttagna dokument

När grafdata tas bort kanske du också vill ta bort motsvarande dokument från sökindexet. Syftet med en princip för identifiering av databorttagning är att effektivt identifiera borttagna dataobjekt och ta bort det fullständiga dokumentet från indexet. Principen för identifiering av databorttagning är inte avsedd att ta bort partiell dokumentinformation. För närvarande är Soft Delete den enda princip som stöds principen (borttagning markeras med en flagga av något slag), som anges i datakällans definition enligt följande:

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

I följande exempel skapas en datakälla med en princip för mjuk borttagning:

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

Även om du aktiverar borttagningsidentifieringsprincip stöds inte borttagning av komplexa (Edm.ComplexType) fält från indexet. Den här principen kräver att kolumnen "aktiv" i Gremlin-databasen ska vara av typen heltal, sträng eller boolesk.

Mappa diagramdata till fält i ett sökindex

Azure Cosmos DB för Apache Gremlin-indexeraren mappar automatiskt ett par diagramdata:

  1. Indexeraren mappas _rid till ett rid fält i indexet om det finns och Base64 kodar det.

  2. Indexeraren mappas _id till ett id fält i indexet om det finns.

  3. När du kör frågor mot din Azure Cosmos DB-databas med hjälp av Azure Cosmos DB för Apache Gremlin kanske du märker att JSON-utdata för varje egenskap har en id och en value. Indexeraren mappar automatiskt egenskaperna value till ett fält i ditt sökindex som har samma namn som egenskapen om den finns. I följande exempel mappas 450 till ett pages fält i sökindexet.

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

Du kanske upptäcker att du behöver använda mappningar för utdatafält för att mappa dina frågeutdata till fälten i indexet. Du vill förmodligen använda mappningar för utdatafält i stället för Fältmappningar eftersom den anpassade frågan sannolikt har komplexa data.

Anta till exempel att frågan genererar följande utdata:

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

Om du vill mappa värdet pages för i JSON ovan till ett totalpages fält i indexet kan du lägga till följande mappning av utdatafält i indexerarens definition:

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

Observera hur mappningen av utdatafält börjar med /document och inte innehåller någon referens till egenskapsnyckeln i JSON. Detta beror på att indexeraren placerar varje dokument under /document noden när du matar in grafdata och indexeraren också automatiskt låter dig referera till värdet pages för genom enkel referens pages i stället för att behöva referera till det första objektet i matrisen pagesi .

Nästa steg