Indeksowanie danych z usługi Azure Cosmos DB dla języka Apache Gremlin dla zapytań w usłudze Azure AI Search

  • Artykuł

Ważne

Indeksator usługi Azure Cosmos DB for Apache Gremlin jest obecnie w publicznej wersji zapoznawczej w obszarze Uzupełniające warunki użytkowania. Obecnie nie ma obsługi zestawu SDK.

Z tego artykułu dowiesz się, jak skonfigurować indeksator, który importuje zawartość z usługi Azure Cosmos DB dla języka Apache Gremlin i umożliwia wyszukiwanie w usłudze Azure AI Search.

Ten artykuł uzupełnia tworzenie indeksatora z informacjami specyficznymi dla usługi Cosmos DB. Używa ona interfejsów API REST, aby zademonstrować trzyczęściowy przepływ pracy wspólny dla wszystkich indeksatorów: tworzenie źródła danych, tworzenie indeksu, tworzenie indeksatora. Wyodrębnianie danych odbywa się podczas przesyłania żądania Tworzenia indeksatora.

Ponieważ terminologia może być myląca, warto zauważyć, że indeksowanie usługi Azure Cosmos DB i indeksowanie usługi Azure AI Search są różnymi operacjami. Indeksowanie w usłudze Azure AI Search tworzy i ładuje indeks wyszukiwania w usłudze wyszukiwania.

Wymagania wstępne

  • Zarejestruj się, aby uzyskać informacje o wersji zapoznawczej , aby przekazać opinię na temat scenariusza. Dostęp do funkcji można uzyskać automatycznie po przesłaniu formularza.

  • Konto , baza danych, kontener i elementy usługi Azure Cosmos DB. Użyj tego samego regionu zarówno dla usługi Azure AI Search, jak i usługi Azure Cosmos DB, aby uzyskać mniejsze opóźnienia i uniknąć opłat za przepustowość.

  • Zasady automatycznego indeksowania w kolekcji usługi Azure Cosmos DB są ustawione na Spójne. To jest konfiguracja domyślna. Indeksowanie z opóźnieniem nie jest zalecane i może spowodować brak danych.

  • Uprawnienia do odczytu. "Pełny dostęp" parametry połączenia zawiera klucz, który udziela dostępu do zawartości, ale jeśli używasz ról platformy Azure, upewnij się, że tożsamość zarządzana usługi wyszukiwania ma uprawnienia roli Czytelnik konta usługi Cosmos DB.

  • Klient REST do tworzenia źródła danych, indeksu i indeksatora.

Definiowanie źródła danych

Definicja źródła danych określa dane do indeksowania, poświadczeń i zasad identyfikowania zmian w danych. Źródło danych jest definiowane jako niezależny zasób, dzięki czemu może być używane przez wiele indeksatorów.

W przypadku tego wywołania określ wersję zapoznawczą interfejsu API REST (2020-06-30-Preview lub 2021-04-30-Preview), aby utworzyć źródło danych łączące się za pośrednictwem usługi Azure Cosmos DB dla języka Apache Gremlin.

  1. Utwórz lub zaktualizuj źródło danych, aby ustawić jego definicję:

     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. Ustaw wartość "type" na "cosmosdb" (wymagane).

  3. Ustaw wartość "credentials" na parametry połączenia. W następnej sekcji opisano obsługiwane formaty.

  4. Ustaw wartość "container" na kolekcję. Właściwość "name" jest wymagana i określa identyfikator grafu.

    Właściwość "query" jest opcjonalna. Domyślnie indeksator usługi Azure AI Search dla usługi Azure Cosmos DB for Apache Gremlin sprawia, że każdy wierzchołek na grafie jest dokumentem w indeksie. Krawędzie zostaną zignorowane. Domyślną wartością zapytania jest g.V(). Alternatywnie można ustawić zapytanie tak, aby indeksować tylko krawędzie. Aby indeksować krawędzie, ustaw zapytanie na g.E()wartość .

  5. Ustaw wartość "dataChangeDetectionPolicy" , jeśli dane są nietrwałe i chcesz, aby indeksator pobierał tylko nowe i zaktualizowane elementy w kolejnych uruchomieniach. Postęp przyrostowy zostanie domyślnie włączony przy użyciu _ts kolumny górnego znaku wodnego.

  6. Ustaw wartość "dataDeletionDetectionPolicy" , jeśli chcesz usunąć dokumenty wyszukiwania z indeksu wyszukiwania po usunięciu elementu źródłowego.

Obsługiwane poświadczenia i parametry połączenia

Indeksatory mogą łączyć się z kolekcją przy użyciu następujących połączeń. W przypadku połączeń przeznaczonych dla usługi Azure Cosmos DB dla języka Apache Gremlin upewnij się, że w parametry połączenia dołącz ciąg "ApiKind".

Unikaj numerów portów w adresie URL punktu końcowego. Jeśli dołączysz numer portu, połączenie zakończy się niepowodzeniem.

Parametry połączenia pełnego dostępu
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Możesz uzyskać parametry połączenia ze strony konta usługi Azure Cosmos DB w witrynie Azure Portal, wybierając pozycję Klucze w okienku nawigacji po lewej stronie. Pamiętaj, aby wybrać pełny parametry połączenia, a nie tylko klucz.
Parametry połączenia tożsamości zarządzanej
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Ta parametry połączenia nie wymaga klucza konta, ale musisz wcześniej skonfigurować usługę wyszukiwania, aby nawiązać połączenie przy użyciu tożsamości zarządzanej i utworzyć przypisanie roli, które przyznaje uprawnienia roli czytelnika konta usługi Cosmos DB. Aby uzyskać więcej informacji, zobacz Konfigurowanie połączenia indeksatora z bazą danych usługi Azure Cosmos DB przy użyciu tożsamości zarządzanej.

Dodawanie pól wyszukiwania do indeksu

W indeksie wyszukiwania dodaj pola, aby zaakceptować źródłowe dokumenty JSON lub dane wyjściowe projekcji zapytania niestandardowego. Upewnij się, że schemat indeksu wyszukiwania jest zgodny z wykresem. W przypadku zawartości w usłudze Azure Cosmos DB schemat indeksu wyszukiwania powinien odpowiadać elementom usługi Azure Cosmos DB w źródle danych.

  1. Utwórz lub zaktualizuj indeks , aby zdefiniować pola wyszukiwania, które będą przechowywać dane:

     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. Utwórz pole klucza dokumentu ("key": true). W przypadku kolekcji partycjonowanych domyślny klucz dokumentu to właściwość usługi Azure Cosmos DB _rid , do której usługa Azure AI Search automatycznie zmienia nazwę rid , ponieważ nazwy pól nie mogą zaczynać się od znaku podkreślenia. Ponadto wartości usługi Azure Cosmos DB _rid zawierają znaki, które są nieprawidłowe w kluczach usługi Azure AI Search. Z tego powodu _rid wartości są zakodowane w formacie Base64.

  3. Utwórz dodatkowe pola w celu uzyskania większej zawartości z możliwością wyszukiwania. Aby uzyskać szczegółowe informacje, zobacz Tworzenie indeksu .

Mapowanie typów danych

Typ danych JSON Typy pól usługi Azure AI Search
Bool Edm.Boolean, Edm.String
Liczby, które wyglądają jak liczby całkowite Edm.Int32, Edm.Int64, Edm.String
Liczby, które wyglądają jak zmiennoprzecinkowe Edm.Double, Edm.String
String Edm.String
Tablice typów pierwotnych, takich jak ["a", "b", "c"] Collection(Edm.String)
Ciągi, które wyglądają jak daty Edm.DateTimeOffset, Edm.String
Obiekty GeoJSON, takie jak { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Inne obiekty JSON Nie dotyczy

Konfigurowanie i uruchamianie indeksatora usługi Azure Cosmos DB

Po utworzeniu indeksu i źródła danych możesz utworzyć indeksator. Konfiguracja indeksatora określa dane wejściowe, parametry i właściwości kontrolujące zachowania czasu wykonywania.

  1. Utwórz lub zaktualizuj indeksator , podając mu nazwę i odwołując się do źródła danych i indeksu docelowego:

    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. Określ mapowania pól, jeśli istnieją różnice w nazwie lub typie pola lub jeśli potrzebujesz wielu wersji pola źródłowego w indeksie wyszukiwania.

  3. Aby uzyskać więcej informacji na temat innych właściwości, zobacz Tworzenie indeksatora .

Indeksator jest uruchamiany automatycznie po jego utworzeniu. Możesz temu zapobiec, ustawiając wartość "disabled" na true. Aby kontrolować wykonywanie indeksatora, uruchom indeksator na żądanie lub umieść go zgodnie z harmonogramem.

Sprawdzanie stanu indeksatora

Aby monitorować stan indeksatora i historię wykonywania, wyślij żądanie pobierz stan indeksatora:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

Odpowiedź zawiera stan i liczbę przetworzonych elementów. Powinien on wyglądać podobnie do poniższego przykładu:

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

Historia wykonywania zawiera do 50 ostatnio wykonanych wykonań, które są sortowane w odwrotnej kolejności chronologicznej, tak aby najnowsze wykonanie było wykonywane jako pierwsze.

Indeksowanie nowych i zmienionych dokumentów

Gdy indeksator w pełni wypełni indeks wyszukiwania, możesz chcieć, aby kolejne indeksatory stopniowo indeksował tylko nowe i zmienione dokumenty w bazie danych.

Aby włączyć indeksowanie przyrostowe, ustaw właściwość "dataChangeDetectionPolicy" w definicji źródła danych. Ta właściwość informuje indeksator, który mechanizm śledzenia zmian jest używany na danych.

W przypadku indeksatorów usługi Azure Cosmos DB jedynymi obsługiwanymi zasadami jest HighWaterMarkChangeDetectionPolicy użycie _ts właściwości (sygnatury czasowej) udostępnianej przez usługę Azure Cosmos DB.

W poniższym przykładzie przedstawiono definicję źródła danych z zasadami wykrywania zmian:

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

Indeksowanie usuniętych dokumentów

Po usunięciu danych grafu możesz również usunąć odpowiedni dokument z indeksu wyszukiwania. Celem zasad wykrywania usuwania danych jest efektywne identyfikowanie usuniętych elementów danych i usuwanie pełnego dokumentu z indeksu. Zasady wykrywania usuwania danych nie są przeznaczone do usuwania częściowych informacji o dokumencie. Obecnie jedynymi obsługiwanymi zasadami są Soft Delete zasady (usunięcie jest oznaczone flagą pewnego rodzaju), która jest określona w definicji źródła danych w następujący sposób:

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

Poniższy przykład tworzy źródło danych z zasadami usuwania nietrwałego:

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

Nawet jeśli włączysz zasady wykrywania usuwania, usuwanie złożonych pól (Edm.ComplexType) z indeksu nie jest obsługiwane. Te zasady wymagają, aby kolumna "aktywna" w bazie danych Gremlin był typu liczba całkowita, ciąg lub wartość logiczna.

Mapowanie danych grafu na pola w indeksie wyszukiwania

Indeksator usługi Azure Cosmos DB for Apache Gremlin automatycznie mapuje kilka fragmentów danych grafu:

  1. Indeksator zamapuje _rid je na rid pole w indeksie, jeśli istnieje, i zakoduje go base64.

  2. Indeksator mapuje _id je na id pole w indeksie, jeśli istnieje.

  3. Podczas wykonywania zapytań dotyczących bazy danych usługi Azure Cosmos DB przy użyciu usługi Azure Cosmos DB dla języka Apache Gremlin można zauważyć, że dane wyjściowe JSON dla każdej właściwości mają id wartość i value. Indeksator automatycznie zamapuje właściwości value na pole w indeksie wyszukiwania o takiej samej nazwie jak właściwość, jeśli istnieje. W poniższym przykładzie 450 zostanie zamapowanych na pages pole w indeksie wyszukiwania.

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

Może się okazać, że musisz użyć mapowań pól wyjściowych , aby zamapować dane wyjściowe zapytania na pola w indeksie. Prawdopodobnie chcesz użyć mapowań pól wyjściowych zamiast mapowań pól, ponieważ zapytanie niestandardowe prawdopodobnie będzie mieć złożone dane.

Załóżmy na przykład, że zapytanie generuje następujące dane wyjściowe:

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

Jeśli chcesz zamapować wartość pages w powyższym formacie JSON na totalpages pole w indeksie, możesz dodać następujące mapowanie pól wyjściowych do definicji indeksatora:

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

Zwróć uwagę, że mapowanie pól wyjściowych rozpoczyna się od /document elementu i nie zawiera odwołania do klucza właściwości w formacie JSON. Dzieje się tak dlatego, że indeksator umieszcza każdy dokument w /document węźle podczas pozyskiwania danych grafu, a indeksator automatycznie umożliwia odwoływanie pages się do wartości pages przez proste odwołanie zamiast odwoływać się do pierwszego obiektu w tablicy pages.

Następne kroki