Gegevens indexeren uit Azure Cosmos DB voor Apache Gremlin voor query's in Azure AI Search

  • Artikel

Belangrijk

De indexeerfunctie van Azure Cosmos DB voor Apache Gremlin is momenteel beschikbaar als openbare preview onder aanvullende gebruiksvoorwaarden. Momenteel is er geen SDK-ondersteuning.

In dit artikel leert u hoe u een indexeerfunctie configureert waarmee inhoud uit Azure Cosmos DB voor Apache Gremlin wordt geïmporteerd en hoe u deze doorzoekbaar maakt in Azure AI Search.

Dit artikel is een aanvulling op Het maken van een indexeerfunctie met informatie die specifiek is voor Cosmos DB. Hierbij worden de REST API's gebruikt om een driedelige werkstroom te demonstreren die gebruikelijk is voor alle indexeerfuncties: een gegevensbron maken, een index maken, een indexeerfunctie maken. Gegevensextractie vindt plaats wanneer u de aanvraag Indexeerfunctie maken verzendt.

Omdat terminologie verwarrend kan zijn, is het de moeite waard om te vermelden dat azure Cosmos DB-indexering en Azure AI Search-indexering verschillende bewerkingen zijn. Indexering in Azure AI Search maakt en laadt een zoekindex in uw zoekservice.

Vereisten

  • Registreer u voor de preview om feedback over scenario's te geven. U hebt automatisch toegang tot de functie na het verzenden van formulieren.

  • Een Azure Cosmos DB-account, -database, -container en -items. Gebruik dezelfde regio voor zowel Azure AI Search als Azure Cosmos DB voor lagere latentie en om bandbreedtekosten te voorkomen.

  • Een automatisch indexeringsbeleid voor de Azure Cosmos DB-verzameling, ingesteld op Consistent. Dit is de standaard configuratie. Luie indexering wordt niet aanbevolen en kan leiden tot ontbrekende gegevens.

  • Leesmachtigingen. Een 'volledige toegang' verbindingsreeks bevat een sleutel die toegang verleent tot de inhoud, maar als u Azure-rollen gebruikt, moet u ervoor zorgen dat de door de zoekservice beheerde identiteit machtigingen heeft voor de rol lezer van het Cosmos DB-account.

  • Een REST-client voor het maken van de gegevensbron, index en indexeerfunctie.

De gegevensbron definiëren

De definitie van de gegevensbron geeft de gegevens op die moeten worden geïndexeerde, referenties en beleidsregels voor het identificeren van wijzigingen in de gegevens. Een gegevensbron wordt gedefinieerd als een onafhankelijke resource, zodat deze kan worden gebruikt door meerdere indexeerfuncties.

Geef voor deze aanroep een preview-REST API-versie op (2020-06-30-Preview of 2021-04-30-Preview) om een gegevensbron te maken die verbinding maakt via een Azure Cosmos DB voor Apache Gremlin.

  1. Een gegevensbron maken of bijwerken om de definitie ervan in te stellen:

     POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-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. Stel 'type' in op "cosmosdb" (vereist).

  3. Stel referenties in op een verbindingsreeks. In de volgende sectie worden de ondersteunde indelingen beschreven.

  4. Stel 'container' in op de verzameling. De eigenschap 'name' is vereist en geeft de id van de grafiek op.

    De eigenschap 'query' is optioneel. De Azure AI Search-indexeerfunctie voor Azure Cosmos DB voor Apache Gremlin maakt standaard elk hoekpunt in uw grafiek een document in de index. Randen worden genegeerd. De standaardinstelling voor de query is g.V(). U kunt de query ook instellen om alleen de randen te indexeren. Als u de randen wilt indexeren, stelt u de query in op g.E().

  5. Stel dataChangeDetectionPolicy in als de gegevens vluchtig zijn en u wilt dat de indexeerfunctie alleen de nieuwe en bijgewerkte items ophaalt bij volgende uitvoeringen. Incrementele voortgang wordt standaard ingeschakeld met behulp van _ts de kolom hoog watermarkering.

  6. Stel 'dataDeletionDetectionPolicy' in als u zoekdocumenten uit een zoekindex wilt verwijderen wanneer het bronitem wordt verwijderd.

Ondersteunde referenties en verbindingsreeks s

Indexeerfuncties kunnen verbinding maken met een verzameling met behulp van de volgende verbindingen. Voor verbindingen die zijn gericht op Azure Cosmos DB voor Apache Gremlin, moet u 'ApiKind' opnemen in de verbindingsreeks.

Vermijd poortnummers in de eindpunt-URL. Als u het poortnummer opneemt, mislukt de verbinding.

Volledige toegang verbindingsreeks
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
U kunt de verbindingsreeks ophalen op de azure Cosmos DB-accountpagina in Azure Portal door Sleutels te selecteren in het linkernavigatiedeelvenster. Zorg ervoor dat u een volledige verbindingsreeks en niet alleen een sleutel selecteert.
Beheerde identiteit verbindingsreeks
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Voor deze verbindingsreeks is geen accountsleutel vereist, maar u moet eerder een zoekservice hebben geconfigureerd om verbinding te maken met behulp van een beheerde identiteit en een roltoewijzing hebt gemaakt waarmee cosmos DB-accountlezer rolmachtigingen worden verleend. Zie Een indexeerfunctieverbinding met een Azure Cosmos DB-database instellen met behulp van een beheerde identiteit voor meer informatie.

Zoekvelden toevoegen aan een index

Voeg in een zoekindex velden toe om de bron-JSON-documenten of de uitvoer van uw aangepaste queryprojectie te accepteren. Zorg ervoor dat het zoekindexschema compatibel is met uw grafiek. Voor inhoud in Azure Cosmos DB moet uw zoekindexschema overeenkomen met de Azure Cosmos DB-items in uw gegevensbron.

  1. Maak of werk een index bij om zoekvelden te definiëren waarmee gegevens worden opgeslagen:

     POST https://[service name].search.windows.net/indexes?api-version=2020-06-30-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. Maak een documentsleutelveld ('sleutel': true'). Voor gepartitioneerde verzamelingen is de standaarddocumentsleutel de Azure Cosmos DB-eigenschap _rid , waarvan Azure AI Search automatisch een andere naam krijgt rid omdat veldnamen niet kunnen beginnen met een onderstrepingsteken. Azure Cosmos DB-waarden _rid bevatten ook tekens die ongeldig zijn in Azure AI Search-sleutels. Daarom zijn de _rid waarden base64 gecodeerd.

  3. Maak extra velden voor meer doorzoekbare inhoud. Zie Een index maken voor meer informatie.

Toewijzingsgegevenstypen

JSON-gegevenstype Azure AI Search-veldtypen
Bool Edm.Boolean, Edm.String
Getallen die eruitzien als gehele getallen Edm.Int32, Edm.Int64, Edm.String
Getallen die eruitzien als drijvende punten Edm.Double, Edm.String
String Edm.String
Matrices van primitieve typen, zoals ["a", "b", "c"] Collection(Edm.String)
Tekenreeksen die eruitzien als datums Edm.DateTimeOffset, Edm.String
GeoJSON-objecten zoals { "type": "Point", "coördinaten": [long, lat] } Edm.GeographyPoint
Andere JSON-objecten N.v.t.

De Azure Cosmos DB-indexeerfunctie configureren en uitvoeren

Zodra de index en de gegevensbron zijn gemaakt, kunt u de indexeerfunctie maken. De configuratie van de indexeerfunctie geeft de invoer, parameters en eigenschappen aan die het gedrag van de uitvoeringstijd regelen.

  1. Maak of werk een indexeerfunctie bij door deze een naam te geven en te verwijzen naar de gegevensbron en doelindex:

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
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. Geef veldtoewijzingen op als er verschillen zijn in veldnaam of -type, of als u meerdere versies van een bronveld in de zoekindex nodig hebt.

  3. Zie Een indexeerfunctie maken voor meer informatie over andere eigenschappen.

Een indexeerfunctie wordt automatisch uitgevoerd wanneer deze wordt gemaakt. U kunt dit voorkomen door 'uitgeschakeld' in te stellen op waar. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

De status van de indexeerfunctie controleren

Als u de status en uitvoeringsgeschiedenis van de indexeerfunctie wilt controleren, verzendt u een get-indexeerstatusaanvraag :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

Het antwoord bevat de status en het aantal verwerkte items. Het moet er ongeveer uitzien als in het volgende voorbeeld:

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

De uitvoeringsgeschiedenis bevat maximaal 50 van de laatst voltooide uitvoeringen, die in de omgekeerde chronologische volgorde worden gesorteerd, zodat de laatste uitvoering als eerste wordt uitgevoerd.

Nieuwe en gewijzigde documenten indexeren

Zodra een indexeerfunctie een zoekindex volledig heeft ingevuld, wilt u mogelijk dat de volgende indexeerfunctie alleen de nieuwe en gewijzigde documenten in uw database incrementeel indexeren.

Als u incrementele indexering wilt inschakelen, stelt u de eigenschap dataChangeDetectionPolicy in uw gegevensbrondefinitie in. Deze eigenschap vertelt de indexeerfunctie welk mechanisme voor het bijhouden van wijzigingen wordt gebruikt voor uw gegevens.

Voor Indexeerfuncties van Azure Cosmos DB is het enige ondersteunde beleid het HighWaterMarkChangeDetectionPolicy gebruik van de _ts eigenschap (timestamp) van Azure Cosmos DB.

In het volgende voorbeeld ziet u een definitie van een gegevensbron met een wijzigingsdetectiebeleid:

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

Verwijderde documenten indexeren

Wanneer grafiekgegevens worden verwijderd, wilt u mogelijk ook het bijbehorende document uit de zoekindex verwijderen. Het doel van een beleid voor het detecteren van gegevensverwijdering is om verwijderde gegevensitems efficiënt te identificeren en het volledige document uit de index te verwijderen. Het detectiebeleid voor gegevensverwijdering is niet bedoeld om gedeeltelijke documentgegevens te verwijderen. Op dit moment is het enige ondersteunde beleid het Soft Delete beleid (verwijderen is gemarkeerd met een vlag van een bepaalde soort), die als volgt is opgegeven in de definitie van de gegevensbron:

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

In het volgende voorbeeld wordt een gegevensbron gemaakt met een beleid voor voorlopig verwijderen:

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30-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"
    }
}

Zelfs als u verwijderingsdetectiebeleid inschakelt, wordt het verwijderen van complexe (Edm.ComplexType) velden uit de index niet ondersteund. Voor dit beleid moet de kolom Actief in de Gremlin-database van het type geheel getal, tekenreeks of booleaanse waarde zijn.

Grafiekgegevens toewijzen aan velden in een zoekindex

De indexeerfunctie van Azure Cosmos DB voor Apache Gremlin wijst automatisch een aantal graafgegevens toe:

  1. De indexeerfunctie wordt toegewezen _rid aan een rid veld in de index als deze bestaat en base64 coderen.

  2. De indexeerfunctie wordt toegewezen _id aan een id veld in de index als deze bestaat.

  3. Wanneer u een query uitvoert op uw Azure Cosmos DB-database met behulp van de Azure Cosmos DB voor Apache Gremlin, ziet u mogelijk dat de JSON-uitvoer voor elke eigenschap een id en een valueheeft. De indexeerfunctie wijst de eigenschappen value automatisch toe aan een veld in uw zoekindex met dezelfde naam als de eigenschap als deze bestaat. In het volgende voorbeeld wordt 450 toegewezen aan een pages veld in de zoekindex.

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

Mogelijk moet u uitvoerveldtoewijzingen gebruiken om de queryuitvoer toe te wijzen aan de velden in uw index. Waarschijnlijk wilt u uitvoerveldtoewijzingen gebruiken in plaats van veldtoewijzingen , omdat de aangepaste query waarschijnlijk complexe gegevens bevat.

Stel dat uw query deze uitvoer produceert:

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

Als u de waarde van pages de bovenstaande JSON wilt toewijzen aan een totalpages veld in uw index, kunt u de volgende uitvoerveldtoewijzing toevoegen aan de definitie van de indexeerfunctie:

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

U ziet hoe de uitvoerveldtoewijzing begint met /document en geen verwijzing naar de eigenschappensleutel in de JSON bevat. Dit komt doordat met de indexeerfunctie elk document onder het knooppunt wordt geplaatst bij het /document opnemen van de grafiekgegevens en de indexeerfunctie, kunt u ook automatisch verwijzen naar de waarde van pages door eenvoudig te verwijzen naar pages het eerste object in de matrix van pages.

Volgende stappen