Megosztás a következőn keresztül:

Adatok indexelése az Apache Gremlinhez készült Azure Cosmos DB-ből az Azure AI Search lekérdezéseihez

  • Cikk

Fontos

Az Apache Gremlin-indexelőhöz készült Azure Cosmos DB jelenleg nyilvános előzetes verzióban érhető el a kiegészítő használati feltételek alatt. Jelenleg nincs SDK-támogatás.

Ebből a cikkből megtudhatja, hogyan konfigurálhat egy olyan indexelőt, amely tartalmat importál az Azure Cosmos DB-ből az Apache Gremlinhez, és hogyan teszi kereshetővé az Azure AI Searchben.

Ez a cikk kiegészíti a Cosmos DB-hez kapcsolódó információkat tartalmazó indexelő létrehozását. A REST API-k segítségével egy háromrészes munkafolyamatot mutat be, amely az összes indexelőre jellemző: adatforrás létrehozása, index létrehozása, indexelő létrehozása. Az adatkinyerés az Indexelő létrehozása kérés elküldésekor történik.

Mivel a terminológia zavaró lehet, érdemes megjegyezni, hogy az Azure Cosmos DB indexelése és az Azure AI Search indexelése különböző műveletek. Az Azure AI Searchben történő indexelés létrehoz és betölt egy keresési indexet a keresési szolgáltatásban.

Előfeltételek

Az adatforrás meghatározása

Az adatforrás definíciója meghatározza az adatok indexeléséhez, hitelesítő adataihoz és szabályzataihoz az adatok változásainak azonosításához. Egy adatforrás független erőforrásként van definiálva, így több indexelő is használhatja.

Ehhez a híváshoz adjon meg egy előzetes REST API-verziót egy olyan adatforrás létrehozásához, amely az Apache Gremlinhez készült Azure Cosmos DB-en keresztül csatlakozik. A 2021-04-01-preview vagy újabb verziót használhatja. Javasoljuk, hogy a legújabb előzetes verziójú API-t használja.

  1. Adatforrás létrehozása vagy frissítése a definíció beállításához:

     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. Állítsa be a "cosmosdb" "type" (típus) értéket (kötelező).

  3. Állítsa be a "hitelesítő adatokat" egy kapcsolati sztring. A következő szakasz a támogatott formátumokat ismerteti.

  4. Állítsa a "tárolót" a gyűjteményre. A "name" tulajdonság megadása kötelező, és megadja a gráf azonosítóját.

    A "lekérdezés" tulajdonság megadása nem kötelező. Alapértelmezés szerint az Apache Gremlinhez készült Azure Cosmos DB Azure AI Search-indexelője a gráf minden csúcsát az index dokumentumává teszi. Az élek figyelmen kívül lesznek hagyva. A lekérdezés alapértelmezett értéke .g.V() Másik lehetőségként beállíthatja, hogy a lekérdezés csak a széleket indexelje. Az élek indexeléséhez állítsa a lekérdezést a következőre g.E(): .

  5. Állítsa be a "dataChangeDetectionPolicy" értéket, ha az adatok változékonyak, és azt szeretné, hogy az indexelő csak az új és frissített elemeket vegye fel a későbbi futtatások során. A növekményes folyamat alapértelmezés szerint engedélyezve lesz a magas vízjel oszlop használatával _ts .

  6. Állítsa be a "dataDeletionDetectionPolicy" értéket, ha el szeretné távolítani a keresési dokumentumokat a keresési indexből a forráselem törlésekor.

Támogatott hitelesítő adatok és kapcsolati sztring

Az indexelők az alábbi kapcsolatokkal csatlakozhatnak egy gyűjteményhez. Az Apache Gremlinhez készült Azure Cosmos DB-t célzó kapcsolatok esetében mindenképpen vegye fel az "ApiKind" szót a kapcsolati sztring.

Kerülje a portszámokat a végpont URL-címében. Ha a portszámot is tartalmazza, a kapcsolat sikertelen lesz.

