Indexování dat ze služby Azure Cosmos DB for NoSQL pro dotazy ve službě Azure AI Vyhledávač

Indexer Azure Cosmos DB pro NoSQL importuje obsah z Azure Cosmos DB pro NoSQL a zpřístupňuje ho k vyhledávání ve službě Azure AI Vyhledávač.

Tento článek doplňuje Vytvořte indexer informacemi, které jsou specifické pro Cosmos DB. Pomocí webu Azure Portal a rozhraní REST API demonstruje třídílný pracovní postup společný pro všechny indexery: vytvoření zdroje dat, vytvoření indexu, 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 Vyhledávač jsou různé operace. Indexování ve službě Azure AI Vyhledávač vytvoří a načte vyhledávací index ve vaší vyhledávací službě.

Požadavky

• Účet Azure Cosmos DB, databáze, kontejner a položky. Pro Azure AI Vyhledávač 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í ** Připojovací řetězec "úplného přístupu" obsahuje klíč, který uděluje přístup k obsahu, ale pokud používáte identity (Microsoft Entra ID), ujistěte se, že spravovaná identita vyhledávací služby je přiřazená jako role Čtenář účtu Cosmos DB a vestavěná role Čtenář dat Cosmos DB.

Abyste mohli projít příklady v tomto článku, potřebujete Azure Portal nebo klienta REST. Pokud používáte Azure Portal, ujistěte se, že je povolený přístup ke všem veřejným sítím. Další přístupy k vytvoření indexeru Cosmos DB zahrnují sady Azure SDK.

Vyzkoušení s ukázkovými daty

Tyto pokyny použijte k vytvoření kontejneru a databáze ve službě Cosmos DB pro účely testování.

1. Stáhněte si HotelsData_toCosmosDB.json z GitHubu a vytvořte kontejner ve službě Cosmos DB, který obsahuje podmnožinu ukázkové sady dat hotelů.

2. Přihlaste se k webu Azure Portal a vytvořte účet, databázi a kontejner ve službě Cosmos DB.

3. Ve službě Cosmos DB vyberte Data Explorer a pro nový kontejner zadejte následující hodnoty.

   Vlastnictví	Hodnota
   Databáze	Vytvořit nový
   ID databáze	databáze hotelů
   Sdílení propustnosti napříč kontejnery	Nevybírejte
   ID kontejneru	hotely
   Klíč oddílu	/HotelId
   Propustnost kontejneru (automatické škálování)	Automatické škálování
   Maximální počet RU/s kontejneru	1 000

4. V Průzkumníku dat rozbalte hotelsdb a hotels a pak vyberte Položky.

5. Vyberte Nahrát položku a pak vyberte HotelsData_toCosmosDB.json soubor, který jste stáhli z GitHubu.

6. Klikněte pravým tlačítkem na Položky a vyberte Nový dotaz SQL. Výchozí dotaz je SELECT * FROM c.

7. Výběrem možnosti Spustit dotaz spusťte dotaz a zobrazte výsledky. Měli byste mít 50 hotelových dokumentů.

Teď, když máte kontejner, můžete k indexování dat použít Azure Portal, klienta REST nebo sadu Azure SDK.

Pole Popis poskytuje nejrozsáhodnější obsah. Toto pole byste měli cílit na fulltextové vyhledávání a volitelné vektorové dotazy.

Použití portálu Azure Portal

Pomocí Průvodce importem dat můžete automatizovat indexování z tabulky nebo zobrazení databáze SQL.

1. Spusťte průvodce.

2. V části Připojit k datům vyberte nebo ověřte, že typ zdroje dat je buď Azure Cosmos DB , nebo účet NoSQL.

   Název zdroje dat odkazuje na objekt připojení zdroje dat ve službě Azure AI Vyhledávač. Název zdroje dat se automaticky vygeneruje pomocí vlastní předpony, kterou zadáte na konci pracovního postupu průvodce.

3. Zadejte název a kolekci databáze. Dotaz je nepovinný. Je užitečné, pokud máte hierarchická data a chcete importovat konkrétní řez.

4. Zadejte metodu ověřování, a to buď spravovanou identitu, nebo integrovaný klíč rozhraní API. Pokud nezadáte připojení spravované identity, azure Portal tento klíč použije.

   Pokud nakonfigurujete Azure AI Vyhledávač, aby používala spravovanou identitu, a vytvoříte přiřazení rolí ve službě Cosmos DB, které udělí oprávnění Čtenář účtů Cosmos DB a Integrovaný čtečka dat Cosmos DB k identitě, může se váš indexer připojit ke službě Cosmos DB pomocí Microsoft Entra ID a role.

5. Můžete zadat možnosti sledování změn a odstranění.

   Detekce změn se ve výchozím nastavení podporuje prostřednictvím _ts pole (časové razítko). Pokud nahrajete obsah podle postupu popsaného v sekci Vyzkoušet s ukázkovými daty, vytvoří se kolekce s polem _ts.

   Detekce odstranění vyžaduje, abyste měli v kolekci již existující pole nejvyšší úrovně, které lze použít jako indikátor měkkého odstranění. Mělo by to být logické pole (můžete ho pojmenovat IsDeleted). Zadejte true jako hodnotu soft-deleted. Do indexu vyhledávání přidejte odpovídající vyhledávací pole s názvem IsDeleted nastaveno na načtení a filtrování.

6. Pokračujte zbývajícími kroky a dokončete průvodce:

   • Průvodce importem dat

Použití rozhraní REST API

Tato část ukazuje volání rozhraní REST API, která vytvářejí zdroj dat, index a indexer.

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

1. Vytvořte nebo aktualizujte zdroj dat a nastavte jeho definici:

   POST https://[service name].search.windows.net/datasources?api-version=2026-04-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. 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".

3. Nastavte přihlašovací údaje do připojovacího řetězce. Následující část popisuje podporované formáty.

4. Přiřaďte "kontejner" ke 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 Vyhledávač indexovat.

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

6. Pokud chcete odebrat vyhledávací dokumenty z indexu vyhledávání při odstranění zdrojové položky, nastavte "dataDeletionDetectionPolicy" .

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í selže.

Použití dotazů k tvarování indexovaných dat

Ve vlastnosti "dotaz" v rámci kontejneru můžete zadat dotaz SQL, který zplošťuje vnořené vlastnosti nebo pole, provádí projekci vlastností JSON a vyfiltruje data, která se mají indexovat.

Příklad dokumentu:

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

Filtrační dotaz:

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

Projekční dotaz

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 na 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 Vyhledávač 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 Vyhledávač. Dotaz vrátí jednu hodnotu JSON, zatímco Azure AI Vyhledávač 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.

1. Vytvořte nebo aktualizujte index a definujte vyhledávací pole, která ukládají data:

   POST https://[service name].search.windows.net/indexes?api-version=2026-04-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. 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řejmenuje rid , 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 Vyhledávač neplatné. Z tohoto důvodu _rid jsou hodnoty kódovány base64.

3. Umožňuje vytvořit další pole pro prohledávatelnější obsah. Podrobnosti najdete v tématu Vytvoření indexu .

Mapování datových typů

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.

1. 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=2026-04-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. 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.

3. 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í, zkontrolujte historii spuštění indexeru na portálu Azure nebo odešlete požadavek rozhraní REST API na získání stavu indexeru.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-04-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
        ]
    }

Historie vykonávání obsahuje až 50 nedávno dokončených vykonání, které jsou seřazeny v obráceném chronologickém pořadí tak, aby nejnovější vykoná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 je jedinou podporovanou politikou použití vlastnosti časového razítka, poskytované službou Azure Cosmos DB, pomocí HighWaterMarkChangeDetectionPolicy a _ts.

Následující příklad ukazuje definici zdroje dat se zásadami detekce změn:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
},

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é ukládání stavu, které Azure AI Vyhledávač používá k zajištění postupného pokroku 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. Můžete sdělit Azure AI Vyhledávač, že výsledky jsou seřazené pomocí nastavení vlastnosti konfigurace assumeOrderByHighWaterMarkColumn.

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 (odstranění je označeno určitým příznakem), 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 vlastnost, na kterou odkazuje softDeleteColumnName, je v dotazu zahrnuta.

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ů jako softDeleteColumnName není podporováno.

Následující příklad vytvoří zdroj dat se zásadou měkkého odstranění:

POST https://[service name].search.windows.net/datasources?api-version=2026-04-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

Nyní můžete řídit způsob, jak spuštíte indexer, monitorujete stav nebo plánujete provádění indexeru. Následující články platí pro indexery, které načítá obsah ze služby Azure Cosmos DB:

• Nastavení připojení indexeru k databázi Azure Cosmos DB pomocí spravované identity
• Indexování velkých datových sad
• Přístup indexeru k obsahu chráněnému funkcemi zabezpečení sítě Azure