ANALYZE TABLE ... MÉTRICAS DE COMPUTAÇÃO DE ARMAZENAMENTO

Aplica-se a: Runtime Databricks 18.0 e superiores

O ANALYZE TABLE … COMPUTE STORAGE METRICS comando calcula métricas de tamanho total de armazenamento para tabelas. Mostra uma distribuição detalhada do armazenamento para análise e otimização de custos. Para otimização de desempenho de consultas, vejaANALYZE TABLE ... CALCULAR ESTATÍSTICAS.

Por defeito, o comando escaneia diretamente os ficheiros da tabela. Em tabelas grandes, adicione a USING INVENTORY cláusula para ler a partir de um relatório de inventário de armazenamento na cloud pré-gerado, o que reduz tanto o tempo como o custo de calcular métricas de armazenamento. Veja Utilizar um relatório de inventário.

Sintaxe

ANALYZE TABLE table_name COMPUTE STORAGE METRICS
  [ USING INVENTORY LOCATION inventory_path
    CONF conf_name ]

Parâmetros

• table_name

  Identifica a tabela a ser analisada. O nome não deve incluir uma especificação temporal ou de opções ou um caminho. Se a tabela não for encontrada, o Azure Databricks levanta uma condição de erro TABLE_OR_VIEW_NOT_FOUND.

• USING INVENTORY

  Opcional. Lê métricas de armazenamento de um relatório de inventário pré-gerado na cloud em vez de analisar os ficheiros da tabela. Veja Utilizar um relatório de inventário. Utiliza dois subparâmetros:

  • LOCATION inventory_path

    Um literal STRING com o caminho completo de armazenamento na cloud para o relatório de inventário, incluindo qualquer prefixo. Este caminho deve corresponder ao destino que configurou quando configurou o relatório de inventário no balde ou contentor de origem, e deve ser apoiado por uma localização externa a que tenha acesso. Veja Utilizar um relatório de inventário.

    Por exemplo, 'abfss://your-destination-container@your-storage-account.dfs.core.windows.net/your-prefix/'.

  • CONF conf_name

    Required. Um literal STRING que identifica qual configuração do relatório de inventário no bucket ou contentor de origem a utilizar.

    Se configurar a regra da política de inventário de blob usando a CLI do Azure, use o mesmo valor que definiu para name. Se configurares usando a consola do Azure, usa o valor que defines para o nome da Regra em vez disso.

Description

Calcula métricas de tamanho total de armazenamento para uma tabela específica. Este comando devolve informações completas de armazenamento, incluindo bytes totais, bytes ativos, bytes que podem ser comprimidos e bytes de retrocesso no tempo, juntamente com o número de ficheiros associado para cada categoria.

Use este comando para identificar tabelas grandes ou não utilizadas, otimizar custos de armazenamento e compreender porque é que o tamanho total de armazenamento difere do tamanho da tabela ativa. Isto é útil para administradores de plataformas que precisam de analisar padrões de armazenamento em múltiplas tabelas ou acompanhar alterações de armazenamento ao longo do tempo.

Métricas de saída

O comando devolve três colunas: metric_name, metric_value, e metric_description. Uma linha é devolvida para cada uma das seguintes métricas:

Detalhes

• Por defeito, o comando utiliza uma abordagem de lista recursiva para calcular a informação de armazenamento. O tempo de execução é tipicamente de minutos, mas pode demorar várias horas para tabelas muito grandes.
• Este comando funciona tanto para tabelas geridas pelo Unity Catalog como para tabelas externas.
• O comando calcula métricas de armazenamento em tempo de execução. Os resultados não são armazenados no Unity Catalog nem são refletidos na DESCRIBE EXTENDED saída, que mostra apenas o tamanho da tabela ativa.
• Para acompanhar as alterações de armazenamento ao longo do tempo, execute este comando periodicamente e armazene os resultados numa tabela. Execute este comando num ciclo através de várias tabelas para analisar padrões de armazenamento em todo o seu património de dados. Veja Métricas de armazenamento computacional para todas as tabelas num catálogo.

Use um relatório de inventário

Aplica-se a: Databricks Runtime 19 e superiores

Use a USING INVENTORY cláusula em tabelas grandes para reduzir o tempo e o custo de calcular métricas de armazenamento, lendo um relatório de inventário pré-gerado em nuvem em vez de analisar os ficheiros da tabela. A Databricks recomenda esta cláusula para tabelas compostas por 100.000 ou mais ficheiros, ou para tabelas fortemente particionadas em múltiplas chaves. Para tabelas mais pequenas, ou tabelas sem um relatório de inventário configurado, use o comando sem esta cláusula.

A USING INVENTORY cláusula funciona para tabelas geridas pelo Unity Catalog e externas. Funciona apenas em computação clássica. Para mais limitações, veja LIMITAÇÕES DE UTILIZAÇÃO DE INVENTÁRIO.

Para informações sobre as métricas que o comando devolve, veja Métricas de Saída.

Pré-requisitos

A USING INVENTORY cláusula tem os seguintes pré-requisitos:

• Privilégios para configurar pela primeira vez: Os administradores da Metastore têm os privilégios necessários do Azure Databricks por defeito. Se não for administrador, para configurar relatórios de inventário e registar o seu destino como localização externa, deve ter as seguintes permissões:
  • Permissões do fornecedor de cloud para configurar relatórios de inventário no bucket de origem ou contentor.
  • Um dos seguintes privilégios do Azure Databricks para registar o destino do inventário como localização externa:
    • O privilégio CREATE EXTERNAL LOCATION tanto na metastore como na credencial de armazenamento que refere.
    • O MANAGE privilégio no local externo.

• Um relatório de inventário configurado: Configure um relatório de inventário de blobs do Armazenamento do Azure em cada contentor de origem que contém as tabelas que pretende analisar. Use estas definições:
  • Tipo de objeto: Blob
  • Tipos de blobs: blobs de bloco e blobs de anexação
  • Subtipos: Não ative Incluir snapshots ou Incluir blobs eliminados
  • Frequência: Diária
  • Formato de exportação: Apache Parquet
  • Campos de inventário do blob: Incluir Nome, Último Modificado, Comprimento do Conteúdo, Instantâneo, Eliminado e estado da pasta HDI (CLI schemaFields: Name, Last-Modified, Content-Length, Snapshot, Deleted, hdi_isfolder). Sem eles, o comando não consegue calcular a saída correta.

• Uma localização externa para o relatório de inventário: Deve ter acesso de leitura no Azure Databricks ao caminho de destino do relatório de inventário.

  • Se o caminho não estiver numa localização externa existente, regista-o primeiro como uma localização externa. Veja Estabelecer ligação a uma localização externa do Azure Data Lake Storage Gen2 (ADLS Gen2).

• Privilégios para executar o comando: Deve ter o READ FILES privilégio na localização externa no Azure Databricks que apoia o destino do relatório de inventário, além dos seus privilégios existentes na tabela que analisa.

Para encontrar o balde de origem ou contentor para uma tabela, execute DESCRIBE TABLE EXTENDED e verifique o Location campo na saída. Para visualizações materializadas e tabelas de streaming, deve usar DESCRIBE EXTENDED para encontrar o local real de armazenamento. Deve verificar se o seu relatório de inventário está configurado nesse balde ou contentor de origem.

Erros nos relatórios de inventário estagnados

O comando procura o relatório de inventário completo mais recente gerado nos últimos 14 dias. Se não encontrar relatório nessa janela, o comando não calcula métricas e devolve um ANALYZE_TABLE_COMPUTE_STORAGE_METRICS_INVENTORY_CONTENTS_NOT_VALID erro com uma mensagem semelhante à seguinte:

No inventory reports found in the last 14 days (window: 2026-07-08 to 2026-07-22).
1 report directory(s) exist but fall outside the lookback window.
Ensure a recent inventory report has been generated.

Para resolver este erro, confirme que o bucket de origem ou contentor gera relatórios de inventário no calendário que configurou, e depois execute novamente o comando após gerar um novo relatório. Consulte Pré-requisitos.

Considerações sobre tipos de tabela

Para visualizações materializadas e tabelas de streaming, total_bytes inclui o tamanho da tabela e os metadados associados. A active_bytes métrica exclui as tabelas vacuumable_bytes e time_travel_bytes.

Para clones superficiais, total_bytes inclui apenas os metadados próprios do clone e os ficheiros de registo Delta, excluindo ficheiros de tabela de origem. active_bytes é zero porque o clone faz referência aos ficheiros de dados da tabela de origem.

Exemplos

Métricas de computação de armazenamento

Para calcular métricas de armazenamento, execute o seguinte comando:

ANALYZE TABLE main.my_schema.my_table COMPUTE STORAGE METRICS;

O comando devolve a saída, como a seguinte:

metric_name              metric_value  metric_description
-----------------------  ------------  --------------------------------------------------
total_bytes                5368709120  Total bytes on disk
num_total_files                  1250  Total files on disk
active_bytes               4294967296  Bytes in current snapshot
num_active_files                 1000  Files in current snapshot
vacuumable_bytes            805306368  Bytes eligible for vacuum
num_vacuumable_files              150  Files eligible for vacuum
time_travel_bytes           268435456  Bytes reachable by time travel (excluding active)
num_time_travel_files             100  Files reachable by time travel (excluding active)

O resultado mostra:

• Armazenamento total: 5,37 GB em 1.250 ficheiros
• Dados ativos: 4,29 GB em 1.000 ficheiros (versão atual da tabela)
• Dados aspiráveis: 805 MB em 150 ficheiros (VACUUM pode recuperar este tamanho de armazenamento)
• Dados de viagem no tempo: 268 MB em 100 ficheiros (para consultas históricas)

Calcular métricas de armazenamento usando um relatório de inventário

O exemplo seguinte calcula as mesmas métricas a partir de um relatório de inventário em vez de analisar os ficheiros da tabela:

ANALYZE TABLE main.my_schema.my_table COMPUTE STORAGE METRICS
USING INVENTORY LOCATION 'abfss://your-destination-container@your-storage-account.dfs.core.windows.net/your-prefix/'
CONF 'databricks-inventory-list-config';

Como os relatórios de inventário refletem o estado da tabela no momento em que o relatório foi gerado (até 24 horas antes), o resultado pode diferir de uma varredura direta. Por exemplo:

metric_name              metric_value  metric_description
-----------------------  ------------  --------------------------------------------------
total_bytes                5100273664  Total bytes on disk
num_total_files                  1232  Total files on disk
active_bytes               4076863488  Bytes in current snapshot
num_active_files                  984  Files in current snapshot
vacuumable_bytes            771751936  Bytes eligible for vacuum
num_vacuumable_files              148  Files eligible for vacuum
time_travel_bytes           251658240  Bytes reachable by time travel (excluding active)
num_time_travel_files             100  Files reachable by time travel (excluding active)

Veja Utilizar um relatório de inventário.

Calcular métricas de armazenamento para todas as tabelas de um catálogo

Para calcular métricas de armazenamento para cada tabela de um catálogo, todas usando relatórios de inventário no mesmo destino, utiliza-se um ciclo. O exemplo seguinte lista as tabelas usando um esquema de informação, que cada catálogo inclui automaticamente:

%python
tables = spark.sql("""
  SELECT table_catalog, table_schema, table_name
  FROM main.information_schema.tables
  WHERE table_type IN (
    'MANAGED', 'EXTERNAL',
    'STREAMING_TABLE', 'MATERIALIZED_VIEW',
    'MANAGED_SHALLOW_CLONE', 'EXTERNAL_SHALLOW_CLONE'
  )
""").collect()

for t in tables:
    full_name = f"{t.table_catalog}.{t.table_schema}.{t.table_name}"
    result = spark.sql(f"""
      ANALYZE TABLE {full_name} COMPUTE STORAGE METRICS
      USING INVENTORY LOCATION 'abfss://your-destination-container@your-storage-account.dfs.core.windows.net/your-prefix/'
      CONF 'databricks-inventory-list-config'
    """)
    result.show()

UTILIZAÇÃO DAS LIMITAÇÕES DO INVENTÁRIO

A USING INVENTORY cláusula tem as seguintes limitações:

• Esta cláusula corre apenas em computação clássica. Não é suportado em computação serverless nem em armazéns SQL do Databricks.
• Esta cláusula suporta apenas tabelas de catálogo, incluindo tabelas geridas e externas. Não suporta tabelas Delta Lake baseadas em caminhos, que geram um erro: ANALYZE_TABLE_COMPUTE_STORAGE_METRICS_NOT_SUPPORTED condição de erro.
• Se a versionação de objetos estiver ativada no bucket ou contentor de origem, os resultados não são garantidos que estejam corretos.
• Se a localização de armazenamento de uma tabela mudar, reconfigure o relatório de inventário no novo balde ou contentor de origem. A localização original já não gera relatórios para a tabela. Por exemplo, converter uma tabela externa numa tabela gerida altera a localização de armazenamento da tabela. Veja Converter tabelas Delta Lake externas ou estrangeiras para tabelas geridas pelo Unity Catalog.

O Azure não suporta configuração de inventário entre contas de armazenamento. Se as suas tabelas abrangerem várias contas de armazenamento, cada conta precisa da sua própria configuração de inventário.

Notebook: Calcular métricas de armazenamento para múltiplas tabelas

O caderno seguinte percorre ANALYZE TABLE ... COMPUTE STORAGE METRICS ... USING INVENTORY um conjunto de tabelas do Catálogo Unity e armazena os resultados numa tabela Delta Lake. Use-o para analisar o armazenamento em várias tabelas ao mesmo tempo.

Métricas de computação de armazenamento para caderno de múltiplas tabelas

Obter caderno

Declarações relacionadas

• ANALYZE TABLE ... CALCULAR ESTATÍSTICAS
• VACUUM
• Otimização preditiva para tabelas geridas do Unity Catalog
• Trabalhar com o histórico da tabela
• Converter tabelas Delta Lake externas ou estrangeiras em tabelas geridas pelo Unity Catalog
• Localizações externas