Индексирование данных из Azure Cosmos DB для Apache Gremlin для запросов в Поиск с использованием ИИ Azure (предварительная версия)

Azure Cosmos DB для индексатора Apache Gremlin (предварительная версия) импортирует содержимое из Azure Cosmos DB для Apache Gremlin и делает его доступным для поиска в Поиск с использованием ИИ Azure.

Эта статья дополняет Создание индексатора информацией, относящейся к Cosmos DB. В нем используются ИНТЕРФЕЙСы REST API для демонстрации трех частей рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.

Поскольку терминология может быть запутана, стоит отметить, что Azure Cosmos DB индексирование и Поиск с использованием ИИ Azure индексирование являются разными операциями. Индексирование в Поиск с использованием ИИ Azure создает и загружает индекс поиска в службе поиска.

Необходимые условия

• Заполните форму регистрации индексатора предварительной версии. Регистрация автоматически утверждена.

• Учетная запись Azure Cosmos DB, база данных, контейнер и элементы. Используйте один и тот же регион для Поиск с использованием ИИ Azure и Azure Cosmos DB для снижения задержки и предотвращения расходов на пропускную способность.

• Политика индексирования автоматическая в коллекции Azure Cosmos DB, установлено на Consistent. Этот параметр является конфигурацией по умолчанию. Отложенное индексирование не рекомендуется и может привести к отсутствием данных.

• Разрешения на чтение. Connection string "полный доступ" включает ключ, предоставляющий доступ к содержимому, но если вы используете роли Azure, убедитесь, что у управляемой идентичности службы search service есть разрешение на роль Читатель учетных записей Cosmos DB.

• Клиент REST для создания источника данных, индекса и индексатора.

Определение источника данных

Определение источника данных указывает данные для индексирования, учетных данных и политик для выявления изменений в данных. Источник данных определяется как независимый ресурс, чтобы его можно было использовать несколькими индексаторами.

Для этого вызова укажите предварительную версию REST API, чтобы создать источник данных, который подключается через Azure Cosmos DB для Apache Gremlin. Вы можете использовать 2021-04-01-preview или более позднюю версию. Рекомендуется использовать последнюю предварительную версию REST API.

1. Создайте или обновите источник данных , чтобы задать его определение:

    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. Установите «type» на "cosmosdb" (обязательно).

3. Установите "учетные данные" в строку подключения. В следующем разделе описаны поддерживаемые форматы.

4. Задайте для коллекции значение container. Свойство "name" требуется, и оно указывает идентификатор графа.

   Свойство query является необязательным. По умолчанию индексатор Поиск с использованием ИИ Azure для Azure Cosmos DB для Apache Gremlin делает каждую вершину в графе документом в индексе. Края игнорируются. По умолчанию используется g.V()запрос. В качестве альтернативы можно настроить запрос так, чтобы индексировались только рёбра. Чтобы индексировать края, задайте для запроса значение g.E().

5. Задайте значение dataChangeDetectionPolicy , если данные являются переменными, и индексатор будет получать только новые и обновленные элементы при последующих запусках. По умолчанию инкрементальное выполнение включено; в качестве столбца маркера верхней границы используется _ts.

6. Установите параметр dataDeletionDetectionPolicy, если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента.

Поддерживаемые учетные данные и строки подключения

Индексаторы могут подключаться к коллекции с помощью следующих подключений. Для подключений, предназначенных для Azure Cosmos DB для Apache Gremlin, обязательно включите "ApiKind" в строку подключения.

Избегайте номеров портов в URL-адресе конечной точки. Если включить номер порта, подключение завершается ошибкой.

Добавление полей поиска в индекс

В индексе поиска добавьте поля, чтобы принять исходные документы JSON или выходные данные пользовательской проекции запроса. Убедитесь, что схема индекса поиска совместима с графом. Для содержимого в Azure Cosmos DB схема индекса поиска должна соответствовать элементам Azure Cosmos DB в источнике данных.

1. Создайте или обновите индекс , чтобы определить поля поиска, в которые хранятся данные:

    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. Создайте поле ключа документа ("key": true"). Для секционированных коллекций ключ документа по умолчанию — это свойство Azure Cosmos DB _rid, которое Поиск с использованием ИИ Azure автоматически переименовывается в rid, так как имена полей не могут начинаться с символа подчеркивания. Кроме того, значения Azure Cosmos DB _rid содержат символы, недопустимые в Поиск с использованием ИИ Azure ключах. По этой причине _rid значения кодируются в кодировке Base64.

3. Создайте дополнительные поля для более удобного для поиска содержимого. См. статью "Создание индекса" для получения дополнительных сведений.

Сопоставление типов данных

Настройка и запуск индексатора Azure Cosmos DB

После создания индекса и источника данных вы будете готовы к созданию индексатора. Конфигурация индексатора задает входные данные, параметры и свойства, управляющие поведением во время выполнения.

1. Создайте или обновите индексатор , предоставив ему имя и ссылаясь на источник данных и целевой индекс:

   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. Укажите сопоставления полей , если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля.

3. Дополнительные сведения о других свойствах см. в статье "Создание индексатора ".

Индексатор запускается автоматически при его создании. Это можно предотвратить, задав для параметра "Отключено" значение true. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.

Проверка состояния индексатора

Чтобы отслеживать состояние индексатора и журнал выполнения, отправьте запрос получения состояния индексатора:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  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"
},

Индексирование удаленных документов

При удалении данных графа может потребоваться также удалить соответствующий документ из индекса поиска. Целью политики обнаружения удаления данных является эффективное определение удаленных элементов данных и удаление полного документа из индекса. Политика обнаружения удаления данных не предназначена для удаления сведений о частичном документе. В настоящее время единственная поддерживаемая политика — политика 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"
}

В следующем примере создается источник данных с политикой обратимого удаления:

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

Даже если включить политику обнаружения удаления, удаление сложных (Edm.ComplexType) полей из индекса не поддерживается. Эта политика требует, чтобы столбец "активный" в базе данных Gremlin был целочисленным, строковым или логическим.

Сопоставление данных графа с полями в индексе поиска

Azure Cosmos DB для индексатора Apache Gremlin автоматически сопоставляет несколько фрагментов данных графа:

1. Индексатор сопоставляет _rid с полем rid в индексе, если оно существует, и кодирует его в формате Base64.

2. Индексатор сопоставляет _id с полем id в индексе, если оно существует.

3. При выполнении запроса к базе данных Azure Cosmos DB с помощью Azure Cosmos DB для Apache Gremlin можно заметить, что в выходных данных JSON для каждого свойства содержатся id и value. Индексатор автоматически сопоставляет свойство value с полем в индексе поиска, которое имеет то же имя, что и свойство, если оно существует. В следующем примере 450 сопоставляется с pages полем в индексе поиска.

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

Возможно, вам потребуется использовать сопоставления полей вывода для сопоставления выходных данных запроса с полями в индексе. Скорее всего, вам стоит использовать сопоставления выходных полей, а не сопоставления полей, так как настраиваемый запрос, скорее всего, содержит сложные данные.

Например, предположим, что запрос создает эти выходные данные:

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

Если вы хотите сопоставить значение pages в формате JSON выше с totalpages полем в индексе, можно добавить следующее сопоставление полей вывода в определение индексатора:

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

Сопоставление полей вывода начинается с /document и не содержит ссылку на ключ свойств в JSON. Это связано с тем, что индексатор помещает каждый документ под узел /document при приеме данных графа, и индексатор также автоматически позволяет ссылаться на значение pages посредством простого использования ссылки pages вместо того, чтобы ссылаться на первый объект массива pages.

Дальнейшие действия

• Дополнительные сведения о Azure Cosmos DB для Apache Gremlin см. в статье Introduction to Azure Cosmos DB: Azure Cosmos DB для Apache Gremlin.

• Дополнительные сведения о сценариях и ценах Поиск с использованием ИИ Azure см. на странице службы Search на azure.microsoft.com.

• Сведения о конфигурации сетевого доступа для индексаторов см. статью Indexer access to content protected by Azure network security features.