Indexování dat ze služby Azure Cosmos DB for NoSQL pro dotazy ve službě Azure AI Search
V tomto článku se dozvíte, jak nakonfigurovat indexer , který importuje obsah ze služby Azure Cosmos DB for NoSQL a umožňuje vyhledávání ve službě Azure AI Search.
Tento článek doplňuje vytvoření indexeru informacemi, které jsou specifické pro Službu Cosmos DB. Pomocí rozhraní REST API demonstruje třídílný pracovní postup společný pro všechny indexery: vytvoření zdroje dat, vytvoření indexeru a vytvoření indexeru. Extrakce dat nastane, když odešlete požadavek Create Indexer.
Protože terminologie může být matoucí, stojí za zmínku, že indexování služby Azure Cosmos DB a indexování služby Azure AI Search jsou různé operace. Indexování ve službě Azure AI Search vytvoří a načte vyhledávací index ve vaší vyhledávací službě.
Požadavky
Účet služby Azure Cosmos DB, databáze, kontejner a položky. Pro Azure AI Search i Azure Cosmos DB použijte stejnou oblast, abyste se vyhnuli nižší latenci a vyhnuli se poplatkům za šířku pásma.
Zásady automatického indexování v kolekci Azure Cosmos DB nastavené na konzistentní. Toto je výchozí konfigurace. Opožděné indexování se nedoporučuje a může vést k chybějícím datům.
Oprávnění ke čtení Úplný přístup připojovací řetězec obsahuje klíč, který uděluje přístup k obsahu, ale pokud používáte Azure RBAC (Microsoft Entra ID), ujistěte se, že spravovaná identita vyhledávací služby má přiřazenou roli čtenáře účtů Cosmos DB i roli integrované čtečky dat Cosmos DB.
Klient REST pro vytvoření zdroje dat, indexu a indexeru.
Definování zdroje dat
Definice zdroje dat určuje data, která se mají indexovat, přihlašovací údaje a zásady pro identifikaci změn v datech. Zdroj dat je nezávislý prostředek, který může používat více indexerů.
Vytvořte nebo aktualizujte zdroj dat a nastavte jeho definici:
POST https://[service name].search.windows.net/datasources?api-version=2023-11-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 }
Nastavte "typ" na
"cosmosdb"
(povinné). Pokud používáte starší rozhraní API služby Search verze 2017-11-11, syntaxe typu je"documentdb"
. V opačném případě pro verzi 2019-05-06 a novější použijte"cosmosdb"
.Nastavte přihlašovací údaje na připojovací řetězec. Následující část popisuje podporované formáty.
Nastavte kontejner na kolekci. Je vyžadována vlastnost name a určuje ID kolekce databáze, která se má indexovat. Vlastnost dotaz je volitelná. Slouží k zploštění libovolného dokumentu JSON do plochého schématu, které může Azure AI Search indexovat.
Nastavte dataChangeDetectionPolicy, pokud jsou data nestálá a chcete, aby indexer vyzvedal pouze nové a aktualizované položky v následných spuštěních.
Podporované přihlašovací údaje a připojovací řetězec
Indexery se můžou připojit ke kolekci pomocí následujících připojení.
Vyhněte se číslům portů v adrese URL koncového bodu. Pokud zadáte číslo portu, připojení se nezdaří.
Úplný přístup připojovací řetězec |
---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id> " }` |
Připojovací řetězec můžete získat ze stránky účtu služby Azure Cosmos DB na webu Azure Portal tak, že v levém navigačním podokně vyberete Klíče. Nezapomeňte vybrat úplný připojovací řetězec a ne jenom klíč. |
Připojovací řetězec spravované identity |
---|
{ "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])" } |
Tato připojovací řetězec nevyžaduje klíč účtu, ale musíte mít vyhledávací službu, která se může připojit pomocí spravované identity. U připojení, která cílí na rozhraní SQL API, můžete vynechat ApiKind z připojovací řetězec. Další informace o ApiKind nastavení IdentityAuthType připojení indexeru k databázi Azure Cosmos DB pomocí spravované identity. |
Použití dotazů k tvarování indexovaných dat
Ve vlastnosti "dotaz" v části kontejner můžete zadat dotaz SQL, který zploštělé vlastnosti nebo pole, vlastnosti JSON projektu a vyfiltruje data, která se mají indexovat.
Příklad dokumentu:
{
"userId": 10001,
"contact": {
"firstName": "andy",
"lastName": "hoh"
},
"company": "microsoft",
"tags": ["azure", "cosmosdb", "search"]
}
Dotaz filtru:
SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts
Zploštěný dotaz:
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
Dotaz projekce:
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
Dotaz pro zploštění pole:
SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts
Nepodporované dotazy (DISTINCT a GROUP BY)
Dotazy využívající klíčové slovo DISTINCT nebo klauzuli GROUP BY se nepodporují. Azure AI Search využívá stránkování dotazů SQL k úplnému vytvoření výčtu výsledků dotazu. Klíčové slovo DISTINCT ani klauzule GROUP BY nejsou kompatibilní s tokeny pokračování použitými ke stránkování výsledků.
Příklady nepodporovaných dotazů:
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
I když má Azure Cosmos DB alternativní řešení pro podporu stránkování dotazů SQL s klíčovým slovem DISTINCT pomocí klauzule ORDER BY, není kompatibilní s Azure AI Search. Dotaz vrátí jednu hodnotu JSON, zatímco Azure AI Search očekává objekt JSON.
-- 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
Přidání vyhledávacích polí do indexu
Do indexu vyhledávání přidejte pole pro příjem zdrojových dokumentů JSON nebo výstupu vlastní projekce dotazu. Ujistěte se, že schéma indexu vyhledávání je kompatibilní se zdrojovými daty. Pro obsah ve službě Azure Cosmos DB by schéma indexu vyhledávání mělo odpovídat položkám služby Azure Cosmos DB ve zdroji dat.
Vytvořte nebo aktualizujte index a definujte vyhledávací pole, která ukládají data:
POST https://[service name].search.windows.net/indexes?api-version=2023-11-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 } ] }
Vytvoření pole klíče dokumentu ("key": true) U dělených kolekcí je výchozím klíčem dokumentu vlastnost Azure Cosmos DB
_rid
, na kterou azure AI Search automaticky přejmenujerid
, protože názvy polí nemůžou začínat podtržítkem. Hodnoty Služby Azure Cosmos DB_rid
také obsahují znaky, které jsou v klíčích služby Azure AI Search neplatné. Z tohoto důvodu_rid
jsou hodnoty kódovány base64.Umožňuje vytvořit další pole pro prohledávatelnější obsah. Podrobnosti najdete v tématu Vytvoření indexu .
Mapování datových typů
Datové typy JSON | Typy polí Azure AI Search |
---|---|
Bool | Edm.Boolean, Edm.String |
Čísla, která vypadají jako celá čísla | Edm.Int32, Edm.Int64, Edm.String |
Čísla, která vypadají jako plovoucí desetiná čárka | Edm.Double, Edm.String |
String | Edm.String |
Pole primitivních typů, jako je ["a", "b", "c"] | Collection(Edm.String) |
Řetězce, které vypadají jako kalendářní data | Edm.DateTimeOffset, Edm.String |
Objekty GeoJSON, například { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
Další objekty JSON | – |
Konfigurace a spuštění indexeru Azure Cosmos DB for NoSQL
Po vytvoření indexu a zdroje dat můžete indexer vytvořit. Konfigurace indexeru určuje vstupy, parametry a vlastnosti, které řídí chování doby běhu.
Vytvořte nebo aktualizujte indexer tak, že ho pojmenujte a odkazujete na zdroj dat a cílový index:
POST https://[service name].search.windows.net/indexers?api-version=2023-11-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 }
Určete mapování polí, pokud existují rozdíly v názvu nebo typu pole nebo pokud potřebujete v indexu vyhledávání více verzí zdrojového pole.
Další informace o dalších vlastnostech najdete v tématu Vytvoření indexeru .
Indexer se spustí automaticky při jeho vytvoření. Můžete tomu zabránit nastavením "zakázáno" na hodnotu true. Pokud chcete řídit provádění indexeru, spusťte indexer na vyžádání nebo ho umístěte do plánu.
Kontrola stavu indexeru
Pokud chcete monitorovat stav indexeru a historii spuštění, odešlete žádost o získání stavu indexeru:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
Content-Type: application/json
api-key: [admin key]
Odpověď zahrnuje stav a počet zpracovaných položek. Měl by vypadat podobně jako v následujícím příkladu:
{
"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
]
}
Historie provádění obsahuje až 50 naposledy dokončených spuštění, které jsou seřazeny v obráceném chronologickém pořadí tak, aby poslední spuštění bylo první.
Indexování nových a změněných dokumentů
Jakmile indexer plně naplní vyhledávací index, můžete chtít, aby následující indexer běžel postupně indexovat pouze nové a změněné dokumenty v databázi.
Chcete-li povolit přírůstkové indexování, nastavte vlastnost dataChangeDetectionPolicy v definici zdroje dat. Tato vlastnost říká indexeru, který mechanismus sledování změn se používá u vašich dat.
U indexerů Azure Cosmos DB se jediná podporovaná zásada používá HighWaterMarkChangeDetectionPolicy
_ts
vlastnost (timestamp) poskytovanou službou Azure Cosmos DB.
Následující příklad ukazuje definici zdroje dat se zásadami detekce změn:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
" highWaterMarkColumnName": "_ts"
},
Poznámka:
Když přiřadíte null
hodnotu k poli ve službě Azure Cosmos DB, indexer služby AI Search nemůže rozlišovat mezi null
a chybějící hodnotou pole. Proto pokud je pole v indexu prázdné, nenahradí null
se hodnotou, a to ani v případě, že byla tato změna provedena v databázi.
Přírůstkové indexování a vlastní dotazy
Pokud k načtení dokumentů používáte vlastní dotaz, ujistěte se, že dotaz objednává výsledky podle _ts
sloupce. To umožňuje pravidelné kontrolní body, které Azure AI Search používá k zajištění přírůstkového průběhu v případě selhání.
V některých případech, i když dotaz obsahuje ORDER BY [collection alias]._ts
klauzuli, azure AI Search nemusí odvodit, že dotaz je seřazený podle výrazu _ts
. Azure AI Search můžete říct, že výsledky jsou seřazené nastavením assumeOrderByHighWaterMarkColumn
vlastnosti konfigurace.
Chcete-li zadat tento tip, vytvořte nebo aktualizujte definici indexeru následujícím způsobem:
{
... other indexer definition properties
"parameters" : {
"configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}
Indexování odstraněných dokumentů
Když se řádky z kolekce odstraní, obvykle je chcete odstranit také z indexu vyhledávání. Účelem zásad detekce odstranění dat je efektivní identifikace odstraněných datových položek. V současné době je jedinou podporovanou zásadou Soft Delete
zásada (odstranění je označeno příznakem určitého druhu), který je zadaný v definici zdroje dat následujícím způsobem:
"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"
}
Pokud používáte vlastní dotaz, ujistěte se, že je vlastnost odkazovaná softDeleteColumnName
dotazem promítnuta.
Musí softDeleteColumnName
to být pole nejvyšší úrovně v indexu. Použití vnořených polí v rámci složitých datových typů, protože softDeleteColumnName
se nepodporuje.
Následující příklad vytvoří zdroj dat se zásadami obnovitelného odstranění:
POST https://[service name].search.windows.net/datasources?api-version=2023-11-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"
}
}
Použití .NET
Pro data přístupná přes protokol rozhraní SQL API můžete pomocí sady .NET SDK automatizovat pomocí indexerů. Doporučujeme projít si předchozí části rozhraní REST API a seznámit se s koncepty, pracovními postupy a požadavky. Pak se můžete podívat na následující referenční dokumentaci k rozhraní .NET API a implementovat indexer JSON ve spravovaném kódu:
- azure.search.documents.indexes.models.searchindexerdatasourceconnection
- azure.search.documents.indexes.models.searchindexerdatasourcetype
- azure.search.documents.indexes.models.searchindex
- azure.search.documents.indexes.models.searchindexer
Další kroky
Teď můžete řídit způsob spuštění indexeru, monitorování stavu nebo plánování provádění indexeru. Následující články platí pro indexery, které načítá obsah ze služby Azure Cosmos DB:
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro