Indexování dat ze služby Azure Cosmos DB pro Apache Gremlin pro dotazy ve službě Azure AI Search

  • Článek

Důležité

Indexer Azure Cosmos DB for Apache Gremlin je v současné době ve verzi Public Preview v rámci doplňkových podmínek použití. V současné době neexistuje žádná podpora sady SDK.

V tomto článku se dozvíte, jak nakonfigurovat indexer , který importuje obsah ze služby Azure Cosmos DB pro Apache Gremlin 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

  • Zaregistrujte si verzi Preview a poskytněte nám zpětnou vazbu ke scénáři. K funkci se dostanete automaticky po odeslání formuláře.

  • Úč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 role Azure, ujistěte se, že spravovaná identita vyhledávací služby má oprávnění role Čtenář účtu služby 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 verze Preview (2020-06-30-Preview nebo 2021-04-30-Preview) a vytvořte zdroj dat, který se připojuje přes Azure Cosmos DB pro Apache Gremlin.

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

     POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-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. Nastavte kontejner na kolekci. Vlastnost name je povinná a určuje ID grafu.

    Vlastnost dotaz je volitelná. Ve výchozím nastavení indexer Azure AI Search pro Azure Cosmos DB for Apache Gremlin vytvoří každý vrchol v grafu dokument v indexu. Hrany budou ignorovány. 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 data nestálá a chcete, aby indexer vyzvedal pouze nové a aktualizované položky v následných spuštěních. Přírůstkový průběh se ve výchozím nastavení povolí jako _ts sloupec horní značky.

  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í. Pro připojení, která cílí na Službu 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í 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>;ApiKind=MongoDb" }
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];)" }
Tato připojovací řetězec nevyžaduje klíč účtu, ale dříve jste nakonfigurovali vyhledávací službu pro připojení pomocí spravované identity a vytvořili přiřazení role, které uděluje oprávnění čtenáře účtu služby Cosmos DB. Další informace najdete v tématu Nastavení připojení indexeru k databázi Azure Cosmos DB pomocí spravované identity .

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 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á budou ukládat data:

     POST https://[service name].search.windows.net/indexes?api-version=2020-06-30-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 , 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 Search neplatné. 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ů

Datový typ 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 služby 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=2020-06-30
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=2020-06-30
  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"
},

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

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=2020-06-30-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í dat grafu:

  1. Indexer bude mapovat _rid na rid pole v indexu, pokud existuje, a Base64 ho zakóduje.

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

  3. Při dotazování databáze Azure Cosmos DB pomocí služby 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 vlastnosti value do pole ve vyhledávacím indexu, které má stejný název jako vlastnost, pokud existuje. V následujícím příkladu by bylo 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 budete muset použít mapování výstupních polí. Pravděpodobně budete chtít místo mapování polí použít mapování výstupních polí, protože vlastní dotaz bude pravděpodobně obsahovat 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