Descoberta de partições para tabelas externas

Este artigo descreve a estratégia de descoberta de partição padrão para tabelas externas do Unity Catalog e uma configuração opcional para habilitar um log de metadados de partição que torna a descoberta de partição consistente com o metastore do Hive.

O Databricks recomenda habilitar o registro de metadados de partição para melhorar as velocidades de leitura e o desempenho de consulta para tabelas externas do Unity Catalog com partições.

Qual é a estratégia de descoberta de partição padrão para o Unity Catalog?

Por padrão, o Unity Catalog lista recursivamente todos os diretórios no local da tabela para descobrir partições automaticamente. Para tabelas grandes com muitos diretórios de partição, isso pode aumentar a latência para muitas operações de tabela.

Usar o log de metadados de partição

No Databricks Runtime 13.3 LTS e superior, você pode, opcionalmente, habilitar o registro de metadados de partição, uma estratégia de descoberta de partição para tabelas externas registradas no Unity Catalog. Esse comportamento é consistente com a estratégia de descoberta de partição usada no metastore do Hive. Esse comportamento afeta apenas as tabelas externas do Unity Catalog que têm partições e usam Parquet, ORC, CSV, Avro ou JSON. O Databricks recomenda habilitar o novo comportamento para melhorar as velocidades de leitura e o desempenho da consulta para essas tabelas.

Importante

Tabelas com registro de metadados de partição habilitado demonstram uma mudança comportamental para a descoberta de partições. Em vez de verificar automaticamente o local da tabela em busca de partições, o Unity Catalog respeita apenas as partições registradas nos metadados da partição. Consulte Adicionar manualmente, descartar ou reparar metadados de partição.

Esse comportamento se tornará o padrão em uma versão futura do Databricks Runtime. As tabelas com esse recurso ativado só podem ser lidas ou gravadas usando o Databricks Runtime 13.3 LTS e superior.

Habilitar o registro de metadados de partição

Para habilitar o log de metadados de partição em uma tabela, defina a propriedade table ao criar uma tabela externa, conforme mostrado no exemplo a seguir:

CREATE OR REPLACE TABLE <catalog>.<schema>.<table-name>
USING <format>
PARTITIONED BY (<partition-column-list>)
TBLPROPERTIES ('partitionMetadataEnabled' = 'true')
LOCATION 'abfss://<bucket-path>/<table-directory>';

Depois de criar uma tabela com o registo de metadados de partição ativado, o Azure Databricks utiliza os metadados de partição para ler a tabela em todas as cargas de trabalho subsequentes.

Você também pode usar o Spark conf para habilitar metadados de partição para sua SparkSession atual. Quando habilitada, as tabelas externas criadas no SparkSession serão criadas com a propriedade da tabela de metadados de partição habilitada. O conf do Spark está desativado por padrão.

A sintaxe a seguir demonstra o uso de SQL para definir um conf do Spark em um bloco de anotações. Você também pode definir as configurações do Spark ao configurar a computação.

SET spark.databricks.nonDelta.partitionLog.enabled = true;

Você pode substituir o conf do Spark ativando ou desabilitando explicitamente a propriedade table quando uma tabela é criada.

Importante

Você só pode ler e gravar tabelas com o registro de metadados de partição habilitado no Databricks Runtime 13.3 LTS e superior. Para ler essas tabelas usando o Databricks Runtime 12.2 LTS, você deve soltar e recriar a tabela com a propriedade da tabela de metadados de partição desabilitada.

As tabelas externas não excluem arquivos de dados subjacentes quando você os solta. O Databricks recomenda o uso CREATE OR REPLACE da sintaxe para atualizar tabelas para usar o log de metadados de partição, como no exemplo a seguir:

CREATE OR REPLACE TABLE <catalog>.<schema>.<table-name>
USING <format>
PARTITIONED BY (<partition-column-list>)
LOCATION 'abfss://<bucket-path>/<table-directory>';

Você pode verificar se uma tabela foi criada usando metadados de partição:

