Indexar dados do Azure Cosmos DB para Apache Gremlin para consultas no Pesquisa de IA do Azure (pré-visualização)

O indexador Azure Cosmos DB for Apache Gremlin (pré-visualização) importa conteúdo do Azure Cosmos DB para Apache Gremlin e torna-o pesquisável no Pesquisa de IA do Azure.

Este artigo complementa Criar um indexador com informação específica para o Cosmos DB. Utiliza as APIs REST para demonstrar um fluxo de trabalho em três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice, criar um indexador. A extração de dados ocorre quando submete o pedido Create Indexer.

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

Pré-requisitos

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

• Uma conta Azure Cosmos DB, base de dados, contentor e itens. Use a mesma região tanto para o Pesquisa de IA do Azure como para o Azure Cosmos DB para menor latência e para evitar cobranças de largura de banda.

• Uma política de indexação automática na coleção Azure Cosmos DB, definida para Consistente. Esta configuração é a padrão. Indexação preguiçosa não é recomendada e pode resultar em dados em falta.

• Ler permissões. Uma cadeia de conexão de "acesso total" inclui uma chave que concede acesso ao conteúdo, mas se estiveres a usar funções do Azure, certifica-te de que a identidade gerida do serviço de pesquisa tem permissões de Leitor de Conta do Cosmos DB.

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

Defina a fonte de dados

A definição da fonte de dados especifica os dados a 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 múltiplos indexadores.

Para esta chamada, especifique uma versão pré-visualizada da API REST para criar uma fonte de dados que se ligue via Azure Cosmos DB para Apache Gremlin. Podes usar 2021-04-01-preview ou mais tarde. Recomendamos a mais recente API REST de pré-visualização.

1. Crie ou atualize uma fonte de dados para definir a 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 "tipo" para "cosmosdb" (obrigatório).

3. Defina "credenciais" para uma string de conexão. A secção seguinte descreve os formatos suportados.

4. Defina "contentor" para a coleção. A propriedade "nome" é necessária e especifica o ID do grafo.

   A propriedade "query" é opcional. Por predefinição, o indexador do Pesquisa de IA do Azure para o Azure Cosmos DB for Apache Gremlin transforma cada vértice do grafo num documento no índice. As arestas são ignoradas. O padrão da consulta é g.V(). Alternativamente, pode definir a consulta para indexar apenas as arestas. Para indexar as arestas, configure a consulta para g.E().

5. Defina "dataChangeDetectionPolicy" se os seus dados estiverem voláteis e quiser que o indexador detete apenas os itens novos e atualizados nas execuções seguintes. O progresso incremental está ativado por predefinição, utilizando _ts como coluna de limite máximo.

6. Define "dataDeletionDetectionPolicy" se quiseres remover documentos de pesquisa de um índice de pesquisa quando o item de origem for eliminado.

Credenciais suportadas e cadeias de ligação

Os indexadores podem ligar-se a uma coleção usando as seguintes ligações. Para ligações que visam Azure Cosmos DB para Apache Gremlin, certifique-se de incluir "ApiKind" no cadeia de ligação.

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

Adicionar campos de pesquisa a um índice

Num índice de pesquisa, adicione campos para aceitar os documentos JSON de origem ou a saída da sua projeção personalizada de consulta. Certifique-se de que o esquema do índice de pesquisa é compatível com o seu gráfico. Para conteúdo no Azure Cosmos DB, o seu esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB na sua 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": verdadeiro). Para coleções particionadas, a chave padrão do documento é a propriedade Azure Cosmos DB _rid, que a Pesquisa de IA do Azure automaticamente renomeia para rid porque os nomes dos campos não podem começar por um sublinhado. Além disso, os valores de Azure Cosmos DB _rid contêm caracteres que são inválidos em chaves do Pesquisa de IA do Azure. Por esta razão, os _rid valores são codificados em Base64.

3. Crie campos adicionais para conteúdos mais pesquisáveis. Consulte Criar um índice para mais detalhes.

Mapeamento dos tipos de dados

Configure e execute o indexador Azure Cosmos DB

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

1. Crie ou atualize um indexador atribuindo-lhe um nome e referenciando a fonte de dados e o índice alvo:

   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 campos se existirem diferenças no nome ou tipo do campo, ou se precisar de múltiplas versões de um campo de origem no índice de pesquisa.

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

Um indexador corre automaticamente quando é criado. Podes evitar isto definindo "desabilitado" como verdadeiro. Para controlar a execução do indexador, execute um indexador a pedido ou coloque-o num calendário.

Verificar o estado do indexador

Para monitorizar o estado do indexador e o histórico de execução, envie um pedido Get Indexer Status :

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 estado e o número de itens processados. Deverá assemelhar-se ao seguinte exemplo:

    {
        "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ções contém até 50 das execuções mais recentemente concluídas, que estão ordenadas por ordem cronológica inversa para que a execução mais recente venha primeiro.

Indexação de documentos novos e alterados

Depois de um indexador preencher totalmente um índice de pesquisa, pode querer que execuções subsequentes indexem incrementalmente apenas os documentos novos e alterados na sua base de dados.

Para permitir a indexação incremental, defina a propriedade "dataChangeDetectionPolicy" na definição da sua fonte de dados. Esta propriedade indica ao indexador qual o mecanismo de acompanhamento de alterações utilizado nos seus dados.

Para Azure Cosmos DB indexadores, a única política suportada é a HighWaterMarkChangeDetectionPolicy usando a propriedade _ts (carimbo temporal) fornecida pela Azure Cosmos DB.

O exemplo seguinte mostra uma definição de fonte de dados com uma política de deteção de alterações:

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

Indexação de documentos apagados

Quando os dados do grafo são eliminados, pode querer eliminar o documento correspondente do índice de pesquisa também. O objetivo de uma política de deteção de eliminação de dados é identificar eficientemente os itens de dados eliminados e eliminar o documento completo do índice. A política de deteção de eliminação de dados não pretende eliminar informação parcial de documentos. Atualmente, a única política suportada é a Soft Delete política (a eliminação é marcada com algum tipo de flag), que é especificada na definição da fonte de dados da seguinte forma:

"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 seguinte cria uma fonte de dados com uma política de eliminação suave:

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 que ative a política de deteção de eliminação, não é suportado eliminar campos complexos (Edm.ComplexType) do índice. Esta política exige que a coluna 'ativa' na base de dados Gremlin seja do tipo inteiro, string ou booleana.

Mapear dados de grafos para campos num índice de pesquisa

O indexador Azure Cosmos DB for Apache Gremlin mapeia automaticamente alguns dados de grafo:

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

2. O indexador mapeia _id para um id campo no índice, se este existir.

3. Ao consultar a sua base de dados Azure Cosmos DB usando o Azure Cosmos DB for Apache Gremlin, poderá notar que a saída JSON de cada propriedade tem um id e um value. O indexador mapeia automaticamente as propriedades value para um campo no seu índice de pesquisa que tem o mesmo nome da propriedade, caso exista. No exemplo seguinte, 450 está 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"
            }
          ]
        }
    }

Pode descobrir que precisa de usar Mapeamentos de Campos de Saída para mapear a saída da sua consulta para os campos no seu índice. Provavelmente vais querer utilizar Mapeamentos de Campos de Saída em vez de Mapeamentos de Campos, já que a consulta personalizada provavelmente tem dados complexos.

Por exemplo, suponha que a sua consulta produz este resultado:

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

Se quiser mapear o valor de pages no JSON acima para um totalpages campo no seu índice, pode adicionar o seguinte Mapeamento de Campo de Saída à definição do seu indexador:

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

Note como o Mapeamento do Campo de Saída começa com /document e não inclui referência à chave de propriedades no JSON. Isto deve-se ao facto de o indexador colocar cada documento sob o nó /document durante a ingestão dos dados do grafo, e também permitir automaticamente que se faça referência ao valor de pages simplesmente referenciando pages, em vez de se ter de referenciar o primeiro objeto do array de pages.

Próximos passos

• Para saber mais sobre Azure Cosmos DB para Apache Gremlin, consulte o Introdução a Azure Cosmos DB: Azure Cosmos DB para Apache Gremlin.

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

• Para saber mais sobre a configuração de rede para indexadores, consulte o documento Indexer acesso a conteúdos protegidos por funcionalidades de segurança de rede do Azure.