Teljes hozzáférésű kapcsolati sztring
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
A kapcsolati sztring az Azure Portal Azure Cosmos DB-fióklapjáról a bal oldali navigációs panel Kulcsok elemével szerezheti be. Ügyeljen arra, hogy a teljes kapcsolati sztring ne csak egy kulcsot válasszon.
Felügyelt identitás kapcsolati sztring
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Ez a kapcsolati sztring nem igényel fiókkulcsot, de korábban konfigurálnia kell egy keresési szolgáltatást a felügyelt identitással való csatlakozáshoz, és létre kell hoznia egy szerepkör-hozzárendelést, amely a Cosmos DB-fiókolvasó szerepkör-engedélyeit biztosítja. További információ: Indexelőkapcsolat beállítása felügyelt identitással rendelkező Azure Cosmos DB-adatbázishoz.

Keresési mezők hozzáadása indexhez

A keresési indexben adjon hozzá mezőket a forrás JSON-dokumentumok vagy az egyéni lekérdezésvetítés kimenetének elfogadásához. Győződjön meg arról, hogy a keresési index sémája kompatibilis a gráfjával. Az Azure Cosmos DB-ben lévő tartalom esetében a keresési index sémájának meg kell felelnie az adatforrás Azure Cosmos DB-elemeinek .

  1. Hozzon létre vagy frissítsen egy indexet az adatokat tároló keresési mezők definiálásához:

     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. Hozzon létre egy dokumentumkulcsmezőt ("key": true). Particionált gyűjtemények esetén az alapértelmezett dokumentumkulcs az Azure Cosmos DB _rid tulajdonság, amelyre az Azure AI Search automatikusan átnevez, rid mert a mezőnevek nem kezdődhetnek aláhúzásjellel. Az Azure Cosmos DB-értékek _rid olyan karaktereket is tartalmaznak, amelyek érvénytelenek az Azure AI Search-kulcsokban. Ezért az _rid értékek Base64 kódolásúak.

  3. További mezők létrehozása több kereshető tartalomhoz. Részletekért lásd : Index létrehozása.

Adattípusok leképezése

JSON-adattípus Az Azure AI Search mezőtípusai
Bool Edm.Boolean, Edm.String
Egész számoknak tűnő számok Edm.Int32, Edm.Int64, Edm.String
Lebegőpontosnak tűnő számok Edm.Double, Edm.String
Sztring Edm.String
Primitív típusú tömbök, például ["a", "b", "c"] Collection(Edm.String)
Dátumnak tűnő sztringek Edm.DateTimeOffset, Edm.String
GeoJSON-objektumok, például { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Egyéb JSON-objektumok n/a

Az Azure Cosmos DB indexelő konfigurálása és futtatása

Az index és az adatforrás létrehozása után készen áll az indexelő létrehozására. Az indexelő konfigurációja meghatározza a futási idő viselkedését vezérlő bemeneteket, paramétereket és tulajdonságokat.

  1. Hozzon létre vagy frissítsen egy indexelőt úgy, hogy megad neki egy nevet, és hivatkozik az adatforrásra és a célindexre:

    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. Mezőleképezéseket adhat meg, ha a mezőnév vagy a típus eltérést mutat, vagy ha egy forrásmező több verziójára van szüksége a keresési indexben.

  3. További információt az egyéb tulajdonságokról az Indexelő létrehozása című témakörben talál.

Az indexelő automatikusan fut a létrehozásakor. Ezt úgy akadályozhatja meg, hogy a "letiltva" értéket igaz értékre állítja. Az indexelő végrehajtásának szabályozásához futtasson egy indexelőt igény szerint , vagy ütemezze.

Az indexelő állapotának ellenőrzése

Az indexelőzmények állapotának és végrehajtási előzményeinek figyeléséhez küldjön egy indexelőzmény-lekéréses kérést:

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

A válasz tartalmazza az állapotot és a feldolgozott elemek számát. A következő példához hasonlóan kell kinéznie:

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

A végrehajtási előzmények legfeljebb 50 legutóbbi végrehajtást tartalmaznak, amelyek fordított időrendi sorrendben vannak rendezve, hogy a legújabb végrehajtás legyen az első.

Új és módosított dokumentumok indexelése

Miután egy indexelő kitöltött egy keresési indexet, érdemes lehet, hogy a későbbi indexelők növekményesen indexeljenek csak az adatbázis új és módosított dokumentumait.

A növekményes indexelés engedélyezéséhez állítsa be a "dataChangeDetectionPolicy" tulajdonságot az adatforrás definíciójában. Ez a tulajdonság tájékoztatja az indexelőt, hogy melyik változáskövetési mechanizmust használja az adatokon.

Az Azure Cosmos DB-indexelők esetében az egyetlen támogatott szabályzat az HighWaterMarkChangeDetectionPolicy _ts Azure Cosmos DB által biztosított (időbélyeg) tulajdonság használata.

Az alábbi példa egy változásészlelési szabályzattal rendelkező adatforrásdefiníciót mutat be:

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

Törölt dokumentumok indexelése

A gráfadatok törlésekor érdemes lehet törölni a megfelelő dokumentumot a keresési indexből is. Az adattörlési észlelési szabályzat célja a törölt adatelemek hatékony azonosítása és a teljes dokumentum törlése az indexből. Az adattörlési észlelési szabályzat nem a részleges dokumentuminformációk törlését jelenti. Jelenleg az egyetlen támogatott szabályzat a Soft Delete szabályzat (a törlés valamilyen jelölővel van megjelölve), amely az adatforrás definíciójában az alábbiak szerint van megadva:

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

Az alábbi példa egy helyreállítható törlési szabályzattal rendelkező adatforrást hoz létre:

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

Még ha engedélyezi is a törlésészlelési szabályzatot, az összetett (Edm.ComplexType) mezők törlése az indexből nem támogatott. Ez a szabályzat megköveteli, hogy a Gremlin-adatbázis "aktív" oszlopa egész szám, sztring vagy logikai típusú legyen.

Gráfadatok leképezése keresési index mezőihez

Az Apache Gremlin-hez készült Azure Cosmos DB indexelő automatikusan megfeleltet néhány gráfadatot:

  1. Az indexelő leképezi _rid az index egy rid mezőjét, ha létezik, és a Base64 kódolja azt.

  2. Az indexelő le lesz képezve _id az index egy id mezőjére, ha létezik.

  3. Amikor az Azure Cosmos DB-adatbázist az Apache Gremlinhez készült Azure Cosmos DB használatával kérdezi le, láthatja, hogy az egyes tulajdonságok JSON-kimenete rendelkezik egy és egy id value. Az indexelő automatikusan megfelelteti a tulajdonságokat value a keresési index egy olyan mezőjébe, amelynek neve megegyezik a tulajdonság nevével, ha létezik. Az alábbi példában a 450 a keresési index egy pages mezőjére lesz leképezve.

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

Előfordulhat, hogy a kimeneti mezőleképezések használatával le kell képeznie a lekérdezés kimenetét az index mezőihez. Valószínűleg a kimeneti mezőleképezéseket szeretné használni mezőleképezések helyett, mivel az egyéni lekérdezés valószínűleg összetett adatokkal fog rendelkezni.

Tegyük fel például, hogy a lekérdezés a következő kimenetet hozza létre:

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

Ha le szeretné képezni a fenti JSON értékét pages az index egy totalpages mezőjére, a következő kimeneti mezőleképezést veheti fel az indexelő definíciójához:

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

Figyelje meg, hogyan kezdődik /document a kimeneti mezőleképezés, és nem tartalmaz hivatkozást a JSON tulajdonságkulcsára. Ennek az az oka, hogy az indexelő minden dokumentumot a /document csomópont alá helyez a gráfadatok betöltésekor, és az indexelő automatikusan lehetővé teszi, hogy egyszerű hivatkozással pages hivatkozzon az értékre pages ahelyett, hogy a tömb első objektumára pageskellene hivatkoznia.

Következő lépések