Индексирование данных из Azure Cosmos DB для NoSQL для запросов в поиске ИИ Azure
Из этой статьи вы узнаете, как настроить индексатор , который импортирует содержимое из Azure Cosmos DB для NoSQL и делает его доступным для поиска в Azure AI Search.
В этой статье описано , как создать индексатор с информацией, относяющейся к Cosmos DB. В нем используются ИНТЕРФЕЙСы REST API для демонстрации трех частей рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.
Так как терминология может быть запутана, стоит отметить, что индексирование Azure Cosmos DB и индексирование поиска ИИ Azure отличаются операциями. Индексирование в службе поиска ИИ Azure создает и загружает индекс поиска в службе поиска.
Необходимые компоненты
Учетная запись Azure Cosmos DB, база данных, контейнер и элементы. Используйте один и тот же регион для поиска ИИ Azure и Azure Cosmos DB для снижения задержки и для предотвращения расходов на пропускную способность.
Политика автоматического индексирования в коллекции Azure Cosmos DB установите значение "Согласованный". Это конфигурация по умолчанию. Отложенное индексирование не рекомендуется и может привести к отсутствием данных.
Разрешения на чтение. Строка подключения "полный доступ" включает ключ, который предоставляет доступ к содержимому, но если вы используете Azure RBAC (идентификатор Microsoft Entra ID), убедитесь, что управляемое удостоверение службы поиска назначено как роль читателя учетной записи Cosmos DB, так и встроенная роль чтения данных Cosmos DB.
Клиент REST для создания источника данных, индекса и индексатора.
Определение источника данных
Определение источника данных указывает данные для индексирования, учетных данных и политик для выявления изменений в данных. Источник данных — это независимый ресурс, который может использоваться несколькими индексаторами.
Создайте или обновите источник данных, чтобы задать его определение:
POST https://[service name].search.windows.net/datasources?api-version=2023-11-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 }
Задайте для параметра type
"cosmosdb"
(обязательный). Если вы используете более старый API поиска версии 2017-11-11, используется"documentdb"
синтаксис типа. В противном случае для 2019-05-06 и более поздних версий используйте"cosmosdb"
.Задайте для параметра "Учетные данные" значение строка подключения. В следующем разделе описаны поддерживаемые форматы.
Задайте для коллекции значение container. Свойство name является обязательным и указывает идентификатор коллекции баз данных для индексирования. Свойство query является необязательным. Используйте его для выравнивания произвольного документа JSON в неструктурированной схеме, которую может индексировать поиск ИИ Azure.
Задайте значение dataChangeDetectionPolicy, если данные являются переменными, и индексатор будет получать только новые и обновленные элементы при последующих запусках.
Установите параметр dataDeletionDetectionPolicy, если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента.
Поддерживаемые учетные данные и строка подключения
Индексаторы могут подключаться к коллекции с помощью следующих подключений.
Избегайте номеров портов в URL-адресе конечной точки. Если включить номер порта, подключение завершится ошибкой.
Полный доступ строка подключения |
---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id> " }` |
Вы можете получить строка подключения на странице учетной записи Azure Cosmos DB в портал Azure, выбрав "Ключи" в области навигации слева. Не забудьте выбрать полную строка подключения и не только ключ. |
Управляемое удостоверение строка подключения |
---|
{ "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])" } |
Для этого строка подключения не требуется ключ учетной записи, но у вас должна быть служба поиска, которая может подключаться с помощью управляемого удостоверения. Для подключений, предназначенных для API SQL, можно исключить ApiKind из строка подключения. Дополнительные сведения см. в ApiKind IdentityAuthType статье "Настройка подключения индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения". |
Использование запросов для формирования индексированных данных
В свойстве query в разделе "контейнер" можно указать SQL-запрос для плоских вложенных свойств или массивов, свойств проекта JSON и отфильтровать данные для индексирования.
Пример документа:
{
"userId": 10001,
"contact": {
"firstName": "andy",
"lastName": "hoh"
},
"company": "microsoft",
"tags": ["azure", "cosmosdb", "search"]
}
Запрос на фильтрацию:
SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts
Преобразование запросов:
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
Запрос на проектирование:
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
Массив преобразованных запросов:
SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts
Неподдерживаемые запросы (DISTINCT и GROUP BY)
Запросы, использующие ключевое слово DISTINCT или предложение GROUP BY, не поддерживаются. Поиск ИИ Azure использует разбиение на страницы SQL-запроса, чтобы полностью перечислить результаты запроса. Ни ключевое слово DISTINCT, ни предложения GROUP BY не совместимы с маркерами продолжения, используемыми для разбивки результатов.
Примеры неподдерживаемых запросов
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
Хотя Azure Cosmos DB имеет обходное решение для поддержки разбиения запросов SQL с ключевым словом DISTINCT с помощью предложения ORDER BY, оно несовместимо с поиском ИИ Azure. Запрос возвращает одно значение JSON, в то время как служба "Поиск ИИ Azure" ожидает объект 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
Добавление полей поиска в индекс
В индексе поиска добавьте поля, чтобы принять исходные документы JSON или выходные данные пользовательской проекции запроса. Убедитесь, что схема индекса поиска совместима с исходными данными. Для содержимого в Azure Cosmos DB схема индекса поиска должна соответствовать элементам Azure Cosmos DB в источнике данных.
Создайте или обновите индекс , чтобы определить поля поиска, в которые хранятся данные:
POST https://[service name].search.windows.net/indexes?api-version=2023-11-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 } ] }
Создайте поле ключа документа ("key": true"). Для секционированных коллекций ключ документа по умолчанию — это свойство Azure Cosmos DB
_rid
, в которое служба "Поиск ИИ Azure" автоматически переименовываетсяrid
, так как имена полей не могут начинаться с символа подчеркивания. Кроме того, значения Azure Cosmos DB_rid
содержат символы, недопустимые в ключах поиска ИИ Azure. Поэтому значения_rid
представлены в кодировке Base64.Создайте дополнительные поля для более доступных для поиска содержимого. Дополнительные сведения см. в статье "Создание индекса ".
Сопоставление типов данных
Типы данных JSON | Типы полей поиска ИИ Azure |
---|---|
Bool | Edm.Boolean, Edm.String |
Числа, которые выглядят как целые числа | Edm.Int32, Edm.Int64, Edm.String |
Числа, которые выглядят как числа с плавающей запятой | Edm.Double, Edm.String |
Строка | Edm.String |
Массивы примитивных типов, таких как ["a", "b", "c"] | Collection(Edm.String) |
Строки, которые выглядят как даты | Edm.DateTimeOffset, Edm.String |
Объекты GeoJSON, такие как { type: Point, "координаты": [long, lat] } | Edm.GeographyPoint |
Другие объекты JSON | Н/П |
Настройка и запуск индексатора Azure Cosmos DB для NoSQL
Когда индекс и источник данных уже созданы, можно создать индексатор. Конфигурация индексатора задает входные данные, параметры и свойства, управляющие поведением во время выполнения.
Создайте или обновите индексатор , предоставив ему имя и ссылаясь на источник данных и целевой индекс:
POST https://[service name].search.windows.net/indexers?api-version=2023-11-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 }
Укажите сопоставления полей, если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля.
Дополнительные сведения о других свойствах см. в статье "Создание индексатора ".
Индексатор запускается автоматически при его создании. Это можно предотвратить, задав для параметра "Отключено" значение true. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.
Проверка состояния индексатора
Чтобы отслеживать состояние индексатора и журнал выполнения, отправьте запрос состояния индексатора:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
Content-Type: application/json
api-key: [admin key]
Ответ включает состояние и количество обработанных элементов. Он должен выглядеть примерно так:
{
"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
]
}
Журнал выполнения содержит до 50 последних завершенных выполнений, которые сортируются в обратном хронологическом порядке, чтобы последнее выполнение было первым.
Индексирование новых и измененных документов
После полного заполнения индексатора поиска может потребоваться, чтобы последующий индексатор запускался для добавочного индекса только новых и измененных документов в базе данных.
Чтобы включить добавочное индексирование, задайте свойство dataChangeDetectionPolicy в определении источника данных. Это свойство сообщает индексатору, какой механизм отслеживания изменений используется для данных.
Для индексаторов Azure Cosmos DB только поддерживаемая политика — это HighWaterMarkChangeDetectionPolicy
_ts
свойство (метка времени), предоставленное Azure Cosmos DB.
В следующем примере показано определение источника данных с политикой обнаружения изменений:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
" highWaterMarkColumnName": "_ts"
},
Примечание.
При назначении null
значения полю в Azure Cosmos DB индексатор поиска ИИ не может различаться null
и отсутствующее значение поля. Таким образом, если поле в индексе пусто, оно не будет заменено null
значением, даже если это изменение было сделано в вашей базе данных.
Добавочное индексирование и пользовательские запросы
Если вы используете пользовательский запрос для получения документов, убедитесь, что запрос упорядочивает результаты по столбцу _ts
. Это позволяет периодически проверять, используется ли поиск ИИ Azure для обеспечения добавочного прогресса в присутствии сбоев.
В некоторых случаях, даже если запрос содержит ORDER BY [collection alias]._ts
предложение, поиск ИИ Azure может не определить порядок _ts
запроса. Вы можете сообщить Службе поиска ИИ Azure, что результаты упорядочены, задав assumeOrderByHighWaterMarkColumn
свойство конфигурации.
Чтобы указать это указание, создайте или обновите определение индексатора следующим образом:
{
... other indexer definition properties
"parameters" : {
"configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}
Индексация удаленных документов
Строки, удаляемые из исходной коллекции, вероятно, также следует удалить из индекса поиска. Политика обнаружения удаления данных предназначена для эффективного определения удаленных элементов данных. В настоящее время единственная поддерживаемая политика — Soft Delete
это политика (удаление помечается флагом определенного типа), которое указывается в определении источника данных следующим образом:
"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"
}
Если вы используете пользовательский запрос, убедитесь, что свойство, на которое softDeleteColumnName
ссылается ссылка, проецируется запросом.
Должно softDeleteColumnName
быть поле верхнего уровня в индексе. Использование вложенных полей в сложных типах данных, так как softDeleteColumnName
не поддерживается.
В следующем примере создается источник данных с политикой мягкого удаления:
POST https://[service name].search.windows.net/datasources?api-version=2023-11-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"
}
}
Использование .NET
Для доступа к данным через протокол API SQL можно использовать пакет SDK для .NET для автоматизации с помощью индексаторов. Мы рекомендуем ознакомиться с предыдущими разделами REST API, чтобы узнать о понятиях, рабочих процессах и требованиях. Затем можно обратиться к следующей справочной документации по API .NET, чтобы реализовать индексатор JSON в управляемом коде:
- azure.search.documents.indexes.models.searchindexerdatasourceconnection
- azure.search.documents.indexes.models.searchindexerdatasourcetype
- azure.search.documents.indexes.models.searchindex
- azure.search.documents.indexes.models.searchindexer
Следующие шаги
Теперь вы можете управлять запуском индексатора, отслеживания состояния или расписания выполнения индексатора. Следующие статьи относятся к индексаторам, которые извлекает содержимое из Azure Cosmos DB:
Кері байланыс
https://aka.ms/ContentUserFeedback.
Жақында қолжетімді болады: 2024 жыл бойы біз GitHub Issues жүйесін мазмұнға арналған кері байланыс механизмі ретінде біртіндеп қолданыстан шығарамыз және оны жаңа кері байланыс жүйесімен ауыстырамыз. Қосымша ақпаратты мұнда қараңыз:Жіберу және пікірді көру