Otimizar tabelas do Lakehouse com base nas verificações de integridade

Aplica-se a:✅ endpoint de análise SQL no Microsoft Fabric

Neste tutorial, você aprenderá a criar uma Microsoft Fabric Pipeline para executar a manutenção inteligente da tabela.

Essa solução chama o sys.sp_get_table_health_metrics procedimento armazenado T-SQL no endpoint de análise SQL do Lakehouse, avalia o resultado e executa OPTIMIZE somente quando a tabela realmente precisa de manutenção. Esse padrão "check-then-act" evita gastos desnecessários com computação em tabelas saudáveis, garantindo que tabelas degradadas recebam manutenção automaticamente.

Por que a manutenção é necessária

As tabelas do lakehouse podem acumular arquivos Parquet pequenos demais ao longo do tempo, o que prejudica o desempenho das consultas no endpoint de análise SQL.

Em vez de executar OPTIMIZE em uma programação fixa, independentemente do estado da tabela, esse pipeline toma uma decisão embasada: primeiro, verifica a integridade da tabela e só aciona a otimização quando uma anomalia é detectada.

Pré-requisitos

Antes de começar, verifique se você tem:

• Um espaço de trabalho do Microsoft Fabric com permissões de Colaborador ou superior.
• Um Lakehouse nesse espaço de trabalho contendo pelo menos uma tabela Delta que você deseja monitorar. Este tutorial usa um Lakehouse chamado SalesDataLakehouse.
• Familiaridade com pipelines de dados do Fabric.
• Familiaridade com os notebooks do Fabric.

Estrutura da solução

O pipeline concluído tem esta estrutura:

1. Atividade de script: executa sp_get_table_health_metrics na tabela de destino e retorna métricas de integridade da tabela como saída estruturada.
2. Atividade de condição: lê PotentialAnomalyType diretamente da saída do Script e verifica se ele é maior que zero. Para obter mais informações sobre os PotentialAnomalyType, consulte códigos de tipos de anomalias potenciais.
3. Atividade de notebook (dentro do ramo True): Executa OPTIMIZE na tabela de um notebook do Spark.

Ao final deste tutorial, você terá um notebook que recebe parâmetros do pipeline e otimiza uma tabela quando acionado.

Etapa 1: Criar o notebook de otimização

O notebook aceita o lakehouse de destino, o esquema e o nome da tabela como parâmetros do pipeline e, em seguida, executa OPTIMIZE usando o Spark SQL.

1. No workspace Fabric, selecione + Novo item>Bloco de Anotações.
2. Nomeie o notebook como Optimize-Table.
3. Em Local, selecione o Lakehouse onde as tabelas que você verifica estão armazenadas. Este exercício usa um Lakehouse chamado SalesDataLakehouse.
4. Selecione Criar.

Adicionar a célula de parâmetro

A primeira célula define as variáveis que o pipeline substitui em runtime.

1. Na primeira célula, insira os parâmetros a seguir. Os valores não são importantes, e o pipeline os substitui em tempo de execução.

   # Parameters 
   lakehouse_name = "<LakehouseName>"
   schema_name    = "<SchemaName>"
   table_name     = "<TableName>"
   

   Importante

   Como a parametrização funciona em notebooks do Fabric: Em tempo de execução, o Fabric injeta uma nova célula imediatamente após a célula de parâmetros que reatribui essas variáveis com os valores passados pelo pipeline. Os valores definidos aqui inicializam apenas as variáveis e melhoram a legibilidade.

2. Selecione o menu da célula (...) >Alterne a célula de parâmetro para marcar essa célula como uma célula de parâmetro.

Adicionar a célula OPTIMIZE

O OPTIMIZE comando é um comando SQL do Spark, não um comando T-SQL. Você deve executá-lo em ambientes spark, como notebooks, definições de trabalho do Spark ou a interface de manutenção do Lakehouse. O endpoint de análise SQL e o editor de consultas SQL do Warehouse não oferecem suporte direto a esse comando.

1. Na segunda célula, insira:

   full_name = f"{lakehouse_name}.{schema_name}.{table_name}"
   print(f"Optimizing {full_name} ...")
   
   result = spark.sql(f"OPTIMIZE {full_name}")
   result.show(truncate=False)
   

2. Adicione células Markdown conforme necessário para documentar corretamente o notebook para outros usuários. Seu bloco de anotações finalizado deve ser semelhante ao seguinte:

   

Etapa 2: Criar o pipeline

1. No workspace do Fabric, selecione + Novo item>Pipeline.

2. Nomeie o pipeline Check-and-Optimize-Table.

