Udostępnij za pośrednictwem

Indeksowanie danych z usługi Azure Cosmos DB for NoSQL dla zapytań w usłudze Azure AI Search

  • Artykuł

W tym artykule dowiesz się, jak skonfigurować indeksator , który importuje zawartość z usługi Azure Cosmos DB for NoSQL 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 witryny Azure Portal i 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

Aby pracować z przykładami w tym artykule, potrzebujesz witryny Azure Portal lub klienta REST. Jeśli używasz witryny Azure Portal, upewnij się, że dostęp do wszystkich sieci publicznych jest włączony. Inne podejścia do tworzenia indeksatora usługi Cosmos DB obejmują zestawy SDK platformy Azure.

Wypróbuj przykładowe dane

Skorzystaj z tych instrukcji, aby utworzyć kontener i bazę danych w usłudze Cosmos DB na potrzeby testowania.

  1. Pobierz HotelsData_toCosmosDB.JSON z usługi GitHub, aby utworzyć kontener w usłudze Cosmos DB zawierający podzbiór przykładowych zestawów danych hoteli.

  2. Zaloguj się do witryny Azure Portal i utwórz konto, bazę danych i kontener w usłudze Cosmos DB.

  3. W usłudze Cosmos DB wybierz pozycję Eksplorator danych dla nowego kontenera, podaj następujące wartości.

    Właściwości Wartość
    baza danych Tworzyć w programie
    Identyfikator bazy danych hotelsdb
    Udostępnianie przepływności między kontenerami Nie wybieraj
    Identyfikator kontenera hotele
    Klucz partycji /HotelId
    Przepływność kontenera (autoskalowanie) Skalowanie automatyczne
    Maksymalna liczba jednostek RU/s kontenera 1000

  4. W Eksploratorze danych rozwiń węzeł hotelsdb i *hotels", a następnie wybierz pozycję Elementy.

  5. Wybierz pozycję Przekaż element , a następnie wybierz plik HotelsData_toCosmosDB.JSON pobrany z usługi GitHub.

  6. Kliknij prawym przyciskiem myszy pozycję Elementy i wybierz pozycję Nowe zapytanie SQL. Domyślne zapytanie to SELECT * FROM c.

  7. Wybierz pozycję Wykonaj zapytanie , aby uruchomić zapytanie i wyświetlić wyniki. Powinien istnieć 50 dokumentów hotelowych.

Teraz, gdy masz kontener, możesz za pomocą witryny Azure Portal, klienta REST lub zestawu Azure SDK indeksować dane.

Pole Opis zawiera najbardziej szczegółową zawartość. To pole powinno być przeznaczone dla wyszukiwania pełnotekstowego i opcjonalnych zapytań wektorowych.

Korzystanie z witryny Azure Portal

Możesz użyć Kreatora importu danych lub Kreatora importowania i wektoryzacji danych, aby zautomatyzować indeksowanie z tabeli lub widoku bazy danych SQL. Konfiguracja źródła danych jest podobna dla obu kreatorów.

  1. Uruchom kreator.

  2. Na stronie Połącz z danymi wybierz lub sprawdź, czy typem źródła danych jest usługa Azure Cosmos DB lub konto NoSQL.

    Nazwa źródła danych odnosi się do obiektu połączenia źródła danych w usłudze Azure AI Search. Jeśli używasz kreatora wektorów, nazwa źródła danych jest generowana automatycznie przy użyciu niestandardowego prefiksu określonego na końcu przepływu pracy kreatora.

  3. Określ nazwę i kolekcję bazy danych. Zapytanie jest opcjonalne. Jest to przydatne, jeśli masz dane hierarchiczne i chcesz zaimportować określony fragment.

  4. Określ metodę uwierzytelniania , tożsamość zarządzaną lub wbudowany klucz interfejsu API. Jeśli nie określisz połączenia tożsamości zarządzanej, w witrynie Azure Portal jest używany klucz.

    Jeśli skonfigurujesz usługę Azure AI Search do używania tożsamości zarządzanej i utworzysz przypisanie roli w usłudze Cosmos DB, które przyznaje uprawnienia Czytelnik kont usługi Cosmos DB i Wbudowany czytnik danych usługi Cosmos DB do tożsamości, indeksator może nawiązać połączenie z usługą Cosmos DB przy użyciu identyfikatora i ról firmy Microsoft Entra.

  5. W przypadku kreatora Importowanie i wektoryzowanie danych można określić opcje śledzenia zmian i usuwania.

    Wykrywanie zmian jest domyślnie obsługiwane za pomocą _ts pola (znacznik czasu). Jeśli przekażesz zawartość przy użyciu podejścia opisanego w artykule Wypróbuj z przykładowymi danymi, kolekcja zostanie utworzona _ts przy użyciu pola.

    Wykrywanie usuwania wymaga wstępnie istniejącego pola najwyższego poziomu w kolekcji, które może być używane jako flaga usuwania nietrwałego. Powinno to być pole logiczne (można nazwać je IsDeleted). Określ true jako wartość usuwania nietrwałego. W indeksie wyszukiwania dodaj odpowiednie pole wyszukiwania o nazwie IsDeleted ustawione na pobieranie i filtrowanie.

  6. Przejdź do pozostałych kroków, aby ukończyć pracę kreatora:

Korzystanie z interfejsów API REST

W tej sekcji przedstawiono wywołania interfejsu API REST, które tworzą źródło danych, indeks i indeksator.

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 to niezależny zasób, który może być używany przez wiele indeksatorów.

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

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-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. Ustaw wartość "type" na "cosmosdb" (wymagane). Jeśli używasz starszego interfejsu API wyszukiwania w wersji 2017-11-11, składnia "type" to "documentdb". W przeciwnym razie w przypadku wersji 2019-05-06 lub nowszej użyj polecenia "cosmosdb".

  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 kolekcji bazy danych do indeksowania. Właściwość "query" jest opcjonalna. Służy do spłaszczania dowolnego dokumentu JSON do płaskiego schematu, który usługa Azure AI Search może indeksować.

  5. Ustaw wartość "dataChangeDetectionPolicy" , jeśli dane są nietrwałe i chcesz, aby indeksator pobierał tylko nowe i zaktualizowane elementy w kolejnych uruchomieniach.

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

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>" }`
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];)/(IdentityAuthType=[identity-auth-type])" }
Ta parametry połączenia nie wymaga klucza konta, ale musisz mieć usługę wyszukiwania, która może łączyć się przy użyciu tożsamości zarządzanej. W przypadku połączeń przeznaczonych dla interfejsu API SQL można pominąć ApiKind z parametry połączenia. Aby uzyskać więcej informacji na temat ApiKindprogramu , IdentityAuthType zobacz Konfigurowanie połączenia indeksatora z bazą danych usługi Azure Cosmos DB przy użyciu tożsamości zarządzanej.

Używanie zapytań do kształtowania indeksowanych danych

We właściwości "query" w obszarze "container" można określić zapytanie SQL w celu spłaszczania zagnieżdżonych właściwości lub tablic, właściwości projektu JSON i filtrowania danych do indeksowania.

Przykładowy dokument:

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

Zapytanie filtru:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Spłaszczanie zapytania:

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

Zapytanie projekcji:

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

Zapytanie spłaszczania tablicy:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Nieobsługiwane zapytania (DISTINCT i GROUP BY)

Zapytania używające słowa kluczowego DISTINCT lub klauzuli GROUP BY nie są obsługiwane. Usługa Azure AI Search opiera się na stronicowaniu zapytań SQL, aby w pełni wyliczyć wyniki zapytania. Ani klauzule DISTINCT lub GROUP BY nie są zgodne z tokenami kontynuacji używanymi do stronicowania wyników.

Przykłady nieobsługiwanych zapytań:

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

Mimo że usługa Azure Cosmos DB ma obejście umożliwiające obsługę stronicowania zapytań SQL przy użyciu słowa kluczowego DISTINCT przy użyciu klauzuli ORDER BY, nie jest ona zgodna z usługą Azure AI Search. Zapytanie zwraca pojedynczą wartość JSON, natomiast usługa Azure AI Search oczekuje obiektu 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

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 danymi źródłowymi. 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 przechowują dane:

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-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. 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 więcej pól w celu uzyskania większej zawartości z możliwością wyszukiwania. Aby uzyskać szczegółowe informacje, zobacz Tworzenie indeksu .

Mapowanie typów danych

Typy 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 for NoSQL

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=2024-07-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. 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, sprawdź historię wykonywania indeksatora w witrynie Azure Portal lub wyślij interfejs API REST Get Indexer Status REST

  1. Na stronie usługi wyszukiwania otwórz pozycję Indeksatory zarządzania wyszukiwaniem>.

  2. Wybierz indeksator, aby uzyskać dostęp do konfiguracji i historii wykonywania.

  3. Wybierz określone zadanie indeksatora, aby wyświetlić szczegóły, ostrzeżenia i błędy.

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

Uwaga

Po przypisaniu null wartości do pola w usłudze Azure Cosmos DB indeksator wyszukiwania sztucznej inteligencji nie może odróżnić wartości null pola od brakującej. W związku z tym jeśli pole w indeksie jest puste, nie zostanie zastąpione wartością null , nawet jeśli ta modyfikacja została wprowadzona w bazie danych.

Indeksowanie przyrostowe i zapytania niestandardowe

Jeśli używasz zapytania niestandardowego do pobierania dokumentów, upewnij się, że zapytanie porządkuje wyniki według kolumny _ts . Umożliwia to okresowe sprawdzanie, które usługa Azure AI Search używa do zapewnienia przyrostowego postępu w obecności awarii.

W niektórych przypadkach, nawet jeśli zapytanie zawiera klauzulę ORDER BY [collection alias]._ts , usługa Azure AI Search może nie wnioskować, że zapytanie jest uporządkowane przez _tselement . Możesz poinformować usługę Azure AI Search, że wyniki są uporządkowane, ustawiając assumeOrderByHighWaterMarkColumn właściwość konfiguracji.

Aby określić tę wskazówkę, utwórz lub zaktualizuj definicję indeksatora w następujący sposób:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Indeksowanie usuniętych dokumentów

Gdy wiersze są usuwane z kolekcji, zwykle chcesz usunąć te wiersze z indeksu wyszukiwania. Celem zasad wykrywania usuwania danych jest efektywne identyfikowanie usuniętych elementów danych. 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"
}

Jeśli używasz zapytania niestandardowego, upewnij się, że właściwość, do której odwołuje się softDeleteColumnName kwerenda, jest przewidywana.

Musi softDeleteColumnName być polem najwyższego poziomu w indeksie. Używanie zagnieżdżonych pól w złożonych typach danych, ponieważ softDeleteColumnName nie jest obsługiwane.

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

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

Korzystanie z platformy .NET

Aby uzyskać dostęp do danych za pośrednictwem protokołu interfejsu API SQL, możesz użyć zestawu SDK platformy .NET do automatyzacji za pomocą indeksatorów. Zalecamy zapoznanie się z poprzednimi sekcjami interfejsu API REST, aby poznać pojęcia, przepływ pracy i wymagania. Następnie możesz zapoznać się z następującą dokumentacją referencyjną interfejsu API platformy .NET, aby zaimplementować indeksator JSON w kodzie zarządzanym:

Następne kroki

Teraz możesz kontrolować sposób uruchamiania indeksatora, monitorowania stanu lub planowania wykonywania indeksatora. Następujące artykuły dotyczą indeksatorów pobierających zawartość z usługi Azure Cosmos DB: