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.

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:

   • Rövid útmutató: Adatok importálása varázsló

   • Rövid útmutató: Adatok importálása és vektorizálása varázsló

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.

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

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

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

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

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:

• Indexelőkapcsolat beállítása egy Azure Cosmos DB-adatbázishoz felügyelt identitás használatával
• Nagyméretű adathalmazok indexelése
• Indexelő hozzáférése az Azure hálózati biztonsági funkciói által védett tartalmakhoz