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


Adatok indexelése az Azure Cosmos DB for NoSQL-ből lekérdezésekhez az Azure AI Searchben

Ebből a cikkből megtudhatja, hogyan konfigurálhat olyan indexelőt, amely tartalmat importál az Azure Cosmos DB for NoSQL-ből, é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. Az Azure Portal és a REST API-k használatával 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

A cikkben szereplő példák végigdolgozásához az Azure Portalra vagy egy REST-ügyfélre van szükség. Ha az Azure Portalt használja, győződjön meg arról, hogy az összes nyilvános hálózathoz való hozzáférés engedélyezve van. A Cosmos DB-indexelők létrehozásának egyéb megközelítései közé tartoznak az Azure SDK-k.

Kipróbálás mintaadatokkal

Ezeket az utasításokat követve hozzon létre egy tárolót és adatbázist a Cosmos DB-ben tesztelési célokra.

  1. Töltse le HotelsData_toCosmosDB.JSON a GitHubról, hogy létrehozhasson egy tárolót a Cosmos DB-ben, amely a minta szállodák adatkészletének egy részét tartalmazza.

  2. Jelentkezzen be az Azure Portalra, és hozzon létre egy fiókot, adatbázist és tárolót a Cosmos DB-ben.

  3. A Cosmos DB-ben válassza az Adatkezelőt az új tárolóhoz, és adja meg a következő értékeket.

    Tulajdonság Érték
    Adatbázis Új létrehozása
    Adatbázis-azonosító hotelsdb
    Átviteli sebesség megosztása tárolók között Ne válassza a
    Tároló azonosítója szállodák
    Partíciókulcs /HotelId
    Tároló átviteli sebessége (automatikus skálázás) Automatikus méretezés
    Tároló maximális RU/s 1000
  4. Az Adatkezelőben bontsa ki a hotelsdb és a *hotels elemet, majd válassza az Elemek lehetőséget.

  5. Válassza az Elem feltöltése lehetőséget, majd válassza HotelsData_toCosmosDB.JSONGitHubról letöltött fájlt.

  6. Kattintson a jobb gombbal az Elemek elemre, és válassza az Új SQL-lekérdezés lehetőséget. Az alapértelmezett lekérdezés a következő SELECT * FROM c: .

  7. Válassza a Lekérdezés végrehajtása lehetőséget a lekérdezés futtatásához és az eredmények megtekintéséhez. 50 szállodai dokumentumnak kell lennie.

Most, hogy rendelkezik egy tárolóval, az Azure Portal, a REST-ügyfél vagy az Azure SDK használatával indexelheti az adatokat.

A Leírás mező a legigértelmesebb tartalmat biztosítja. Ezt a mezőt a teljes szöveges kereséshez és az opcionális vektoros lekérdezésekhez kell megcélznia.

Az Azure Portal használata

Az Adatok importálása varázslóval vagy az Adatok importálása és vektorizálása varázslóval automatizálhatja az indexelést egy SQL-adatbázistáblából vagy nézetből. Az adatforrás konfigurációja mindkét varázsló esetében hasonló.

  1. Indítsa el a varázslót.

  2. Az adatokhoz való csatlakozáskor válassza ki vagy ellenőrizze, hogy az adatforrás típusa Azure Cosmos DB vagy NoSQL-fiók-e.

    Az adatforrás neve az Azure AI Search adatforrás-kapcsolati objektumára hivatkozik. Ha a vektorvarázslót használja, az adatforrás neve automatikusan létrejön a varázsló munkafolyamatának végén megadott egyéni előtaggal.

  3. Adja meg az adatbázis nevét és gyűjteményét. A lekérdezés nem kötelező. Ez akkor hasznos, ha hierarchikus adatokkal rendelkezik, és egy adott szeletet szeretne importálni.

  4. Adjon meg egy hitelesítési módszert, egy felügyelt identitást vagy egy beépített API-kulcsot. Ha nem ad meg felügyelt identitáskapcsolatot, az Azure Portal a kulcsot használja.

    Ha úgy konfigurálja az Azure AI Search szolgáltatást, hogy felügyelt identitást használjon, és létrehoz egy szerepkör-hozzárendelést a Cosmos DB-ben, amely a Cosmos DB-fiókolvasónak és a Cosmos DB beépített adatolvasójának engedélyt ad az identitáshoz, az indexelő a Microsoft Entra-azonosító és -szerepkörök használatával csatlakozhat a Cosmos DB-hez.

  5. Az Adatok importálása és vektorizálása varázslóban megadhatja a módosítás- és törléskövetési beállításokat.

    A változásészlelés alapértelmezés szerint egy _ts mezőn (időbélyegen) keresztül támogatott. Ha a Mintaadatok kipróbálása című cikkben ismertetett módszerrel tölt fel tartalmat, a gyűjtemény egy _ts mezővel jön létre.

    A törlésészleléshez rendelkeznie kell egy előre létező legfelső szintű mezővel a gyűjteményben, amely helyreállítható törlési jelzőként használható. Logikai mezőnek kell lennie (nevezheti el törölve). Adja meg true a helyreállíthatóan törölt értéket. A keresési indexben adjon hozzá egy isDeleted nevű megfelelő keresőmezőt lekérdezhető és szűrhető értékre.

  6. Folytassa a varázsló végrehajtásához szükséges további lépésekkel:

A REST API-k használata

Ez a szakasz az adatforrást, indexet és indexelőt létrehozó REST API-hívásokat mutatja be.

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. Az adatforrás egy független erőforrás, amelyet több indexelő is használhat.

  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-07-01
    Content-Type: application/json
    api-key: [Search service admin key]
    {
        "name": "[my-cosmosdb-ds]",
        "type": "cosmosdb",
        "credentials": {
          "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
        },
        "container": {
          "name": "[my-cosmos-db-collection]",
          "query": null
        },
        "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ő). Ha a Search API régebbi, 2017-11-11-es verzióját használja, a "típus" szintaxisa."documentdb" Ellenkező esetben a 2019-05-06-os és újabb verziókhoz használja a következőt "cosmosdb": .

  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 az indexelendő adatbázis-gyűjtemény azonosítóját. A "lekérdezés" tulajdonság megadása nem kötelező. Ezzel tetszőleges JSON-dokumentumokat simíthat egy sima sémába, amelyet az Azure AI Search indexelhet.

  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.

  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.

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

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>" }`
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.
(Modern megközelítés) Felügyelt identitás kapcsolati sztring NoSQL-fiókokhoz
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=AccessToken)" }
Ez a kapcsolati sztring, amelyet csak az Azure Cosmos DB for NoSQL-fiókok támogatnak, biztosítja, hogy a keresési szolgáltatás soha ne használjon fiókkulcsokat (még a háttérben is), amikor a Cosmos DB-ből próbál hozzáférni az adatokhoz. Ez ajánlott, mivel akkor is működik, ha a NoSQL-fiók fiókkulcsai le vannak tiltva. További információ: Indexelői kapcsolat beállítása felügyelt identitással rendelkező Azure Cosmos DB-adatbázishoz
(Örökölt megközelítés) 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];)/(IdentityAuthType=AccountKey)" }
Ez a kapcsolati sztring nem követeli meg közvetlenül a fiókkulcs megadását, de a keresési szolgáltatás a felügyelt identitást fogja használni a fiókkulcsok háttérbeli lekéréséhez. Bár ez minden Cosmos DB-fióktípus esetében támogatott, a NoSQL-fióktípushoz nem ajánlott. Egy ilyen kapcsolati sztring nem fog működni, ha a Cosmos DB-fiók fiókkulcsai le vannak tiltva. Ha a IdentityAuthType tulajdonság nincs megadva, a keresési szolgáltatás továbbra is alapértelmezés szerint beolvassa a fiókkulcsot a háttérben. Az SQL API-t célzó kapcsolatok esetében kihagyhatja ApiKind a kapcsolati sztring. További információ: ApiKindIdentityAuthTypeIndexelői kapcsolat beállítása felügyelt identitással rendelkező Azure Cosmos DB-adatbázishoz

Lekérdezések használata indexelt adatok alakításához

A "container" alatt található "lekérdezés" tulajdonságban megadhat egy SQL-lekérdezést a beágyazott tulajdonságok vagy tömbök, a projekt JSON-tulajdonságainak összesimításához és az indexelendő adatok szűréséhez.

Példadokumentum:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Szűrő lekérdezés:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Egybesimító lekérdezés:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Előrejelzési lekérdezés:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Tömblapító lekérdezés:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Nem támogatott lekérdezések (DISTINCT és GROUP BY)

A DISTINCT kulcsszót vagy a GROUP BY záradékot használó lekérdezések nem támogatottak. Az Azure AI Search az SQL-lekérdezések lapozására támaszkodik a lekérdezés eredményeinek teljes számbavételéhez. Sem a DISTINCT kulcsszó, sem a GROUP BY záradék nem kompatibilis az eredmények lapozásához használt folytatási jogkivonatokkal .

Példák nem támogatott lekérdezésekre:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Bár az Azure Cosmos DB megkerülő megoldással támogatja az SQL-lekérdezések lapozását a DISTINCT kulcsszóval az ORDER BY záradék használatával, nem kompatibilis az Azure AI Search szolgáltatással. A lekérdezés egyetlen JSON-értéket ad vissza, míg az Azure AI Search egy JSON-objektumot vár.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

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 forrásadatokkal. 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-07-01
    Content-Type: application/json
    api-key: [Search service admin key]
    {
        "name": "mysearchindex",
        "fields": [{
            "name": "rid",
            "type": "Edm.String",
            "key": true,
            "searchable": false
        }, 
        {
            "name": "description",
            "type": "Edm.String",
            "filterable": false,
            "searchable": true,
            "sortable": false,
            "facetable": false,
            "suggestions": true
        }
      ]
    }
    
  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ípusok 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 for NoSQL 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-07-01
    Content-Type: application/json
    api-key: [search service admin key]
    {
        "name" : "[my-cosmosdb-indexer]",
        "dataSourceName" : "[my-cosmosdb-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 monitorozásához ellenőrizze az indexelőzményeket az Azure Portalon, vagy küldjön egy Get Indexer Status REST APIrequest parancsot

  1. A keresési szolgáltatás oldalán nyissa meg a Kereséskezelési>indexelőket.

  2. Válasszon ki egy indexelőzményt a konfigurációs és végrehajtási előzmények eléréséhez.

  3. Válasszon ki egy adott indexelőfeladatot a részletek, figyelmeztetések és hibák megtekintéséhez.

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

Feljegyzés

Amikor az Azure Cosmos DB-ben egy mezőhöz rendel null értéket, az AI Search indexelője nem tud különbséget tenni a hiányzó mezőértékek között null . Ezért ha az index egy mezője üres, akkor az nem lesz helyettesítve null értékkel, még akkor sem, ha a módosítás az adatbázisban történt.

Növekményes indexelés és egyéni lekérdezések

Ha egyéni lekérdezést használ a dokumentumok lekéréséhez, győződjön meg arról, hogy a lekérdezés az oszlop szerint rendeli meg az _ts eredményeket. Ez lehetővé teszi az Azure AI Search által a hibák jelenlétének növekményes előrehaladását lehetővé tevő rendszeres ellenőrzőpontozást.

Bizonyos esetekben még ha a lekérdezés tartalmaz is egy záradékot ORDER BY [collection alias]._ts , előfordulhat, hogy az Azure AI Search nem arra következtet, hogy a lekérdezést a _ts. A konfigurációs tulajdonság beállításával megadhatja az Azure AI Searchnek, hogy az eredmények sorrendbe assumeOrderByHighWaterMarkColumn vannak rendezve.

A tipp megadásához hozza létre vagy frissítse az indexelő definícióját az alábbiak szerint:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
} 

Törölt dokumentumok indexelése

Amikor sorokat töröl a gyűjteményből, általában ezeket a sorokat is törölni szeretné a keresési indexből. Az adattörlési észlelési szabályzat célja a törölt adatelemek hatékony azonosítása. 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"
}

Ha egyéni lekérdezést használ, győződjön meg arról, hogy az általa softDeleteColumnName hivatkozott tulajdonságot a lekérdezés kivetíti.

Az softDeleteColumnName index legfelső szintű mezőjének kell lennie. Beágyazott mezők használata összetett adattípusokon belül, mivel az softDeleteColumnName nem támogatott.

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-07-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "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"
    }
}

A .NET használata

Az SQL API protokollon keresztül elért adatok esetében a .NET SDK-val automatizálhat indexelőkkel. Javasoljuk, hogy tekintse át az előző REST API-szakaszokat a fogalmak, a munkafolyamat és a követelmények megismeréséhez. Ezután tekintse meg a következő .NET API referenciadokumentációt egy JSON-indexelő felügyelt kódban való implementálásához:

Következő lépések

Mostantól szabályozhatja az indexelő futtatásának, a monitorozás állapotának vagy az indexelő végrehajtásának ütemezését. Az alábbi cikkek azOkra az indexelőkre vonatkoznak, amelyek tartalmat kérnek le az Azure Cosmos DB-ből: