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

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 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 o RBAC do Azure (ID do Microsoft Entra), verifique se a identidade gerenciada do 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.

• 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 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, envie uma solicitação Obter Status do Indexador:

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

A resposta inclui o status e o número de itens processados. Deve ser semelhante 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çã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, pois não há suporte para o uso de softDeleteColumnName campos aninhados.

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:

• azure.search.documents.indexes.models.searchindexerdatasourceconnection
• azure.search.documents.indexes.models.searchindexerdatasourcetype
• azure.search.documents.indexes.models.searchindex
• azure.search.documents.indexes.models.searchindexer

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:

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