Indexar dados do Azure Cosmos DB para MongoDB para consultas no Azure AI Search

Neste artigo, saiba como configurar um indexador que importa conteúdo do Azure Cosmos DB para MongoDB e o torna pesquisável no Azure AI Search.

Este artigo complementa o artigo 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, vale a pena observar que a indexação do Azure Cosmos DB e a indexação do Azure AI Search são operações diferentes. A indexação no Azure AI Search cria e carrega um índice de pesquisa em seu serviço de pesquisa.

Pré-requisitos

• Registre-se para a versão prévia para fornecer comentários sobre o cenário. Você pode acessar o recurso automaticamente após o envio do formulário.

• Uma conta, um banco de dados, uma coleção e documentos do Azure Cosmos DB. Use a mesma região para o Azure AI Search e o 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 do Azure Cosmos DB, definida como Consistente. Essa é 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

Estas são as limitações desse recurso:

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

• O nome da coluna _ts é 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 Azure AI Search como coletor.

Definir a fonte de dados

A definição da fonte de dados especifica os dados a serem indexados, as credenciais e as 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 esta chamada, especifique uma versão prévia da API REST. Você pode usar 2020-06-30-versão prévia ou posterior para criar uma fonte de dados que se conecta por meio da API MongoDB. Recomendamos a API REST de visualização mais recente.

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

   POST https://[service name].search.windows.net/datasources?api-version=2024-05-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]",
       "query": null
     },
     "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 a cadeia de conexão. A próxima seção descreve os formatos compatíveis.

4. Defina "container" como a coleção. A propriedade "name" é necessária e especifica a ID da coleção de banco de dados a ser indexada. Para o Azure Cosmos DB for MongoDB, não há suporte para "consulta".

5. Defina "dataChangeDetectionPolicy" se os dados forem voláteis e você quiser que o indexador selecione apenas os itens novos e atualizados nas execuções seguintes.

6. Defina "dataDeletionDetectionPolicy" se desejar 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 do MongoDB, inclua "ApiKind" na cadeia de conexão.

Evite usar 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 o conteúdo no Azure Cosmos DB, o esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB na fonte de dados.

1. Crie ou atualize um índice para definir os campos de pesquisa que armazenarão os dados:

   POST https://[service name].search.windows.net/indexes?api-version=2024-05-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 do documento ("key": true). Em 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 contém valores exclusivos. Como os nomes dos campos e os tipos de dados são os mesmos nos dois lados, não é necessário nenhum mapeamento de campo.

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

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

   • Em outros campos, seu campo de pesquisa deve ter o mesmo nome definido na coleção.

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

Mapeamento de tipos de dados

Configurar e executar o indexador do Azure Cosmos DB para MongoDB

Uma vez que o índice e a fonte de dados forem criados, será possível 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 um nome a ele e referenciando a fonte de dados e o índice de destino:

   POST https://[service name].search.windows.net/indexers?api-version=2024-05-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. Confira Criar um indexador para obter mais informações sobre outras propriedades.

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

Checar o status do indexador

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

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

A resposta inclui o status e o número de itens processados. Ela deve ser parecida com o 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 execuções mais recentes, classificadas em ordem cronológica inversa, de modo que a execução mais recente apareça em primeiro lugar.

Como indexar documentos novos e alterados

Depois que um indexador preencher completamente um índice de pesquisa, o ideal será que o indexador seguinte seja executado para indexar de maneira incremental apenas os documentos novos e alterados no banco de dados.

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

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

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

"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 excluí-las do índice de pesquisa. A finalidade de uma política de detecção de exclusão de dados é identificar de maneira eficaz dados excluídos. Atualmente, a única política com suporte é a política Soft Delete (a exclusão recebe algum tipo de marcador), que é especificada na definição de 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"
}

Se você estiver usando uma consulta personalizada, garanta que a propriedade referenciada por softDeleteColumnName seja projetada pela consulta.

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

POST https://[service name].search.windows.net/datasources?api-version=2024-05-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

Você já pode controlar como executar o indexador, monitorar o status ou agendar a execução do indexador. Os seguintes artigos se aplicam aos indexadores que efetuam pull do conteúdo do Azure Cosmos DB:

• Configurar uma conexão do indexador a um banco de dados do 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