• Verifique a seção de propriedades da tabela retornada por DESCRIBE EXTENDED table_name.
• Verifique os metadados da tabela com o Catalog Explorer.

As propriedades da tabela contêm partitionMetadataEnabled=true.

O Unity Catalog impõe regras sobre sobreposições de caminho para tabelas e volumes. Não é possível registrar uma nova tabela do Catálogo Unity em uma coleção de arquivos de dados se já existir uma tabela nesse local.

Trabalhar com tabelas com metadados de partição

O Databricks recomenda o uso de nomes de tabelas em todas as leituras e gravações em todas as tabelas registradas no Unity Catalog. Para tabelas com metadados de partição, isso garante que novas partições adicionadas a uma tabela se registrem no Unity Catalog e que as consultas na tabela leiam todas as partições registradas.

O uso de padrões baseados em caminho para leituras ou gravações pode resultar em partições ignoradas ou não registradas no metastore do Unity Catalog. Consulte Limitações.

Listar partições

Use o seguinte comando para mostrar todas as partições registradas no Unity Catalog como metadados de partição:

SHOW PARTITIONS <table-name>

Para verificar se uma única partição está registrada no Unity Catalog, use o seguinte comando:

SHOW PARTITIONS <table-name>
PARTITION (<partition-column-name> = <partition-column-value>)

Adicionar, soltar ou reparar manualmente metadados de partição

O Unity Catalog requer que todas as partições para tabelas externas estejam contidas no diretório registrado usando a cláusula durante o LOCATION registro da tabela.

Com os metadados de partição ativados, a descoberta automática de partições no local da tabela é desativada. Se sistemas externos gravarem dados no local da tabela ou se você usar gravações baseadas em caminho para adicionar ou substituir registros na tabela, você deverá reparar manualmente os metadados da partição.

O Azure Databricks usa o particionamento no estilo Hive para armazenar tabelas com suporte de Parquet, ORC, CSV e JSON. As partições no estilo Colmeia contêm pares chave-valor conectados por um sinal de igual no diretório de partição, por exemplo year=2021/month=01/.

Se sua tabela usa particionamento no estilo Hive, você pode usar MSCK REPAIR para sincronizar metadados de partição no Unity Catalog com partições que existem no local da tabela. Os exemplos de sintaxe a seguir demonstram operações comuns:

-- Add and remove parition metadata to match directories in table location
MSCK REPAIR TABLE <table_name> SYNC PARTITIONS;

-- Add partitions in the table location that are not registered as partition metadata
MSCK REPAIR TABLE <table_name> ADD PARTITIONS;

-- Drop partitions registered as partition metadata that are not in the table location
MSCK REPAIR TABLE <table_name> DROP PARTITIONS;

Ver REPAIR TABLE.

Especificar manualmente caminhos para outros tipos de partição

Se a tabela não usar particionamento no estilo Hive, você deverá especificar manualmente os locais das partições ao adicionar partições. A especificação manual de partições também pode reduzir a latência em comparação com a MSCK REPAIR sintaxe, especialmente para tabelas com um grande número de partições. O exemplo de sintaxe a seguir mostra a adição de uma partição:

ALTER TABLE <table-name>
ADD PARTITION (<partition-column-name> = <partition-column-value>)
LOCATION 'abfss://<bucket-path>/<table-directory>/<partition-directory>';

Você também pode usar ALTER TABLE a sintaxe para soltar, renomear, recuperar e definir locais para partições. Veja ALTER TABLE ... PARTITION.

Limitações

As seguintes limitações existem:

• Não é possível ler ou gravar em tabelas com metadados de partição habilitados usando o Databricks Runtime 12.2 LTS ou inferior.
• A leitura de uma tabela usando o caminho do diretório retorna todas as partições, incluindo as que foram adicionadas ou descartadas manualmente.
• Se você inserir ou substituir registros em uma tabela usando um caminho em vez de um nome de tabela, os metadados da partição não serão registrados.