Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Neste artigo, saiba como configurar um indexador que importa conteúdo do Banco de Dados SQL do Azure ou de uma instância gerenciada do SQL do Azure e o torna pesquisável no Azure AI Search.
Este artigo complementa Criar um indexador com informações específicas do Azure SQL. 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.
Este artigo também prevê:
Uma descrição das políticas de deteção de alterações suportadas pelo indexador SQL do Azure para que possa configurar a indexação incremental.
Uma seção de perguntas frequentes (FAQ) para respostas a perguntas sobre compatibilidade de recursos.
Nota
A sincronização de dados em tempo real não é possível com um indexador. Um indexador pode reindexar sua tabela no máximo a cada cinco minutos. Caso as atualizações de dados precisem ser refletidas no índice mais cedo, recomendamos enviar linhas atualizadas diretamente.
Pré-requisitos
Um banco de dados SQL do Azure ou uma Instância Gerenciada SQL com um ponto de extremidade público.
Uma única tabela ou vista.
Use uma tabela se seus dados forem grandes ou se você precisar de indexação incremental usando os recursos nativos de deteção de alterações do SQL (controle de alterações integrado ao SQL) para refletir linhas novas, alteradas e excluídas no índice de pesquisa.
Use um modo de exibição se precisar consolidar dados de várias tabelas. Exibições grandes não são ideais para o indexador SQL. Uma solução alternativa é criar uma nova tabela apenas para ingestão em seu índice de Pesquisa de IA do Azure. Se optar por utilizar uma vista, pode utilizar a Marca de Água Alta para deteção de alterações, mas tem de utilizar uma solução alternativa para deteção de eliminações.
A chave primária deve ter um único valor. Em uma tabela, ele também deve ser não-clusterizado para controle de alterações integrado SQL completo.
Permissões de leitura. O Azure AI Search dá suporte à autenticação do SQL Server, onde o nome de usuário e a senha são fornecidos na cadeia de conexão. Como alternativa, você pode configurar uma identidade gerenciada e usar funções do Azure com associação às funções de Colaborador do SQL Server ou de Colaborador do Banco de Dados SQL .
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 na firewall SQL do Azure e que o cliente tem acesso através de uma regra de entrada. Para um cliente REST executado localmente, configure o firewall do SQL Server para permitir o acesso de entrada do endereço IP do dispositivo. Outras abordagens para criar um indexador SQL do Azure incluem SDKs do Azure.
Tente com dados de exemplo
Use estas instruções para criar e carregar uma tabela no Banco de Dados SQL do Azure para fins de teste.
Baixe hotels-azure-sql.sql do GitHub para criar uma tabela no Banco de Dados SQL do Azure que contenha um subconjunto do conjunto de dados de hotéis de exemplo.
Entre no portal do Azure e crie um banco de dados SQL do Azure e um servidor de banco de dados. Considere configurar a autenticação do SQL Server e a autenticação do Microsoft Entra ID. Se você não tiver permissões para configurar funções no Azure, poderá usar a autenticação SQL como uma solução alternativa.
Configure o firewall do servidor para todas as solicitações de entrada do seu dispositivo local.
Na base de dados SQL do Azure, selecione Editor de consultas (pré-visualização) e, em seguida, selecione Nova consulta.
Cole e execute o script T-SQL que cria a tabela de hotéis. Uma chave primária não clusterizada é um requisito para o controle de alterações integrado ao SQL.
CREATE TABLE tbl_hotels ( Id TINYINT PRIMARY KEY NONCLUSTERED, Modified DateTime NULL DEFAULT '0000-00-00 00:00:00', IsDeleted TINYINT, HotelName VARCHAR(40), Category VARCHAR(20), City VARCHAR(30), State VARCHAR(4), Description VARCHAR(500) );
Cole e execute o script T-SQL que insere registros.
-- Insert rows INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (1, CURRENT_TIMESTAMP, 0, 'Stay-Kay City Hotel', 'Boutique', 'New York', 'NY', 'This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of Americas most attractive and cosmopolitan cities.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (10, CURRENT_TIMESTAMP, 0, 'Countryside Hotel', 'Extended-Stay', 'Durham', 'NC', 'Save up to 50% off traditional hotels. Free WiFi, great location near downtown, full kitchen, washer & dryer, 24\/7 support, bowling alley, fitness center and more.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (11, CURRENT_TIMESTAMP, 0, 'Royal Cottage Resort', 'Extended-Stay', 'Bothell', 'WA', 'Your home away from home. Brand new fully equipped premium rooms, fast WiFi, full kitchen, washer & dryer, fitness center. Inner courtyard includes water features and outdoor seating. All units include fireplaces and small outdoor balconies. Pets accepted.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (12, CURRENT_TIMESTAMP, 0, 'Winter Panorama Resort', 'Resort and Spa', 'Wilsonville', 'OR', 'Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms\/suites offer mini-fridges & 49-inch HDTVs.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (13, CURRENT_TIMESTAMP, 0, 'Luxury Lion Resort', 'Luxury', 'St. Louis', 'MO', 'Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (14, CURRENT_TIMESTAMP, 0, 'Twin Vortex Hotel', 'Luxury', 'Dallas', 'TX', 'New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (15, CURRENT_TIMESTAMP, 0, 'By the Market Hotel', 'Budget', 'New York', 'NY', 'Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (16, CURRENT_TIMESTAMP, 0, 'Double Sanctuary Resort', 'Resort and Spa', 'Seattle', 'WA', '5 Star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in\/out, Fitness Center & espresso in room.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (17, CURRENT_TIMESTAMP, 0, 'City Skyline Antiquity Hotel', 'Boutique', 'New York', 'NY', 'In vogue since 1888, the Antiquity Hotel takes you back to bygone era. From the crystal chandeliers that adorn the Green Room, to the arched ceilings of the Grand Hall, the elegance of old New York beckons. Elevate Your Experience. Upgrade to a premiere city skyline view for less, where old world charm combines with dramatic views of the city, local cathedral and midtown.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (18, CURRENT_TIMESTAMP, 0, 'Ocean Water Resort & Spa', 'Luxury', 'Tampa', 'FL', 'New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (19, CURRENT_TIMESTAMP, 0, 'Economy Universe Motel', 'Budget', 'Redmond', 'WA', 'Local, family-run hotel in bustling downtown Redmond. We are a pet-friendly establishment, near expansive Marymoor park, haven to pet owners, joggers, and sports enthusiasts. Close to the highway and just a short drive away from major cities.'); INSERT INTO tbl_hotels (Id, Modified, IsDeleted, HotelName, Category, City, State, Description) VALUES (20, CURRENT_TIMESTAMP, 0, 'Delete Me Hotel', 'Unknown', 'Nowhere', 'XX', 'Test-case row for change detection and delete detection . For change detection, modify any value, and then re-run the indexer. For soft-delete, change IsDelete from zero to a one, and then re-run the indexer.');
Execute uma consulta para confirmar o upload.
SELECT Description FROM tbl_hotels;
Você verá resultados semelhantes à captura de tela a seguir.
O campo Descrição fornece o conteúdo mais detalhado. Você deve direcionar este campo para pesquisa de texto completo e vetorização opcional.
Agora que você tem uma tabela de banco de dados, pode usar o portal do Azure, o cliente REST ou um SDK do Azure para indexar seus dados.
Gorjeta
Outro recurso que fornece conteúdo e código de exemplo pode ser encontrado em Azure-Samples/SQL-AI-samples.
Configurar o pipeline do indexador
Nesta etapa, especifique a fonte de dados, o índice e o indexador.
Verifique se o banco de dados SQL está ativo e não pausado devido à inatividade. No portal do Azure, navegue até a página do servidor de banco de dados e verifique se o status do banco de dados está online. Você pode executar uma consulta em qualquer tabela para ativar o banco de dados.
Verifique se você tem uma tabela ou exibição que atenda aos requisitos para indexadores e deteção de alterações.
Primeiro, você só pode extrair de uma única tabela ou exibição. Recomendamos tabelas porque elas oferecem suporte à política de controle de alterações integrada ao SQL, que deteta linhas novas, atualizadas e excluídas. Uma política de marca d'água alta não permite a eliminação de linhas e é mais difícil de implementar.
Em segundo lugar, a chave primária deve ser um único valor (chaves compostas não são suportadas) e não clusterizada.
Mude para o serviço de pesquisa e crie uma fonte de dados. Em Gerenciamento de pesquisa Fontes de>dados, selecione Adicionar fonte de dados:
- Para o tipo de fonte de dados, escolha Banco de Dados SQL do Azure.
- Forneça um nome para o objeto de fonte de dados no Azure AI Search.
- Use os menus suspensos para selecionar a assinatura, o tipo de conta, o servidor, o banco de dados, a tabela ou exibição, o esquema e o nome da tabela.
- Para o controle de alterações, recomendamos a Política Integrada de Controle de Alterações do SQL.
- Para autenticação, recomendamos conectar-se com uma identidade gerenciada. Seu serviço de pesquisa deve ter associação à função de Colaborador do SQL Server ou Colaborador do Banco de Dados SQL no banco de dados.
- Selecione Criar para criar a fonte de dados.
Inicie o assistente Importar dados para criar o índice e o indexador.
- Na página Visão geral, selecione Importar dados.
- Selecione a fonte de dados que você acabou de criar e selecione Avançar.
- Ignore a página Adicionar habilidades cognitivas (Opcional).
- Em Personalizar índice de destino, nomeie o índice, defina a chave para sua chave primária na tabela e, em seguida, selecione Recuperável e Pesquisável para todos os campos e, opcionalmente, adicione Filtrável e Classificável para cadeias curtas ou valores numéricos.
- Em Criar um indexador, nomeie o indexador e selecione Enviar.
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 da API REST Get Indexer Status
Na página do serviço de pesquisa, abra Gerenciamento de pesquisa>Indexadores.
Selecione um indexador para acessar o histórico de configuração e execução.
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 linhas novas, alteradas e excluídas
Se o seu banco de dados SQL oferecer suporte ao rastreio de alterações, um indexador de pesquisa poderá captar apenas o conteúdo novo e atualizado em execuções posteriores do indexador.
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 sua tabela ou exibição.
Para indexadores SQL do Azure, há duas políticas de deteção de alterações:
"SqlIntegratedChangeTrackingPolicy" (aplica-se apenas a tabelas)
"HighWaterMarkChangeDetectionPolicy" (funciona para visualizações)
Política de controle de alterações integrada do SQL
Recomendamos o uso de "SqlIntegratedChangeTrackingPolicy" por sua eficiência e sua capacidade de identificar linhas excluídas.
Requisitos da base de dados:
- Banco de Dados SQL do Azure ou Instância Gerenciada SQL. SQL Server 2016 ou posterior se você estiver usando uma VM do Azure.
- O banco de dados deve ter o controle de alterações habilitado
- Apenas tabelas (sem vistas).
- As tabelas não podem ser agrupadas. Para atender a esse requisito, descarte o índice clusterizado e recrie-o como índice não clusterizado. Essa solução alternativa geralmente degrada o desempenho. A duplicação de conteúdo em uma segunda tabela dedicada ao processamento do indexador pode ser uma atenuação útil.
- As tabelas não podem estar vazias. Se você usar TRUNCATE TABLE para limpar linhas, uma redefinição e nova execução do indexador não removerá os documentos de pesquisa correspondentes. Para remover documentos de pesquisa órfãos, você deve indexá-los com uma ação de exclusão.
- A chave primária não pode ser uma chave composta (contendo mais de uma coluna).
- A chave primária deve ser não clusterizada se você quiser a deteção de exclusão.
As políticas de deteção de alterações são adicionadas às definições da fonte de dados. Para usar essa política, edite a definição da fonte de dados no portal do Azure ou use REST para atualizar sua fonte de dados da seguinte forma:
POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: admin-key
{
"name" : "myazuresqldatasource",
"type" : "azuresql",
"credentials" : { "connectionString" : "connection string" },
"container" : { "name" : "table name" },
"dataChangeDetectionPolicy" : {
"@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy"
}
}
Ao usar a política de controle de alterações integrada ao SQL, não especifique uma política de deteção de exclusão de dados separada. A política de controle de alterações integrada ao SQL tem suporte interno para identificar linhas excluídas. No entanto, para que as linhas excluídas sejam detetadas automaticamente, a chave do documento no índice de pesquisa deve ser a mesma que a chave primária na tabela SQL e a chave primária deve ser não clusterizada.
Política de Deteção de Alteração de Marcas d’Água Elevadas
Essa política de deteção de alterações depende de uma coluna de "indicador elevado" na sua tabela ou vista que regista a versão ou o momento em que uma linha foi atualizada pela última vez. Se estiver a utilizar uma vista, tem de utilizar uma política de marca de água elevada.
A coluna de marca d'água alta deve atender aos seguintes requisitos:
- Todas as inserções especificam um valor para a coluna.
- Todas as atualizações de um item também alteram o valor da coluna.
- O valor desta coluna aumenta a cada inserção ou atualização.
- As consultas com as seguintes cláusulas WHERE e ORDER BY podem ser executadas de forma eficiente:
WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]
Nota
Recomendamos fortemente usar o tipo de dados rowversion para a coluna de marca de referência alta. Se qualquer outro tipo de dados for usado, não é garantido que o controle de alterações capture todas as alterações na presença de transações executadas simultaneamente com uma consulta indexadora. Ao usar rowversion em uma configuração com réplicas só de leitura, deve-se apontar o indexador para a réplica primária. Somente uma réplica primária pode ser usada para cenários de sincronização de dados.
As políticas de deteção de alterações são adicionadas às definições da fonte de dados. Para usar essa política, crie ou atualize sua fonte de dados da seguinte forma:
POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: admin-key
{
"name" : "myazuresqldatasource",
"type" : "azuresql",
"credentials" : { "connectionString" : "connection string" },
"container" : { "name" : "table or view name" },
"dataChangeDetectionPolicy" : {
"@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"highWaterMarkColumnName" : "[a rowversion or last_updated column name]"
}
}
Nota
Se a tabela de origem não tiver um índice na coluna de limite máximo, as consultas usadas pelo indexador SQL poderão expirar. Em particular, a cláusula ORDER BY [High Water Mark Column]
requer um índice para funcionar eficientemente quando a tabela contém muitas linhas.
convertHighWaterMarkToRowVersion
Se estiver a usar um tipo de dados rowversion para a coluna de marca d'água alta, considere definir a propriedade na configuração do convertHighWaterMarkToRowVersion
indexador. Definir essa propriedade como true resulta nos seguintes comportamentos:
Usa o tipo de dados rowversion para a coluna de alto ponto de referência na consulta SQL do indexador. O uso do tipo de dados correto melhora o desempenho da consulta do indexador.
Subtrai um do valor rowversion antes da execução da consulta do indexador. As visualizações com junções um-para-muitos podem ter linhas com valores de 'rowversion' duplicados. Subtrair um garante que a consulta do indexador não perca essas linhas.
Para habilitar essa propriedade, crie ou atualize o indexador com a seguinte configuração:
{
... other indexer definition properties
"parameters" : {
"configuration" : { "convertHighWaterMarkToRowVersion" : true } }
}
tempo de espera da consulta
Se você encontrar erros de tempo limite, defina a configuração do queryTimeout
indexador para um valor maior do que o tempo limite padrão de 5 minutos. Por exemplo, para definir o tempo limite para 10 minutos, crie ou atualize o indexador com a seguinte configuração:
{
... other indexer definition properties
"parameters" : {
"configuration" : { "queryTimeout" : "00:10:00" } }
}
desativarOrdenarPorColunaDeMarcaDeAlta
Você também pode desativar a ORDER BY [High Water Mark Column]
cláusula. No entanto, isso não é recomendado porque, se a execução do indexador for interrompida por um erro, o indexador terá que reprocessar todas as linhas se for executado posteriormente, mesmo que o indexador já tenha processado quase todas as linhas no momento em que foi interrompido. Para desativar a ORDER BY
cláusula, use a definição disableOrderByHighWaterMarkColumn
na configuração do indexador:
{
... other indexer definition properties
"parameters" : {
"configuration" : { "disableOrderByHighWaterMarkColumn" : true } }
}
Política de Deteção de Eliminação Suave de Colunas
Quando as linhas são excluídas da tabela de origem, você provavelmente deseja excluir essas linhas do índice de pesquisa também. Se você usar a política de controle de alterações integrada do SQL, isso será resolvido para você. No entanto, a política de controle de alterações de marca d'água alta não ajuda você com linhas excluídas. O que fazer?
Se as linhas forem fisicamente removidas da tabela, o Azure AI Search não terá como inferir a presença de registros que não existem mais. No entanto, você pode usar a técnica "soft-delete" para excluir logicamente linhas sem removê-las da tabela. Adicione uma coluna à sua tabela ou vista e marque as linhas como eliminadas utilizando essa coluna.
Ao usar a técnica de exclusão suave, você pode especificar a política de exclusão suave da seguinte forma ao criar ou atualizar a fonte de dados:
{
…,
"dataDeletionDetectionPolicy" : {
"@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
"softDeleteColumnName" : "[a column name]",
"softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
}
}
O softDeleteMarkerValue deve ser uma cadeia de caracteres na representação JSON da sua fonte de dados. Utilize a representação string do seu valor real. Por exemplo, se você tiver uma coluna inteira onde as linhas excluídas são marcadas com o valor 1, use "1"
. Se você tiver uma coluna BIT onde as linhas excluídas são marcadas com o valor verdadeiro booleano, use a cadeia de caracteres literal "True"
ou "true"
, o caso não importa.
Se você estiver configurando uma política de exclusão flexível do portal do Azure, não adicione aspas em torno do valor do marcador de exclusão suave. O conteúdo do campo já é entendido como uma string e é traduzido automaticamente em uma string JSON para você. Nos exemplos anteriores, basta digitar 1
, True
ou true
no campo do portal do Azure.
FAQ
P: Posso indexar colunas Sempre Encriptadas?
Não, as colunas Sempre Encriptadas não são atualmente suportadas pelos indexadores do Azure AI Search.
P: Posso usar o indexador SQL do Azure com bancos de dados SQL em execução em VMs IaaS no Azure?
Sim. No entanto, você precisa permitir que seu serviço de pesquisa se conecte ao seu banco de dados. Para obter mais informações, consulte Configurar uma conexão de um indexador do Azure AI Search com o SQL Server em uma VM do Azure.
P: Posso usar o indexador SQL do Azure com bancos de dados SQL em execução no local?
Não diretamente. Não recomendamos nem damos suporte a uma conexão direta, pois isso exigiria que você abrisse seus bancos de dados para o tráfego da Internet. Os clientes tiveram sucesso com esse cenário usando tecnologias de ponte como o Azure Data Factory. Para obter mais informações, consulte Enviar dados por push para um índice do Azure AI Search usando o Azure Data Factory.
P: Posso usar uma réplica secundária em um cluster de failover como fonte de dados?
Depende. Para indexação completa de uma tabela ou exibição, você pode usar uma réplica secundária.
Para indexação incremental, o Azure AI Search dá suporte a duas políticas de deteção de alterações: controle de alterações integrado ao SQL e High Water Mark.
Em réplicas somente leitura, o Banco de dados SQL não oferece suporte ao controle integrado de alterações. Portanto, você deve usar a política High Water Mark.
Nossa recomendação padrão é usar o tipo de dados rowversion para a coluna de marca d'água alta. No entanto, o uso de rowversion depende da função, que não é suportada MIN_ACTIVE_ROWVERSION
em réplicas somente leitura. Portanto, você deve apontar o indexador para uma réplica primária se estiver usando rowversion.
Se tentar usar rowversion numa réplica somente leitura, receberá o seguinte erro:
"O uso de uma coluna rowversion para controle de alterações não é suportado em réplicas de disponibilidade secundárias (somente leitura)." Atualize a fonte de dados e especifique uma conexão com a réplica de disponibilidade primária. A propriedade 'Atualizabilidade' do banco de dados atual é 'READ_ONLY'.
P: Posso usar uma coluna alternativa, sem controle de versão de linha, para o rastreamento de alterações com ponto de referência elevado?
Não é recomendado. Somente rowversion permite uma sincronização de dados confiável. No entanto, dependendo da lógica do seu aplicativo, ele pode ser seguro se:
Você pode garantir que, quando o indexador é executado, não há transações pendentes na tabela que está sendo indexada (por exemplo, todas as atualizações de tabela acontecem como um lote em uma agenda, e a agenda do indexador do Azure AI Search é definida para evitar sobreposição com a agenda de atualização da tabela).
Você periodicamente faz uma reindexação completa para recuperar as linhas perdidas.