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
Azure Cosmos DB-fiók, adatbázis, tároló és elemek. Használja ugyanazt a régiót az Azure AI Search és az Azure Cosmos DB esetében is az alacsonyabb késés és a sávszélesség-díjak elkerülése érdekében.
Az Azure Cosmos DB-gyűjtemény automatikus indexelési szabályzata Konzisztens értékre állítva. Ez az alapértelmezett beállítás. A lusta indexelés nem ajánlott, és hiányzó adatokat eredményezhet.
Olvasási engedélyek. A "teljes hozzáférés" kapcsolati sztring tartalmaz egy kulcsot, amely hozzáférést biztosít a tartalomhoz, de ha identitásokat használ (Microsoft Entra-azonosító), győződjön meg arról, hogy a keresési szolgáltatás felügyelt identitása Cosmos DB-fiókolvasó szerepkörrel és a Cosmos DB beépített adatolvasó szerepkörével is rendelkezik.
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.
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.
Jelentkezzen be az Azure Portalra, és hozzon létre egy fiókot, adatbázist és tárolót a Cosmos DB-ben.
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 Az Adatkezelőben bontsa ki a hotelsdb és a *hotels elemet, majd válassza az Elemek lehetőséget.
Válassza az Elem feltöltése lehetőséget, majd válassza HotelsData_toCosmosDB.JSONGitHubról letöltött fájlt.
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
: .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ó.
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.
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.
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.
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.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.
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 }
Á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"
: .Állítsa be a "hitelesítő adatokat" egy kapcsolati sztring. A következő szakasz a támogatott formátumokat ismerteti.
Á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.
Á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.
Á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ó: ApiKind IdentityAuthType Indexelő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 .
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 } ] }
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.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.
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 }
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.
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
A keresési szolgáltatás oldalán nyissa meg a Kereséskezelési>indexelőket.
Válasszon ki egy indexelőzményt a konfigurációs és végrehajtási előzmények eléréséhez.
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:
- azure.search.documents.indexes.models.searchindexerdatasourceconnection
- azure.search.documents.indexes.models.searchindexerdatasourcetype
- azure.search.documents.indexes.models.searchindex
- azure.search.documents.indexes.models.searchindexer
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: