Indexar dados de Azure Cosmos DB do Apache Gremlin para consultas em Pesquisa de IA do Azure  (versão prévia)

O Azure Cosmos DB do indexador Apache Gremlin (versão prévia) importa conteúdo de Azure Cosmos DB para Apache Gremlin e o torna pesquisável em Pesquisa de IA do Azure .

Este artigo complementa Criar um indexador com informações específicas do Cosmos DB. Ele usa as APIs REST para demonstrar um fluxo de trabalho de três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice e criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar Indexador.

Como a terminologia pode ser confusa, é importante observar que a indexação do Azure Cosmos DB e a indexação do Pesquisa de IA do Azure  são operações diferentes. A indexação em Pesquisa de IA do Azure  cria e carrega um índice de pesquisa em seu serviço de pesquisa.

Pré-requisitos

• Preencha o formulário de registro de visualização do indexador. O registro é aprovado automaticamente.

• Uma conta Azure Cosmos DB, banco de dados, contêiner e itens. Use a mesma região para Pesquisa de IA do Azure  e Azure Cosmos DB para menor latência e para evitar encargos de largura de banda.

• Uma política de indexação automática na coleção Azure Cosmos DB, definida como Consistent. Essa configuração é a configuração padrão. A indexação lenta não é recomendada e pode resultar em dados ausentes.

• Permissões de leitura. Uma cadeia de conexão de "acesso completo" inclui uma chave que permite acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem as permissões Função de Leitor da Conta do Cosmos DB.

• Um cliente REST para criar a fonte de dados, o índice e o indexador.

Definir a fonte de dados

A definição da fonte de dados especifica os dados para indexar, credenciais e políticas para identificar alterações nos dados. Uma fonte de dados é definida como um recurso independente para que possa ser usada por vários indexadores.

Para essa chamada, especifique uma versão prévia da API REST para criar uma fonte de dados que se conecta por meio de Azure Cosmos DB para Apache Gremlin. Você pode usar 2021-04-01-preview ou versão posterior. Recomendamos a API REST de versão prévia mais recente.

1. Crie ou atualize uma fonte de dados para definir sua definição:

    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. Defina "type" como "cosmosdb" (obrigatório).

3. Defina "credentials" como "cadeia de conexão". A próxima seção descreve os formatos com suporte.

4. Defina "contêiner" para a coleção. A propriedade "name" é necessária e especifica a ID do grafo.

   A propriedade "query" é opcional. Por padrão, o indexador de Pesquisa de IA do Azure  para Azure Cosmos DB para Apache Gremlin torna cada vértice no grafo um documento no índice. As bordas são ignoradas. O padrão da consulta é g.V(). Como alternativa, você pode definir a consulta para indexar apenas as bordas. Para indexar as bordas, defina a consulta como g.E().

5. Defina "dataChangeDetectionPolicy" se os dados forem voláteis e você quiser que o indexador pegue apenas os itens novos e atualizados nas execuções subsequentes. O progresso incremental é habilitado por padrão usando _ts como a coluna de marca d' água alta.

6. Defina "dataDeletionDetectionPolicy" se quiser remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.

Credenciais e cadeias de conexão com suporte

Os indexadores podem se conectar a uma coleção usando as conexões a seguir. Para conexões que têm como alvo o Azure Cosmos DB para Apache Gremlin, inclua "ApiKind" na cadeia de conexão.

Evite números de porta na URL do ponto de extremidade. Se você incluir o número da porta, a conexão falhará.

Adicionar campos de pesquisa a um índice

Em um índice de pesquisa, adicione campos para aceitar os documentos JSON de origem ou a saída da projeção de consulta personalizada. Verifique se o esquema de índice de pesquisa é compatível com o grafo. Para obter conteúdo em Azure Cosmos DB, o esquema de índice de pesquisa deve corresponder aos itens Azure Cosmos DB na fonte de dados.

1. Crie ou atualize um índice para definir campos de pesquisa que armazenam dados:

    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. Crie um campo de chave de documento ("chave": true). Para coleções particionadas, a chave de documento padrão é a propriedade Azure Cosmos DB _rid, que Pesquisa de IA do Azure  renomeia automaticamente para rid porque os nomes de campo não podem começar com um caractere de sublinhado. Além disso, os valores do Azure Cosmos DB _rid contêm caracteres inválidos nas chaves do Pesquisa de IA do Azure . Por esse motivo, os _rid valores são codificados em Base64.

3. Crie campos adicionais para obter mais conteúdo pesquisável. Consulte Criar um índice para obter detalhes.

Mapeamento de tipos de dados

Configurar e executar o indexador Azure Cosmos DB

Depois que o índice e a fonte de dados tiverem sido criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, os parâmetros e as propriedades que controlam os comportamentos de tempo de execução.

1. Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao índice de destino:

   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. Especifique mapeamentos de campo se houver diferenças no nome ou tipo de campo ou se você precisar de várias versões de um campo de origem no índice de pesquisa.

3. Consulte Criar um indexador para obter mais informações sobre outras propriedades.

Um indexador é executado automaticamente quando é criado. Você pode impedir isso definindo "desabilitado" como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em um agendamento.

Verificar o status do indexador

Para monitorar o status do indexador e o histórico de execução, envie uma solicitação Obter Status do Indexador :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-01-preview
  Content-Type: application/json  
  api-key: [admin key]

A resposta inclui o status e o número de itens processados. Ele deve ser semelhante ao exemplo a seguir:

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

O histórico de execução contém até 50 das execuções concluídas mais recentemente, que são classificadas na ordem cronológica inversa para que a execução mais recente venha primeiro.

Indexando documentos novos e alterados

Depois que um indexador preencher totalmente um índice de pesquisa, talvez você queira que o indexador subsequente seja executado para indexar incrementalmente apenas os documentos novos e alterados em seu banco de dados.

Para habilitar a indexação incremental, defina a propriedade "dataChangeDetectionPolicy" na definição da fonte de dados. Essa propriedade informa ao indexador qual mecanismo de controle de alterações é usado em seus dados.

Para indexadores do Azure Cosmos DB, única política com suporte é HighWaterMarkChangeDetectionPolicy usando a propriedade _ts (carimbo de data/hora) fornecida pelo Azure Cosmos DB.

O exemplo a seguir mostra uma definição de fonte de dados com uma política de detecção de alterações:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
},

Indexando documentos excluídos

Quando os dados do grafo são excluídos, talvez você queira excluir seu documento correspondente do índice de pesquisa também. A finalidade de uma política de detecção de exclusão de dados é identificar com eficiência os itens de dados excluídos e excluir o documento completo do índice. A política de detecção de exclusão de dados não se destina a excluir informações parciais do documento. Atualmente, a única política com suporte é a política Soft Delete (a exclusão é marcada por algum tipo de sinalizador), que é especificada na definição da fonte de dados da seguinte maneira:

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

O exemplo a seguir cria uma fonte de dados com uma política de exclusão reversível:

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

Mesmo se você habilitar a política de detecção de exclusão, não há suporte para a exclusão de campos complexos (Edm.ComplexType) do índice. Essa política exige que a coluna 'ativa' no banco de dados Gremlin seja de tipo inteiro, cadeia de caracteres ou booliano.

Mapeando dados em grafos nos campos de um índice de pesquisa

O indexador Azure Cosmos DB para Apache Gremlin mapeia automaticamente algumas partes dos dados do grafo:

1. O indexador mapeia _rid para um rid campo no índice se ele existir e o Base64 o codifica.

2. O indexador mapeia _id para um campo id no índice, caso exista.

3. Ao consultar seu banco de dados Azure Cosmos DB usando o Azure Cosmos DB para Apache Gremlin, você pode observar que a saída JSON para cada propriedade tem um id e um value. O indexador mapeia automaticamente a propriedade value para um campo no índice de pesquisa que tem o mesmo nome da propriedade, se existir. No exemplo a seguir, 450 é mapeado para um pages campo no índice de pesquisa.

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

Você pode descobrir que precisa usar mapeamentos de campo de saída para mapear a saída da consulta para os campos em seu índice. Você provavelmente desejará usar mapeamentos de campo de saída em vez de mapeamentos de campo , já que a consulta personalizada provavelmente tem dados complexos.

Por exemplo, digamos que sua consulta produza esta saída:

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

Se você quiser mapear o valor de pages no JSON acima para um totalpages campo em seu índice, poderá adicionar o seguinte mapeamento de campo de saída à sua definição de indexador:

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

Observe como o Mapeamento de Campo de Saída começa /document e não inclui uma referência à chave de propriedades no JSON. Isso ocorre porque o indexador coloca cada documento sob o nó /document ao ingerir os dados do gráfico e o indexador também permite que você faça referência automática ao valor de pages simplesmente referenciando pages em vez de ter que referenciar o primeiro objeto na matriz de pages.

Próximas etapas

• Para saber mais sobre Azure Cosmos DB para Apache Gremlin, consulte o Introduction to Azure Cosmos DB: Azure Cosmos DB for Apache Gremlin.

• Para obter mais informações sobre Pesquisa de IA do Azure  cenários e preços, consulte a página de serviço Search no azure.microsoft.com.

• Para saber mais sobre a configuração de rede para indexadores, consulte o acesso dos indexadores ao conteúdo protegido por recursos de segurança de rede do Azure.