Indexar dados de bancos de dados SQL do Azure

Neste artigo, saiba como configurar um indexador que importa o conteúdo do Banco de Dados SQL do Azure ou uma instância gerenciada de SQL do Azure e o torna pesquisável na IA do Azure Search.

Este artigo complementa Criar um indexador com informações específicas de SQL do Azure. 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 e criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar Indexador.

Este artigo também fornece o seguinte:

• Uma descrição das políticas de detecção de alterações compatíveis com o indexador do SQL do Azure, para que você possa configurar a indexação incremental.

• Uma seção de perguntas frequentes para tirar as dúvidas sobre compatibilidade de recursos.

Pré-requisitos

• Um banco de dados SQL do Azure ou uma Instância Gerenciada de SQL com um ponto de extremidade público.

• Uma única tabela ou exibição.

  Use uma tabela se os dados forem grandes ou se você precisar de indexação incremental usando os recursos nativos de detecçã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 uma exibição se você precisar consolidar dados em várias tabelas. As exibições grandes não são indicadas para o indexador do SQL. Uma solução alternativa é criar uma nova tabela apenas para ingestão no índice da IA do Azure Search. Se você optar por usar uma exibição, poderá usar o High Water Mark para detecção de alterações, mas deverá usar uma solução alternativa para detecção de exclusão.

• A chave primária deve ser de valor único. Em uma tabela, deve também estar não clusterizado para controle de alterações totalmente integrado ao SQL.

• Permissões de leitura. A IA do Azure Search dá suporte à autenticação do SQL Server, em que 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 em funções de Colaborador do SQL Server ou Colaborador de Banco de Dados SQL .

Para trabalhar nos exemplos deste artigo, você precisa do portal do Azure ou de um cliente REST. Se você estiver usando o portal do Azure, verifique se o acesso a todas as redes públicas está habilitado no firewall do SQL do Azure e se o cliente tem acesso por meio 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 de SQL do Azure incluem os SDKs do Azure.

Experimente 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.

1. Baixe hotels-azure-sql.sql do GitHub para criar uma tabela no Banco de Dados SQL do Azure que contém um subconjunto do conjunto de dados de hotéis de exemplo.

2. 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.

3. Configure o firewall do servidor para todas as solicitações de entrada do seu dispositivo local.

4. No banco de dados SQL do Azure, selecione Editor de consultas (versão prévia) e selecione Nova Consulta.

5. Cole e execute o script T-SQL que cria a tabela de hotéis. Uma chave primária não clusterizada é um requisito para acompanhamento de mudanças integrado do 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)
    );
   

6. 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.');
   
   

7. Execute uma consulta para confirmar o upload.

   SELECT Description FROM tbl_hotels;
   

   Você deverá ver resultados semelhantes às seguintes capturas de tela.

   

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

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.

Configurar o pipeline do indexador

Nesta etapa, especifique a fonte de dados, o índice e o indexador.

Checar o status do indexador

Para monitorar o status do indexador e o histórico de execuções, verifique o histórico de execuções do indexador no portal do Azure ou envie uma solicitação Obter Status do Indexador da API REST

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

    {
        "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.

Indexação de linhas novas, alteradas e excluídas

Se o banco de dados SQL for compatível com o controle de alterações, um indexador de pesquisa poderá escolher apenas o conteúdo novo e atualizado nas próximas execuções do indexador.

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 na tabela ou exibição.

Para indexadores de SQL do Azure, há duas políticas de detecção de alterações:

• "SqlIntegratedChangeTrackingPolicy" (aplica-se apenas a tabelas)

• "HighWaterMarkChangeDetectionPolicy" (funciona para exibições)

Política de controle de alterações integrada do SQL

É recomendável usar "SqlIntegratedChangeTrackingPolicy" por sua eficiência e sua capacidade de identificar linhas excluídas.

Requisitos do banco de dados:

• Banco de Dados SQL do Azure ou Instância Gerenciada de 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
• Somente tabelas (sem exibições).
• As tabelas não podem ser agrupadas. Para atender a esse requisito, remova o índice clusterizado e recrie-o como índice não clusterizado. Essa solução alternativa geralmente degrada o desempenho. Duplicar conteúdo em uma segunda tabela dedicada ao processamento do indexador pode ser uma mitigação útil.
• As tabelas não podem estar vazias. Se você usar TRUNCATE TABLE para limpar linhas, uma redefinição e uma nova execução do indexador não removerão 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 estar não clusterizada se você quiser a detecção de exclusão.

As políticas de detecção de alteração são adicionadas às definições de 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 assim:

POST https://myservice.search.windows.net/datasources?api-version=2025-09-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 integrado de alterações do SQL, não especifique uma política de detecção de exclusão de dados separada. A política de controle integrado de alterações do SQL tem suporte interno para identificar linhas excluídas. No entanto, para que as linhas excluídas sejam detectadas automaticamente, a chave do documento no índice de pesquisa deve ser igual à chave primária na tabela SQL e a chave primária deve ser não agrupada.

Política de detecção de alteração de marca d’água alta

Essa política de detecção de alteração se baseia em uma coluna de “marca d'água alta” na tabela ou exibição que captura a versão ou a hora em que uma linha foi atualizada pela última vez. Se você estiver usando uma exibição, deverá usar uma política de marca d'água alta.

A coluna de marca d'água alta deve atender aos requisitos a seguir:

• 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 dessa coluna aumenta com cada inserção ou atualização.
• Consultas com as seguintes cláusulas WHERE e ORDER BY podem ser executadas com eficiência: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

As políticas de detecção de alteração são adicionadas às definições de fonte de dados. Para usar essa política, crie ou atualize a fonte de dados da seguinte maneira:

POST https://myservice.search.windows.net/datasources?api-version=2025-09-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]"
        }
    }

convertHighWaterMarkToRowVersion

Se você estiver usando um tipo de dados rowversion para a coluna de marca d'água alta, considere definir a propriedade convertHighWaterMarkToRowVersion na configuração do indexador. A definição dessa propriedade como true resulta nos seguintes comportamentos:

• Use o tipo de dados rowversion para a coluna de marca d'água alta na consulta SQL do indexador. O uso do tipo de dados correto melhora o desempenho da consulta do indexador.

• Subtraia um do valor rowversion antes da execução da consulta do indexador. Exibições com junções de 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 } }
    }

queryTimeout

Se você encontrar erros de tempo limite, defina a configuração do indexador queryTimeout como um valor maior que o tempo limite padrão de 5 minutos. Por exemplo, para definir o tempo limite de 10 minutos, crie ou atualize o indexador com a seguinte configuração:

    {
      ... other indexer definition properties
     "parameters" : {
            "configuration" : { "queryTimeout" : "00:10:00" } }
    }

disableOrderByHighWaterMarkColumn

Você também pode desabilitar a cláusula ORDER BY [High Water Mark Column]. No entanto, isso não é recomendado porque, se a execução do indexador for interrompida por um erro, o indexador precisará 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 desabilitar a cláusula ORDER BY, use a configuração disableOrderByHighWaterMarkColumn na definição do indexador:

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

Política de detecção de exclusão de coluna por exclusão reversível

Quando as linhas são excluídas da tabela de origem, provavelmente você deseja excluí-las também do índice de pesquisa. Se você usar a política de controle integrado de alterações 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 relação às linhas excluídas. O que fazer?

Se as linhas forem removidas fisicamente da tabela, a IA do Azure Search não terá como inferir na presença de registros que não existem mais. No entanto, você pode usar a técnica de "exclusão reversível" para excluir logicamente linhas sem removê-las da tabela. Adicione uma coluna à sua tabela ou exiba e marque as linhas como excluídas usando essa coluna.

Ao usar a técnica de exclusão reversível, você pode especificar a política de exclusão reversível da seguinte maneira 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 precisa ser uma cadeia de caracteres na representação JSON da fonte de dados. Use a representação de cadeia de caracteres do valor real. Por exemplo, se você tiver uma coluna de inteiros na qual as linhas excluídas são marcadas com o valor 1, use "1". Se você tiver uma coluna BIT na qual as linhas excluídas são marcadas com o valor true booliano, use a cadeia de caracteres literal "True" ou "true", o caso não importa.

Se você estiver configurando uma política de exclusão reversível no portal do Azure, não adicione aspas ao valor do marcador de exclusão reversível. O conteúdo do campo já é compreendido como uma cadeia de caracteres e é convertido automaticamente em uma cadeia de caracteres JSON para você. Nos exemplos anteriores, basta digitar 1, True ou true no campo do portal do Azure.

perguntas frequentes

P: posso indexar colunas Always Encrypted?

Não, colunas Always Encrypted não têm suporte atualmente pelos indexadores da Pesquisa de IA do Azure.

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 o serviço de pesquisa se conecte ao banco de dados. Para obter mais informações, consulte Configurar uma conexão de um indexador da IA do Azure Search ao SQL Server em uma VM do Azure.

P: Posso usar o indexador SQL do Azure com bancos de dados SQL em execução local?

Não diretamente. Não recomendamos nem damos suporte a uma conexão direta, pois isso exigirá a abertura dos bancos de dados ao 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 da IA do Azure Search usando o Azure Data Factory.

P: Posso usar uma réplica secundária em um cluster de failover como fonte de dados?

Isso depende. Para a indexação completa de uma tabela ou exibição, você pode usar uma réplica secundária.

Para a indexação incremental, a IA do Azure Search oferece suporte a duas políticas de detecção de alteração: controle de alterações integrado do SQL e Marca D'água Alta.

Em réplicas somente leitura, o Banco de Dados SQL não dá suporte ao controle de alterações integrado. Portanto, você deve usar a política de Marca D'água Alta.

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 MIN_ACTIVE_ROWVERSION, para a qual não há suporte em réplicas somente leitura. Portanto, você deve apontar o indexador para uma réplica primária se estiver usando rowversion.

Se você tentar usar rowversion em uma réplica somente leitura, obterá o seguinte erro:

“Não há suporte para o uso de uma coluna rowversion para o controle de alterações 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 'Updateability' do banco de dados atual é 'READ_ONLY'”.

P: Posso usar uma coluna não rowversion alternativa para o controle de alterações de marca d'água alta?

Isso não é recomendável. Somente rowversion permite a sincronização de dados confiável. No entanto, dependendo da lógica do aplicativo, ele poderá ser seguro se:

• Você pode garantir que, quando o indexador for executado, não haja transações pendentes na tabela indexada (por exemplo, todas as atualizações de tabela ocorrem como um lote em um agendamento e o agendamento do indexador da IA do Azure Search está definido para evitar sobreposição com o agendamento de atualização da tabela).

• Periodicamente, você fizer uma reindexação completa para selecionar as linhas ausentes.