Indexering av data från Azure Cosmos DB för Apache Gremlin för frågor i Azure AI-sökning (förhandsversion)

Azure Cosmos DB för Apache Gremlin-indexeraren (förhandsversion) importerar innehåll från Azure Cosmos DB för Apache Gremlin och gör det sökbart i Azure AI-sökning.

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 terminologi kan vara förvirrande är det värt att notera att Azure Cosmos DB indexering och Azure AI-sökning indexering är olika åtgärder. Indexering i Azure AI-sökning skapar och läser in ett sökindex i söktjänsten.

Förutsättningar

• Fyll i registreringsformuläret för indexerarens förhandsversion. Registreringen godkänns automatiskt.

• Ett Azure Cosmos DB konto, databas, container och objekt. Använd samma region för både Azure AI-sökning och Azure Cosmos DB för kortare svarstid och för att undvika bandbreddsavgifter.

• En automatisk indexeringsprincip i Azure Cosmos DB-samlingen, inställd på Consistent. Den här inställningen är standardkonfigurationen. Lat indexering rekommenderas inte och kan resultera i saknade data.

• Läsbehörigheter. En "fullständig åtkomst" anslutningssträng innehåller en nyckel som ger åtkomst till innehållet, men om du använder Azure-roller, kontrollerar du att search-tjänstens hanterade identitet har Cosmos DB-kontoläsareroll behörigheter.

• 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 Azure Cosmos DB för Apache Gremlin. Du kan använda 2021-04-01-preview eller senare. Vi rekommenderar den senaste förhandsversionen av REST-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=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. Ange "typ" till "cosmosdb" (krävs).

3. Ange "autentiseringsuppgifter" till en reťazec pripojenia. 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-sökning-indexeraren för Azure Cosmos DB för Apache Gremlin varje hörn i diagrammet till ett dokument i indexet. Kantlinjer 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 dina 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 är aktiverat som standard med högvattenmärkeskolumnen _ts .

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

Stödda autentiseringsuppgifter och anslutningssträngar

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

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

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 objekt 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=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. Skapa ett dokumentnyckelfält ("nyckel": sant). För partitionerade samlingar är standarddokumentnyckeln egenskapen Azure Cosmos DB _rid, som Azure AI-sökning automatiskt byter namn till rid eftersom fältnamn inte kan börja med ett understreckstecken. Dessutom innehåller Azure Cosmos DB _rid-värden tecken som är ogiltiga i Azure AI-sökning-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 .

Kartlägga datatyper

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=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. 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 indexerarens status

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=2026-08-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, och de sorteras i omvänd kronologisk ordning så att den senaste körningen visas 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 indexers är den enda princip som stöds den HighWaterMarkChangeDetectionPolicy som använder egenskapen _ts (tidsstämpel) tillhandahållen 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. Policyn för upptäckt av databorttagning är inte avsedd att ta bort delvis dokumentinformation. För närvarande är den enda policy som stöds Soft Delete-policyn (borttagning markeras med en flagga av något slag), som anges i definitionen av datakällan 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=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"
    }
}

Ä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 mappar _rid till ett rid fält i indexet om det finns och Base64 kodar det.

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

3. När du frågar 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 egenskapens 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 grafdata matas in och indexeraren också automatiskt låter dig referera till värdet av pages genom att enkelt referera till pages i stället för att behöva referera till det första objektet i matrisen pages i.

Nästa steg

• Mer information om Azure Cosmos DB för Apache Gremlin finns i Introduction to Azure Cosmos DB: Azure Cosmos DB for Apache Gremlin.

• Mer information om Azure AI-sökning scenarier och priser finns på tjänstsidan Search på azure.microsoft.com.

• Mer information om nätverkskonfiguration för indexerare finns i Indexer-åtkomst till innehåll som skyddas av Azure nätverkssäkerhetsfunktioner.