Indexování dat z Azure Cosmos DB pro Apache Gremlin pro dotazy v Azure AI Vyhledávač (Preview)

Indexer služby Azure Cosmos DB pro Apache Gremlin (verze Preview) importuje obsah z Azure Cosmos DB pro Apache Gremlin a zpřístupňuje ho k vyhledávání ve službě Azure AI Vyhledávač.

Tento článek doplňuje vytvoření indexeru informacemi, které jsou specifické pro 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í, je vhodné poznamenat, že Azure Cosmos DB indexování a Azure AI Vyhledávač indexování jsou různé operace. Indexování v Azure AI Vyhledávač vytvoří a načte vyhledávací index ve vaší vyhledávací službě.

Požadavky

• Vyplňte registrační formulář indexeru ve verzi Preview. Registrace se automaticky schválí.

• Úč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ásada automatické indexování v kolekci Azure Cosmos DB nastavená na Konsistent. Toto nastavení 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 role Azure, ujistěte se, že spravovaná identita služby search má Role čtenáře účtů 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 definován jako nezávislý prostředek, aby ho mohl používat více indexerů.

Pro toto volání zadejte verzi rozhraní REST API ve verzi Preview pro vytvoření zdroje dat, který se připojuje přes Azure Cosmos DB pro Apache Gremlin. Můžete použít verzi 2021-04-01-preview nebo novější. Doporučujeme nejnovější rozhraní REST API verze Preview.

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

    POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
    Content-Type: application/json
    api-key: [Search service admin key]
    {
      "name": "[my-cosmosdb-gremlin-ds]",
      "type": "cosmosdb",
      "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;"
      },
      "container": {
        "name": "[cosmos-db-collection]",
        "query": "g.V()"
      },
      "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
      },
      "dataDeletionDetectionPolicy": null,
      "encryptionKey": null,
      "identity": null
    }
   

2. Nastavte "typ" na "cosmosdb" (povinné).

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

4. Definujte "kontejner" jako součástí kolekce. Vlastnost name je povinná a určuje ID grafu.

   Vlastnost dotaz je volitelná. Ve výchozím nastavení indexer Azure AI Vyhledávač pro Azure Cosmos DB pro Apache Gremlin vytvoří každý vrchol v grafu dokument v indexu. Hrany se ignorují. Výchozí dotaz je g.V(). Případně můžete dotaz nastavit tak, aby indexovat pouze hrany. Chcete-li indexovat hrany, nastavte dotaz na g.E().

5. Nastavte „dataChangeDetectionPolicy“, pokud jsou vaše data proměnlivá a chcete, aby indexer při následných spuštěních zpracoval pouze nové a aktualizované položky. Přírůstkové zpracování je ve výchozím nastavení povoleno a jako sloupec s horní mezní hodnotou používá _ts.

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ězce

Indexery se můžou připojit ke kolekci pomocí následujících připojení. U připojení, která cílí na Azure Cosmos DB pro Apache Gremlin, nezapomeňte do připojovací řetězec zahrnout "ApiKind".

Vyhněte se číslům portů v adrese URL koncového bodu. Pokud zadáte číslo portu, připojení selže.

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í s grafem. Pro obsah v Azure Cosmos DB by schéma indexu vyhledávání mělo odpovídat položkám 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-08-01-preview
    Content-Type: application/json
    api-key: [Search service admin key]
    {
       "name": "mysearchindex",
       "fields": [
        {
            "name": "rid",
            "type": "Edm.String",
            "facetable": false,
            "filterable": false,
            "key": true,
            "retrievable": true,
            "searchable": true,
            "sortable": false,
            "analyzer": "standard.lucene",
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "synonymMaps": [],
            "fields": []
        }, {
            "name": "label",
            "type": "Edm.String",
            "searchable": true,
            "filterable": false,
            "retrievable": true,
            "sortable": false,
            "facetable": false,
            "key": false,
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "analyzer": "standard.lucene",
            "synonymMaps": []
       }]
     }
   

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, která Azure AI Vyhledávač automaticky přejmenovávat na rid, protože názvy polí nemůžou začínat znakem podtržítka. Hodnoty Azure Cosmos DB _rid také obsahují neplatné znaky v klíčích Azure AI Vyhledávač. Z tohoto důvodu _rid jsou hodnoty kódovány base64.

3. Vytvořte 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

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-08-01-preview
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-gremlin-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í, odešlete žádost o získání stavu indexeru :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  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 je jedinou podporovanou zásadou HighWaterMarkChangeDetectionPolicy pomocí vlastnosti _ts (časové razítko), kterou poskytuje 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"
},

Indexování odstraněných dokumentů

Po odstranění dat grafu můžete také z indexu vyhledávání odstranit odpovídající dokument. Účelem zásad detekce odstranění dat je efektivně identifikovat odstraněné datové položky a odstranit celý dokument z indexu. Zásady detekce odstranění dat nejsou určené k odstranění částečných informací o dokumentu. V současné době je jedinou podporovanou zásadou Soft Delete (odstranění je označeno určitým příznakem), která je specifikována v definici zdroje dat následovně:

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

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

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "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"
    }
}

I když povolíte zásady detekce odstranění, odstranění složitých (Edm.ComplexType) polí z indexu se nepodporuje. Tato zásada vyžaduje, aby sloupec "aktivní" v databázi Gremlin byl typu integer, řetězec nebo logická hodnota.

Mapování dat grafu na pole v indexu vyhledávání

Indexer Azure Cosmos DB pro Apache Gremlin automaticky mapuje několik částí grafových dat:

1. Indexer mapuje _rid na pole rid v indexu, pokud existuje, a zakóduje jej pomocí Base64.

2. Indexer mapuje _id na pole id v indexu, pokud existuje.

3. Při dotazování Azure Cosmos DB databáze pomocí Azure Cosmos DB pro Apache Gremlin si můžete všimnout, že výstup JSON pro každou vlastnost má hodnotu id a value. Indexer automaticky mapuje vlastnost value do pole ve vyhledávacím indexu, které má stejný název jako vlastnost, pokud existuje. V následujícím příkladu je 450 namapováno na pages pole v indexu vyhledávání.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

Možná zjistíte, že k mapování výstupu dotazu na pole v indexu potřebujete mapování výstupních polí . Místo mapování polí budete pravděpodobně chtít použít mapování výstupních polí, protože vlastní dotaz pravděpodobně obsahuje složitá data.

Řekněme například, že váš dotaz vytvoří tento výstup:

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

Pokud chcete namapovat hodnotu pages ve formátu JSON výše na totalpages pole v indexu, můžete do definice indexeru přidat následující mapování výstupních polí :

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

Všimněte si, že mapování výstupního pole začíná /document a neobsahuje odkaz na klíč vlastností ve formátu JSON. Je to proto, že indexer při ingestování dat grafu umístí každý dokument do /document uzlu a indexer také automaticky umožňuje odkazovat na hodnotu pages jednoduchým odkazováním pages , místo abyste museli odkazovat na první objekt v poli pages.

Další kroky

• Další informace o Azure Cosmos DB pro Apache Gremlin najdete v Introduction k Azure Cosmos DB: Azure Cosmos DB pro Apache Gremlin.

• Další informace o Azure AI Vyhledávač scénářích a cenách najdete na stránce služby Search na azure.microsoft.com.

• Informace o konfiguraci sítě pro indexery najdete v tématu Indexer přístup k obsahu chráněnému funkcemi zabezpečení sítě Azure.