3. Selecione o plano de fundo da tela do pipeline e, em seguida, abra a guia Parâmetros. Adicione três parâmetros:

   Name	Tipo	Valor padrão
   lakehouse_name	String	SalesDataLakehouse
   schema_name	String	dbo
   table_name	String	FactSales

Etapa 3: Adicionar a atividade Script

A atividade Script executa sys.sp_get_table_health_metrics no endpoint de análise SQL e captura o resultado.

1. Na guia Atividades, selecione Script para adicioná-lo à área de trabalho.
2. Nomeie como Verificar a integridade da tabela.
3. Na guia Configurações :

   • Conexão: Selecione o endpoint de análises SQL do seu Lakehouse. Se ele não estiver listado, selecione Procurar tudo na parte inferior da lista suspensa e, em seguida, localize o endpoint de análise SQL do Lakehouse.

   • Tipo de script: Selecione Consulta.

   • Script: Selecione Adicionar conteúdo dinâmico e insira a seguinte expressão:

     @concat('EXEC sys.sp_get_table_health_metrics ''',
             pipeline().parameters.schema_name, '.',
             pipeline().parameters.table_name, '''')
     

Essa expressão produz o comando SQL que executa o procedimento armazenado na tabela de destino, por exemplo: EXEC sys.sp_get_table_health_metrics 'dbo.FactSales'.

Verificar a saída do script

Execute o pipeline uma vez e inspecione a saída da atividade Script. Você verá um objeto JSON semelhante a:

{
  "resultSetCount": 1,
  "resultSets": [
    {
      "rowCount": 1,
      "rows": [
        {
          "PotentialAnomalyType": 3,
          "PotentialAnomalyDescription": "Too many small files...",
          "FileCount": 2688,
          "...": "..."
        }
      ]
    }
  ]
}

Etapa 4: Adicionar a atividade If Condition

A atividade If Condition lê PotentialAnomalyType diretamente da saída da atividade Script e toma uma decisão com base em seu resultado. Use as seguintes etapas:

1. Na guia Atividades, selecione Condição Se para adicionar uma atividade na tela.

2. Nomeie como Check Anomaly.

3. Desenhe uma seta de êxito (verde) de Verificar Integridade da Tabela para Verificar Anomalias.

4. Na guia Atividades da atividade If Condition , defina a Expressão como:

   @greater(int(activity('Check Table Health').output.resultSets[0].rows[0]['PotentialAnomalyType']), 0)
   

Essa expressão lê a primeira linha retornada por sys.sp_get_table_health_metrics, converte PotentialAnomalyType em um inteiro e é avaliada para true quando o valor é maior que zero, o que indica uma anomalia detectada na tabela de destino.

Etapa 5: Adicionar a atividade Notebook (ramo True)

Com a atividade If Condition selecionada, selecione Editar (ícone de lápis) ao lado de True. A área de desenho muda para uma subárea de desenho delimitada ao ramo True.

1. Arraste a atividade Notebook para o subcanvas True.

2. Dê o nome de Executar OTIMIZAÇÃO.

3. Na guia Configurações:

   • Notebook: Selecione o notebook Optimize-Table que você criou na Etapa 1.

   • Expanda os parâmetros base e adicione três linhas:

     Name	Tipo	Value
     lakehouse_name	String	@pipeline().parameters.lakehouse_name
     schema_name	String	@pipeline().parameters.schema_name
     table_name	String	@pipeline().parameters.table_name

Os valores de coluna de três nomes devem corresponder exatamente aos nomes das variáveis na célula de parâmetro do notebook.

Seu pipeline finalizado deve ficar como o seguinte:

Etapa 6: Validar e executar

1. Selecione Validar na barra de ferramentas do pipeline para verificar se há erros de configuração.

2. Selecione Executar para executar o pipeline manualmente.

3. Monitore a execução e confirme:

   1. Verifique a integridade da tabela: inspecione a saída dessa atividade quando ela for executada. Você deve ver a saída do procedimento armazenado sys.sp_get_table_health_metrics em formato JSON.
   2. Verificar anomalia: avalia corretamente lendo PotentialAnomalyType diretamente da saída do script.
   3. Executar OPTIMIZE (somente se PotentialAnomalyType > 0): se a atividade Verificar anomalia retornar True, revise a entrada da atividade Executar OPTIMIZE para verificar se ela usa os parâmetros corretos (nome do Lakehouse, esquema e nome da tabela) e verifique a saída para analisar as mensagens da operação OPTIMIZE.

Limpar os recursos

Se você criou recursos apenas para este tutorial e não precisa mais deles, exclua os seguintes itens do seu workspace:

• O pipeline Check-and-Optimize-Table.
• O notebook Optimize-Table.

Conteúdo relacionado

• sp_get_table_health_metrics (Transact-SQL)
• Diretrizes de desempenho no Fabric Data Warehouse