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

O Azure Cosmos DB do indexador do MongoDB (versão prévia) importa conteúdo de Azure Cosmos DB para MongoDB 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, coleção e documentos. 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.

Limitações

Essas são as limitações deste recurso:

• Não há suporte para consultas personalizadas para especificar o conjunto de dados.

• O nome _ts da coluna é uma palavra reservada. Se você precisar desse campo, considere soluções alternativas para preencher um índice.

• O atributo $ref MongoDB é uma palavra reservada. Se você precisar disso em sua coleção do MongoDB, considere soluções alternativas para preencher um índice.

Como alternativa a esse conector, se o cenário tiver algum desses requisitos, você poderá usar a API/SDK por Push ou considerar Azure Data Factory com um índice do Pesquisa de IA do Azure  como coletor.

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 da API do MongoDB. Você pode usar 2020-06-30-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-mongodb-ds]",
     "type": "cosmosdb",
     "credentials": {
       "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
     },
     "container": {
       "name": "[cosmos-db-collection]"
     },
     "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 da coleção de banco de dados a ser indexada. Para Azure Cosmos DB para MongoDB, não há suporte para "consulta".

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.

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 direcionadas à API MongoDB, inclua "ApiKind" no 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 os dados de origem. 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": "doc_id",
           "type": "Edm.String",
           "key": true,
           "retrievable": true,
           "searchable": false
       }, {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }]
   }
   

2. Crie um campo de chave de documento ("chave": true). Para um índice de pesquisa baseado em uma coleção do MongoDB, a chave do documento pode ser "doc_id", "rid" ou algum outro campo de cadeia de caracteres que contenha valores exclusivos. Desde que nomes de campo e tipos de dados sejam iguais em ambos os lados, nenhum mapeamento de campo é necessário.

   • "doc_id" representa "_id" para o identificador de objeto. Se você especificar um campo de "doc_id" no índice, o indexador o preencherá com os valores do identificador de objeto.

   • "rid" é uma propriedade do sistema em Azure Cosmos DB. Se você especificar um campo de "rid" no índice, o indexador o preencherá com o valor codificado em base64 da propriedade "rid".

   • Para qualquer outro campo, seu campo de pesquisa deve ter o mesmo nome definido na coleção.

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 Azure Cosmos DB para o indexador do MongoDB

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-mongodb-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 as linhas são excluídas da coleção, normalmente, você também deseja excluir essas linhas do índice de pesquisa. A finalidade de uma política de detecção de exclusão de dados é identificar com eficiência itens de dados excluídos. 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"
}

Se você estiver usando uma consulta personalizada, certifique-se de que a propriedade referenciada por softDeleteColumnName esteja projetada na consulta.

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-mongodb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb"
    },
    "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"
    }
}

Próximas etapas

Agora você pode controlar como executar o indexador, monitorar o status ou agendar a execução do indexador. Os seguintes artigos se aplicam a indexadores que extraem conteúdo de Azure Cosmos DB:

• Conseje uma conexão de indexador com um banco de dados Azure Cosmos DB usando uma identidade gerenciada
• Indexar conjuntos de dados grandes
• Acesso do Indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure