Indeksowanie danych z Azure Cosmos DB dla języka Apache Gremlin w przypadku zapytań w Wyszukiwanie AI platformy Azure (wersja zapoznawcza)

Indeksator Azure Cosmos DB dla Apache Gremlin (wersja zapoznawcza) importuje zawartość z Azure Cosmos DB dla Apache Gremlin i umożliwia przeszukiwanie jej za pomocą usługi Wyszukiwanie AI platformy Azure.

Ten artykuł uzupełnia Tworzenie indeksatora o informacje specyficzne 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 utworzenia indeksatora.

Ponieważ terminologia może być myląca, warto zauważyć, że indeksowanie Azure Cosmos DB i indeksowanie Wyszukiwanie AI platformy Azure to różne operacje. Indeksowanie w Wyszukiwanie AI platformy Azure tworzy i ładuje indeks wyszukiwania w usłudze wyszukiwania.

Wymagania wstępne

• Wypełnij formularz rejestracji w wersji zapoznawczej indeksatora. Rejestracja jest zatwierdzana automatycznie.

• Konto Azure Cosmos DB, baza danych, kontener i elementy. Użyj tego samego regionu zarówno dla Wyszukiwanie AI platformy Azure, jak i Azure Cosmos DB w celu zmniejszenia opóźnienia i uniknięcia opłat za przepustowość.

• Automatyczna zasada indeksowania w kolekcji Azure Cosmos DB, ustawiona na Consistent. To ustawienie jest konfiguracją domyślną. Indeksowanie z opóźnieniem nie jest zalecane i może spowodować brak danych.

• Uprawnienia do odczytu. Łańcuch połączenia "pełny dostęp" zawiera klucz, który zapewnia dostęp do zawartości, ale jeśli używasz ról Azure, upewnij się, że tożsamość zarządzana usługi search ma uprawnienia Rola czytelnika konta 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ę interfejsu API REST w wersji zapoznawczej, aby utworzyć źródło danych łączące się za pośrednictwem Azure Cosmos DB dla języka Apache Gremlin. Możesz użyć wersji 2021-04-01-preview lub nowszej. Zalecamy najnowszą wersję zapoznawczą interfejsu API REST.

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

    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. 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 Wyszukiwanie AI platformy Azure dla Azure Cosmos DB dla platformy Apache Gremlin sprawia, że każdy wierzchołek na grafie jest dokumentem w indeksie. Krawędzie są ignorowane. 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 wartość g.E().

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 jest domyślnie włączony przy użyciu _ts kolumny górnego znacznika wody.

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ń docelowych Azure Cosmos DB dla platformy Apache Gremlin należy uwzględnić element "ApiKind" w parametry połączenia.

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

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 Azure Cosmos DB schemat indeksu wyszukiwania powinien odpowiadać elementom Azure Cosmos DB w źródle danych.

1. Utwórz lub zaktualizuj indeks , aby zdefiniować pola wyszukiwania, które przechowują dane:

    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. Utwórz pole klucza dokumentu ("key": true). W przypadku kolekcji partycjonowanych domyślny klucz dokumentu to właściwość Azure Cosmos DB _rid, która Wyszukiwanie AI platformy Azure automatycznie zmienia nazwę na rid, ponieważ nazwy pól nie mogą rozpoczynać się od znaku podkreślenia. Ponadto wartości Azure Cosmos DB _rid zawierają znaki, które są nieprawidłowe w kluczach wyszukiwania Azure AI. 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

Konfigurowanie i uruchamianie indeksatora 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=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. 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=2026-08-01-preview
  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 uruchomienia indeksatora częściowo indeksowały 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 dla Twoich danych.

W przypadku indeksatorów Azure Cosmos DB jedyną obsługiwaną zasadą jest HighWaterMarkChangeDetectionPolicy z użyciem atrybutu _ts (sygnatura czasowa), udostępnianego przez 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 jedyną obsługiwaną zasadą jest Soft Delete zasada (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 zasadą miękkiego usuwania.

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

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

Mapowanie danych grafu na pola w indeksie wyszukiwania

Indeksator Azure Cosmos DB dla języka Apache Gremlin automatycznie mapuje kilka fragmentów danych grafu:

1. Indeksator mapuje _rid do pola rid w indeksie, jeśli istnieje, a następnie koduje je w formacie Base64.

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

3. Podczas wykonywania zapytań dotyczących bazy danych Azure Cosmos DB przy użyciu 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ą wartość id i value. Indeksator automatycznie mapuje właściwość value na pole w indeksie wyszukiwania, które ma taką samą nazwę jak właściwość, jeśli istnieje. W poniższym przykładzie wartość 450 jest przypisana do pola pages 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 zawiera 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 i nie zawiera odwołania do klucza właściwości w JSON. Dzieje się tak dlatego, że indeksator umieszcza każdy dokument w węźle /document podczas pozyskiwania danych grafu, a indeksator automatycznie umożliwia odwołanie się do wartości pages poprzez proste odwołanie do pages zamiast odwoływania się do pierwszego obiektu w tablicy pages.

Następne kroki

• Aby dowiedzieć się więcej na temat Azure Cosmos DB dla języka Apache Gremlin, zobacz Wprowadzenie do Azure Cosmos DB: Azure Cosmos DB dla języka Apache Gremlin.

• Aby uzyskać więcej informacji na temat scenariuszy i cen Wyszukiwanie AI platformy Azure, zobacz stronę usługi Search w witrynie azure.microsoft.com.

• Aby dowiedzieć się więcej o konfiguracji sieci dla indeksatorów, zobacz Indexer dostęp do zawartości chronionej przez funkcje zabezpieczeń sieci Azure.