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

Cikk
09/01/2024

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. 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

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 Azure RBAC-t (Microsoft Entra-azonosítót) használ, győződjön meg arról, hogy a keresési szolgáltatás felügyelt identitása Cosmos DB-fiókolvasó szerepkörhöz és a Cosmos DB beépített adatolvasói szerepkörhöz is hozzá van rendelve.
EGY REST-ügyfél , amely létrehozza az adatforrást, az indexet és az indexelőt.

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 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>`" }`
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];)/(IdentityAuthType=[identity-auth-type])" }`
Ez a kapcsolati sztring nem igényel fiókkulcsot, de olyan keresési szolgáltatással kell rendelkeznie, amely képes felügyelt identitással csatlakozni. Az SQL API-t célzó kapcsolatok esetében kihagyhatja `ApiKind` a kapcsolati sztring. További információ: `ApiKindIdentityAuthType` 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 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-07-01
  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"
},

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ást kifejezetten az adatbázisban hajtották végre.

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:

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