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

Aplica-se a: Databricks Runtime 18.0 e versões superiores

O ANALYZE TABLE … COMPUTE STORAGE METRICS comando calcula as métricas totais de tamanho de armazenamento para tabelas. Ele mostra um detalhamento de armazenamento para análise e otimização de custos. Para otimização de desempenho de consulta, consulte ANALYZE TABLE ... ESTATÍSTICAS DE COMPUTAÇÃO.

Por padrão, o comando examina diretamente os arquivos da tabela. Em tabelas grandes, adicione a USING INVENTORY cláusula para ler de um relatório de inventário de armazenamento em nuvem pré-gerado, o que reduz o tempo e o custo das métricas de armazenamento de computação. Consulte Usar 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 especificação de opções ou caminho. Se a tabela não puder ser encontrada, o Azure Databricks gerará uma condição de erro TABLE_OR_VIEW_NOT_FOUND.

• USING INVENTORY

  Opcional. Lê as métricas de armazenamento de um relatório de inventário de armazenamento em nuvem pré-gerado em vez de verificar os arquivos da tabela. Consulte Usar um relatório de inventário. Usa dois submetrâmetros:

  • LOCATION inventory_path

    Um literal string com o caminho de armazenamento em nuvem completo para o relatório de inventário, incluindo qualquer prefixo. Esse caminho deve corresponder ao destino que você configurou ao configurar o relatório de inventário no bucket de origem ou contêiner e deve ser apoiado por um local externo ao qual você tem acesso. Consulte Usar 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 de relatório de inventário no bucket de origem ou contêiner a ser usado.

    Se você configurar a regra de política de inventário de blob usando o CLI do Azure, use o mesmo valor definido para name. Se você configurar usando o console Azure, use o valor definido para o nome da regra.

DESCRIÇÃO

Calcula as métricas totais de tamanho de armazenamento para uma tabela específica. Esse comando retorna informações de armazenamento abrangentes, incluindo bytes totais, bytes ativos, bytes a vácuo e bytes de viagem no tempo, juntamente com o número associado de arquivos para cada categoria.

Use este comando para identificar tabelas grandes ou não utilizadas, otimizar os custos de armazenamento e entender por que o tamanho total do armazenamento difere do tamanho da tabela ativa. Isso é útil para administradores de plataforma que precisam analisar padrões de armazenamento em várias tabelas ou acompanhar alterações de armazenamento ao longo do tempo.

Métricas de saída

O comando retorna três colunas: metric_name, metric_valuee metric_description. Uma linha é retornada para cada uma das seguintes métricas:

Detalhes

• Por padrão, o comando usa uma abordagem de lista recursiva para calcular informações de armazenamento. O tempo de execução normalmente é em minutos, mas pode levar até várias horas para tabelas muito grandes.
• Esse comando funciona para tabelas gerenciadas e externas do Catálogo do Unity.
• O comando calcula as métricas de armazenamento em runtime. Os resultados não são armazenados no Catálogo do Unity e não são refletidos na DESCRIBE EXTENDED saída, o que mostra apenas o tamanho da tabela ativa.
• Para controlar as alterações de armazenamento ao longo do tempo, execute esse comando periodicamente e armazene os resultados em uma tabela. Execute esse comando em um loop em várias tabelas para analisar padrões de armazenamento em seu patrimônio de dados. Consulte as métricas de armazenamento de computação para todas as tabelas em um catálogo.

Usar um relatório de inventário

Aplica-se a: Databricks Runtime 19 and above

Use a USING INVENTORY cláusula em tabelas grandes para reduzir o tempo e o custo das métricas de armazenamento de computação lendo um relatório de inventário de armazenamento em nuvem pré-gerado em vez de verificar os arquivos da tabela. O Databricks recomenda essa cláusula para tabelas que consistem em 100.000 ou mais arquivos ou para tabelas que são fortemente particionadas em várias chaves. Para tabelas menores ou tabelas sem um relatório de inventário configurado, use o comando sem essa cláusula.

A USING INVENTORY cláusula funciona para tabelas gerenciadas e externas do Catálogo do Unity. Ele é executado somente na computação clássica. Para obter mais limitações, consulte AS limitações DE USO DE INVENTÁRIO.

Para obter informações sobre as métricas retornadas pelo comando, consulte Métricas de saída.

Pré-requisitos

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

• Privilégios a serem configurados pela primeira vez: os administradores do Metastore têm os privilégios de Azure Databricks necessários por padrão. Se você não for um administrador, para configurar relatórios de inventário e registrar seu destino como um local externo, deverá ter as seguintes permissões:
  • Permissões do provedor de nuvem para configurar relatórios de inventário no bucket de origem ou contêiner.
  • Um dos seguintes privilégios Azure Databricks para registrar o destino de inventário como um local externo:
    • O CREATE EXTERNAL LOCATION privilégio no metastore e na credencial de armazenamento que ele faz referência.
    • O privilégio MANAGE no local externo.

• Um relatório de inventário configurado: configure um relatório de inventário de blobs Armazenamento do Azure em cada contêiner de origem que contém as tabelas que você deseja analisar. Use estas configurações:
  • Tipo de objeto: Blob
  • Tipos de blob: blobs de blocos e blobs de acréscimo
  • Subtipos: não habilitar incluir instantâneos ou incluir blobs excluídos
  • Frequência: Diariamente
  • Formato de exportação: Apache Parquet
  • Campos de inventário de blob: nome de inclusão, última modificação, comprimento do conteúdo, instantâneo, excluído e status da pasta HDI (CLIschemaFields: Name, Last-Modified, , Content-Length, Snapshot, , Deleted, ). hdi_isfolder Sem eles, o comando não pode calcular a saída correta.

• Um local externo para o relatório de inventário: você deve ter acesso de leitura em Azure Databricks ao caminho de destino do relatório de inventário.

  • Se o caminho não estiver em um local externo existente, registre-o como um local externo primeiro. Consulte Conectar-se a um local externo do Azure Data Lake Storage Gen2 (ADLS Gen2).

• Privilégios para executar o comando: você deve ter o READ FILES privilégio no local externo em Azure Databricks que apoia o destino do relatório de inventário, além dos privilégios existentes na tabela que você analisa.

Para localizar o bucket de origem ou o contêiner de uma tabela, execute DESCRIBE TABLE EXTENDED e verifique o Location campo na saída. Para exibições materializadas e tabelas de streaming, você deve usar DESCRIBE EXTENDED para localizar o local de armazenamento real. Você deve verificar se o relatório de inventário está configurado nesse bucket de origem ou contêiner.

Erros de relatório de inventário obsoleto

O comando pesquisa o relatório de inventário completo mais recente gerado nos últimos 14 dias. Se não encontrar nenhum relatório nessa janela, o comando não computa métricas e retorna 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 esse erro, confirme se o bucket de origem ou contêiner gera relatórios de inventário no agendamento configurado e execute o comando novamente depois que um novo relatório for gerado. Consulte Pré-requisitos.

Considerações sobre o tipo de tabela

Para exibiçõ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 rasos, total_bytes inclui apenas os próprios metadados do clone e arquivos de log Delta, excluindo arquivos de tabela de origem. active_bytes é zero porque o clone faz referência aos arquivos de dados da tabela de origem.

Exemplos

Métricas de armazenamento de computação

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

ANALYZE TABLE main.my_schema.my_table COMPUTE STORAGE METRICS;

O comando retorna a saída, como o 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)

A saída mostra:

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

Métricas de armazenamento de computação usando um relatório de inventário

O exemplo a seguir calcula as mesmas métricas de um relatório de inventário em vez de verificar os arquivos 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), a saída pode ser diferente de uma verificação 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)

Consulte Usar um relatório de inventário.

Métricas de armazenamento de computação para todas as tabelas em um catálogo

Para calcular as métricas de armazenamento para cada tabela em um catálogo, todas usando relatórios de inventário no mesmo destino, use um loop. O exemplo a seguir lista as tabelas usando um esquema de informações, 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()

LIMITAÇÕES DE USO DE INVENTÁRIO

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

• Essa cláusula é executada somente na computação clássica. Não há suporte para ele em computação sem servidor ou em sql warehouses do Databricks.
• Essa cláusula dá suporte apenas a tabelas de catálogo, incluindo tabelas gerenciadas e externas. Ele não dá suporte a tabelas delta lake baseadas em caminho, o que gera um erro: ANALYZE_TABLE_COMPUTE_STORAGE_METRICS_NOT_SUPPORTED condição de erro.
• Se o controle de versão do objeto estiver habilitado no bucket de origem ou no contêiner, os resultados não estarão garantidos como corretos.
• Se o local de armazenamento de uma tabela for alterado, reconfigure o relatório de inventário no novo bucket de origem ou contêiner. O local original não gera mais relatórios para a tabela. Por exemplo, converter uma tabela externa em uma tabela gerenciada altera o local de armazenamento da tabela. Consulte Converter tabelas externas ou estrangeiras do Delta Lake em tabelas gerenciadas pelo Unity Catalog.

Azure não dá suporte à configuração de inventário entre contas de armazenamento. Se suas tabelas abrangerem várias contas de armazenamento, cada conta de armazenamento precisará de sua própria configuração de inventário.

Notebook: Métricas de armazenamento de computação para várias tabelas

O bloco de anotações a seguir é executado ANALYZE TABLE ... COMPUTE STORAGE METRICS ... USING INVENTORY em um conjunto de tabelas do Catálogo do Unity e armazena os resultados em uma tabela delta lake. Use-o para analisar o armazenamento em várias tabelas ao mesmo tempo.

Métricas de armazenamento de computação para vários blocos de anotações de tabelas

Obter laptop

Declarações relacionadas

• ANALYZE TABLE … ESTATÍSTICAS DE COMPUTAÇÃO
• VACUUM
• Otimização preditiva para tabelas gerenciadas do Catálogo do Unity
• Trabalhar com o histórico de tabelas
• Converter tabelas delta lake externas ou estrangeiras em tabelas gerenciadas do Catálogo do Unity
• Locais externos