Indeksowanie danych z usługi Azure Cosmos DB for NoSQL dla zapytań w usłudze Azure AI Search
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 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
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 kontroli dostępu opartej na rolach platformy Azure (Microsoft Entra ID), upewnij się, że tożsamość zarządzana usługi wyszukiwania jest przypisana zarówno rola czytelnika konta usługi Cosmos DB, jak i wbudowana rola czytnika danych 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 to niezależny zasób, który może być używany przez wiele indeksatorów.
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 }
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"
.Ustaw wartość "credentials" na parametry połączenia. W następnej sekcji opisano obsługiwane formaty.
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ć.
Ustaw wartość "dataChangeDetectionPolicy" , jeśli dane są nietrwałe i chcesz, aby indeksator pobierał tylko nowe i zaktualizowane elementy w kolejnych uruchomieniach.
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 ApiKind programu , 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.
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 } ] }
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.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.
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 }
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.
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=2024-07-01
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"
},
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 _ts
element . 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:
- azure.search.documents.indexes.models.searchindexerdatasourceconnection
- azure.search.documents.indexes.models.searchindexerdatasourcetype
- azure.search.documents.indexes.models.searchindex
- azure.search.documents.indexes.models.searchindexer
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: