Partilhar via

Dados de índice do Azure Cosmos DB para NoSQL para consultas no Azure AI Search

  • Artigo

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

Este artigo complementa Criar um indexador com informações específicas do Cosmos DB. Ele usa o portal do Azure e 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, 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 na Pesquisa de IA do Azure cria e carrega um índice de pesquisa no seu serviço de pesquisa.

Pré-requisitos

  • Uma conta, banco de dados, contêiner e itens do Azure Cosmos DB. Use a mesma região para o Azure AI Search e o Azure Cosmos DB para obter latência mais baixa e evitar cobranças de largura de banda.

  • Uma política de indexação automática na coleção do Azure Cosmos DB, definida como Consistente. Esta é a configuração predefinida. A indexação lenta não é recomendada e pode resultar na falta de dados.

  • Permissões de leitura. Uma cadeia de conexão de "acesso total" inclui uma chave que concede acesso ao conteúdo, mas se você estiver usando identidades (ID do Microsoft Entra), verifique se a identidade gerenciada pelo serviço de pesquisa está atribuída à Função de Leitor de Conta do Cosmos DB e à Função de Leitor de Dados Interno do Cosmos DB.

Para trabalhar com os exemplos neste artigo, você precisa do portal do Azure ou de um cliente REST. Se estiver a utilizar o portal do Azure, certifique-se de que o acesso a todas as redes públicas está ativado. Outras abordagens para criar um indexador do Cosmos DB incluem SDKs do Azure.

Tente com dados de exemplo

Use estas instruções para criar um contêiner e um banco de dados no Cosmos DB para fins de teste.

  1. Baixe HotelsData_toCosmosDB.JSON do GitHub para criar um contêiner no Cosmos DB que contenha um subconjunto do conjunto de dados de hotéis de exemplo.

  2. Entre no portal do Azure e crie uma conta, um banco de dados e um contêiner no Cosmos DB.

  3. No Cosmos DB, selecione Data Explorer para o novo contêiner, forneça os seguintes valores.

    Property valor
    Base de Dados Criar nova
    ID da Base de Dados HotelsDB
    Compartilhar taxa de transferência entre contêineres Não selecione
    ID do Contentor hotéis
    Chave de partição /HotelId
    Taxa de transferência do contêiner (dimensionamento automático) Dimensionamento Automático
    Contentor Max RU/s 1000

  4. No Data Explorer, expanda hotelsdb e *hotels" e selecione Itens.

  5. Selecione Carregar item e, em seguida, selecione HotelsData_toCosmosDB.JSON arquivo que você baixou do GitHub.

  6. Clique com o botão direito do mouse em Itens e selecione Nova consulta SQL. A consulta padrão é SELECT * FROM c.

  7. Selecione Executar consulta para executar a consulta e exibir os resultados. Você deve ter 50 documentos do hotel.

Agora que você tem um contêiner, pode usar o portal do Azure, o cliente REST ou um SDK do Azure para indexar seus dados.

O campo Descrição fornece o conteúdo mais detalhado. Você deve direcionar este campo para pesquisa de texto completo e consultas vetoriais opcionais.

Utilizar o portal do Azure

Você pode usar o assistente Importar dados ou o assistente Importar e vetorizar dados para automatizar a indexação a partir de uma tabela ou exibição de banco de dados SQL. A configuração da fonte de dados é semelhante para ambos os assistentes.

  1. Iniciar o assistente.

  2. Em Conectar-se aos seus dados, selecione ou verifique se o tipo de fonte de dados é o Azure Cosmos DB ou uma conta NoSQL.

    O nome da fonte de dados refere-se ao objeto de conexão da fonte de dados no Azure AI Search. Se você usar o assistente de vetor, o nome da fonte de dados será gerado automaticamente usando um prefixo personalizado especificado no final do fluxo de trabalho do assistente.

  3. Especifique o nome e a coleção do banco de dados. A consulta é opcional. É útil se você tiver dados hierárquicos e quiser importar uma fatia específica.

  4. Especifique um método de autenticação, seja uma identidade gerenciada ou uma chave de API interna. Se você não especificar uma conexão de identidade gerenciada, o portal do Azure usará a chave.

    Se você configurar a Pesquisa de IA do Azure para usar uma identidade gerenciada e criar uma atribuição de função no Cosmos DB que conceda permissões de Leitor de Conta do Cosmos DB e Leitor de Dados Interno do Cosmos DB à identidade, seu indexador poderá se conectar ao Cosmos DB usando a ID e as funções do Microsoft Entra.

  5. Para o assistente Importar e vetorizar dados , você pode especificar opções para controle de alterações e exclusões.

    A deteção de alterações é suportada por padrão por meio de um campo (carimbo de _ts data/hora). Se você carregar conteúdo usando a abordagem descrita em Experimentar com dados de exemplo, a coleção será criada com um _ts campo.

    A deteção de exclusão requer que você tenha um campo de nível superior pré-existente na coleção que possa ser usado como um sinalizador de exclusão suave. Deve ser um campo booleano (você pode nomeá-lo IsDeleted). Especifique true como o valor soft-delete. No índice de pesquisa, adicione um campo de pesquisa correspondente chamado IsDeleted definido como recuperável e filtrável.

  6. Continue com as etapas restantes para concluir o assistente:

Utilizar APIs REST

Esta seção demonstra as chamadas de API REST que criam uma fonte de dados, um índice e um indexador.

Definir a fonte de dados

A definição da fonte de dados especifica os dados a serem indexados, credenciais e políticas para identificar alterações nos dados. Uma fonte de dados é um recurso independente que pode ser usado por vários indexadores.

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

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
      "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": {
      "name": "[my-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). Se você estiver usando uma versão mais antiga da API de Pesquisa 2017-11-11, a sintaxe para "tipo" é "documentdb". Caso contrário, para 2019-05-06 e posteriores, use "cosmosdb".

  3. Defina "credenciais" como uma cadeia de conexão. A próxima seção descreve os formatos suportados.

  4. Defina "container" para a coleção. A propriedade "name" é necessária e especifica a ID da coleção de banco de dados a ser indexada. A propriedade "query" é opcional. Use-o para nivelar um documento JSON arbitrário em um esquema simples que o Azure AI Search pode indexar.

  5. Defina "dataChangeDetectionPolicy" se os dados forem voláteis e você quiser que o indexador pegue apenas os itens novos e atualizados em 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 suportadas

Os indexadores podem se conectar a uma coleção usando as seguintes conexões.

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

Cadeia de conexão de acesso total
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }`
Você pode obter a cadeia de conexão na página da conta do Azure Cosmos DB no portal do Azure selecionando Chaves no painel de navegação esquerdo. Certifique-se de selecionar uma cadeia de conexão completa e não apenas uma chave.
Cadeia de conexão de identidade gerenciada
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }
Essa cadeia de conexão não requer uma chave de conta, mas você deve ter um serviço de pesquisa que possa se conectar usando uma identidade gerenciada. Para conexões destinadas à API SQL, você pode omitir ApiKind da cadeia de conexão. Para obter mais informações sobre ApiKindo , IdentityAuthType consulte Configurando uma conexão de indexador com um banco de dados do Azure Cosmos DB usando uma identidade gerenciada.

Usando consultas para dar forma a dados indexados

Na propriedade "query" em "container", você pode especificar uma consulta SQL para nivelar propriedades ou matrizes aninhadas, projetar propriedades JSON e filtrar os dados a serem indexados.

Exemplo de documento:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Filtrar consulta:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Nivelamento da consulta:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Consulta de projeção:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Consulta de nivelamento de matriz:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Consultas não suportadas (DISTINCT e GROUP BY)

Não há suporte para consultas que usam a palavra-chave DISTINCT ou a cláusula GROUP BY. O Azure AI Search depende da paginação da consulta SQL para enumerar totalmente os resultados da consulta. Nem a palavra-chave DISTINCT nem as cláusulas GROUP BY são compatíveis com os tokens de continuação usados para paginar os resultados.

Exemplos de consultas sem suporte:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Embora o Azure Cosmos DB tenha uma solução alternativa para dar suporte à paginação de consulta SQL com a palavra-chave DISTINCT usando a cláusula ORDER BY, ela não é compatível com o Azure AI Search. A consulta retorna um único valor JSON, enquanto o Azure AI Search espera um objeto JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

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 de sua projeção de consulta personalizada. Verifique se o esquema de índice de pesquisa é compatível com os dados de origem. Para conteúdo no Azure Cosmos DB, seu esquema de índice de pesquisa deve corresponder aos itens do Azure Cosmos DB em 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=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": 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 coleções particionadas, a chave de documento padrão é a propriedade do Azure Cosmos DB _rid , para a qual o Azure AI Search renomeia automaticamente porque rid 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 que são inválidos nas chaves do Azure AI Search. Por esta razão, os _rid valores são codificados em Base64.

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

Mapeando tipos de dados

Tipos de dados JSON Tipos de campo do Azure AI Search
Bool Edm.Booleano, Edm.String
Números que se parecem com números inteiros Edm.Int32, Edm.Int64, Edm.String
Números que se parecem com pontos flutuantes Edm.Double, Edm.String
String Edm.String
Matrizes de tipos primitivos como ["a", "b", "c"] Collection(Edm.String)
Cadeias de caracteres que se parecem com datas Edm.DateTimeOffset, Edm.String
Objetos GeoJSON como { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPoint
Outros objetos JSON N/A

Configurar e executar o indexador do Azure Cosmos DB para NoSQL

Depois que o índice e a fonte de dados forem criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, parâmetros e 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=2024-07-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-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 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 evitar isso definindo "desativado" como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em uma programação.

Verificar o estado do indexador

Para monitorar o status do indexador e o histórico de execução, verifique o histórico de execução do indexador no portal do Azure ou envie uma solicitação de API REST Get Indexer Status

  1. Na página do serviço de pesquisa, abra Indexadores de gerenciamento de>pesquisa.

  2. Selecione um indexador para acessar o histórico de configuração e execução.

  3. Selecione um trabalho de indexador específico para exibir detalhes, avisos e erros.

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.

Indexação de documentos novos e alterados

Depois que um indexador tiver preenchido totalmente um índice de pesquisa, talvez você queira que as execuções subsequentes do indexador indexem 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, a única política com suporte é o HighWaterMarkChangeDetectionPolicy uso da propriedade (carimbo _ts 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 deteção de alterações:

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

Nota

Quando você atribui um null valor a um campo no Azure Cosmos DB, o indexador AI Search não consegue distinguir entre null um valor de campo ausente. Portanto, se um campo no índice estiver vazio, ele não será substituído por um null valor, mesmo que essa modificação tenha sido feita especificamente em seu banco de dados.

Indexação incremental e consultas personalizadas

Se estiver a utilizar uma consulta personalizada para recuperar documentos, certifique-se de que a consulta ordena os resultados pela _ts coluna. Isso permite o ponto de verificação periódico que o Azure AI Search usa para fornecer progresso incremental na presença de falhas.

Em alguns casos, mesmo que sua consulta contenha uma ORDER BY [collection alias]._ts cláusula, o _tsAzure AI Search pode não inferir que a consulta é ordenada pelo . Você pode dizer ao Azure AI Search que os resultados são ordenados definindo a assumeOrderByHighWaterMarkColumn propriedade de configuração.

Para especificar essa dica, crie ou atualize sua definição de indexador da seguinte maneira:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Indexação de documentos eliminados

Quando as linhas são excluídas da coleção, normalmente você também deseja excluir essas linhas do índice de pesquisa. O objetivo de uma política de deteção de exclusão de dados é identificar com eficiência os itens de dados excluídos. Atualmente, a única política suportada é a Soft Delete política (a exclusão é marcada com um sinalizador de algum tipo), 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, verifique se a propriedade referenciada por é projetada pela softDeleteColumnName consulta.

O softDeleteColumnName deve ser um campo de nível superior no índice. O uso de campos aninhados em tipos de dados complexos não softDeleteColumnName é suportado.

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

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]

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

Utilizar .NET

Para dados acessados por meio do protocolo de API SQL, você pode usar o SDK do .NET para automatizar com indexadores. Recomendamos que você revise as seções anteriores da API REST para aprender conceitos, fluxo de trabalho e requisitos. Em seguida, consulte a seguinte documentação de referência da API .NET para implementar um indexador JSON no código gerenciado:

Próximos passos

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 do Azure Cosmos DB: