Partilhar via

Usar agrupamento líquido para tabelas

O Liquid Clustering substitui o particionamento de tabelas e ZORDER, simplificando as decisões de layout de dados e otimizando o desempenho das consultas. Ele fornece a flexibilidade para redefinir chaves de clustering sem reescrever dados existentes, permitindo que o layout de dados evolua junto com as necessidades analíticas ao longo do tempo. O clustering líquido aplica-se a Tabelas de Streaming e Visualizações Materializadas.

Importante

A agregação líquida está disponível para tabelas Delta Lake e em public preview para tabelas geridas do Apache Iceberg.

Para todas as tabelas Delta Lake com liquid clustering ativado, a Databricks recomenda o uso do Databricks Runtime 15.2 ou superior. O suporte ao Public Preview com limitações está disponível no Databricks Runtime 13.3 LTS e superior. A simultaneidade em nível de linha é suportada no Databricks Runtime 13.3 LTS e superior e está geralmente disponível no Databricks Runtime 14.2 e superior para todas as tabelas com vetores de exclusão habilitados. Veja Níveis de isolamento e conflitos de gravação em Azure Databricks.

Para todas as tabelas Apache Iceberg com "liquid clustering" ativado, é necessário o Databricks Runtime 16.4 LTS e versões superiores.

Para que serve o agrupamento de líquidos?

O Databricks recomenda o clustering líquido para todas as novas tabelas, que inclui Tabelas de Streaming (STs) e Visualizações Materializadas (MVs). Seguem-se alguns exemplos de cenários que beneficiam do clustering:

  • As tabelas são frequentemente filtradas por colunas de cardinalidade elevada.
  • Tabelas com distorção significativa na distribuição de dados.
  • Tabelas que crescem rapidamente e exigem esforço de manutenção e afinação.
  • Tabelas com requisitos de escrita simultânea.
  • Tabelas com padrões de acesso que se alteram ao longo do tempo.
  • Tabelas onde uma chave de partição típica pode deixar a tabela com muitas ou poucas partições.

Habilitar agrupamento líquido

Você pode habilitar o clustering líquido em uma tabela existente ou durante a criação da tabela. O clustering não é compatível com particionamento ou ZORDER, e requer que você use o Azure Databricks para gerenciar todas as operações de layout e otimização para dados em sua tabela. Depois de ativar o clustering de dados líquidos, execute as tarefas OPTIMIZE como de costume para agrupar dados incrementalmente. Consulte Como acionar clustering.

Para habilitar o agrupamento líquido, adicione a CLUSTER BY frase a uma instrução de criação de tabela, como nos exemplos abaixo:

Nota

No Databricks Runtime 14.2 e versões superiores, pode usar as APIs DataFrame e DeltaTable em Python ou Scala para ativar o clustering líquido em tabelas Delta Lake.

SQL

-- Create an empty Delta table
CREATE TABLE table1(col0 INT, col1 string) CLUSTER BY (col0);

-- Using a CTAS statement
CREATE EXTERNAL TABLE table2 CLUSTER BY (col0)  -- specify clustering after table name, not in subquery
LOCATION 'table_location'
AS SELECT * FROM table1;

-- Using a LIKE statement to copy configurations
CREATE TABLE table3 LIKE table1;

Para o Apache Iceberg, você deve desabilitar explicitamente vetores de exclusão e IDs de linha ao habilitar o Liquid Clustering em uma tabela Iceberg gerenciada.

Python

# Create an empty Delta table
(DeltaTable.create()
  .tableName("table1")
  .addColumn("col0", dataType = "INT")
  .addColumn("col1", dataType = "STRING")
  .clusterBy("col0")
  .execute())

# Using a CTAS statement
df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

# CTAS using DataFrameWriterV2
df = spark.read.table("table1")
df.writeTo("table1").using("delta").clusterBy("col0").create()

linguagem de programação Scala

// Create an empty Delta table
DeltaTable.create()
  .tableName("table1")
  .addColumn("col0", dataType = "INT")
  .addColumn("col1", dataType = "STRING")
  .clusterBy("col0")
  .execute()

// Using a CTAS statement
val df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

// CTAS using DataFrameWriterV2
val df = spark.read.table("table1")
df.writeTo("table1").using("delta").clusterBy("col0").create()

Na versão 16.0 e versões superiores do Databricks Runtime, pode criar tabelas com agrupamento líquido ativado usando escritas de streaming estruturado, como nos exemplos a seguir:

:::

SQL

CREATE TABLE table1 (
  col0 STRING,
  col1 DATE,
  col2 BIGINT
)
CLUSTER BY (col0, col1)
TBLPROPERTIES (
  'clusterByAuto' = 'true'
);

Python

(spark.readStream.table("source_table")
  .writeStream
  .clusterBy("column_name")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")
)

linguagem de programação Scala

spark.readStream.table("source_table")
  .writeStream
  .clusterBy("column_name")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Aviso

As tabelas Delta criadas com o clustering líquido ativado têm vários recursos da tabela Delta habilitados na criação e usam o gravador Delta versão 7 e o software leitor versão 3. Você pode substituir a ativação de alguns desses recursos. Consulte Sobrepor configuração padrão de funcionalidade (opcional).

As versões de protocolo de tabela não podem ser rebaixadas e as tabelas com clustering habilitado não são legíveis por clientes Delta Lake que não suportam todos os recursos de tabela de protocolo de leitor Delta habilitados. Consulte Compatibilidade de recursos e protocolos do Delta Lake.

Ative a clusterização de dados líquidos em uma tabela Delta não particionada existente com a seguinte sintaxe:

-- Alter an existing table
ALTER TABLE <table_name>
CLUSTER BY (<clustering_columns>)

Para o Apache Iceberg, você deve desabilitar explicitamente vetores de exclusão e IDs de linha ao habilitar o clustering líquido em uma tabela Iceberg gerenciada existente.

Importante

O comportamento padrão não aplica clustering a dados gravados anteriormente. Para forçar o reagrupamento de todos os registos, você deve usar OPTIMIZE FULL. Consulte Reagrupar forçadamente para todos os registos.

Para remover chaves de agrupamento, use a seguinte sintaxe:

ALTER TABLE table_name CLUSTER BY NONE;

Agrupamento automático de líquidos

No Databricks Runtime 15.4 LTS e versões superiores, você pode habilitar o clustering líquido automático para tabelas Delta geridas pelo Unity Catalog. Com o clustering líquido automático habilitado, o Azure Databricks escolhe chaves de cluster de forma inteligente para otimizar o desempenho da consulta. Você ativa o agrupamento automático de líquidos usando a cláusula CLUSTER BY AUTO.

Quando habilitadas, as operações automáticas de seleção de chaves e clustering são executadas de forma assíncrona como uma operação de manutenção e exigem que a otimização preditiva esteja habilitada para a tabela. Consulte Otimização preditiva para tabelas gerenciadas do Unity Catalog.

Para identificar chaves de clustering, o Azure Databricks analisa a carga de trabalho de consulta histórica da tabela e identifica as melhores colunas candidatas. As chaves de agrupamento são alteradas quando a economia de custos prevista das melhorias na eliminação de dados superam o custo do agrupamento de dados.

Se a maneira como você consulta seus dados muda ao longo do tempo ou o desempenho da consulta indica alterações em suas distribuições de dados, o cluster líquido automático seleciona novas chaves para otimizar o desempenho.

Se uma chave não foi selecionada por agrupamento líquido automático, o motivo pode ser:

  • A tabela é demasiado pequena para beneficiar do agrupamento líquido.
  • A tabela já tem um bom método de agrupamento de dados. Por exemplo, ele tem boas chaves que foram aplicadas uma vez antes, ou a ordem de inserção já funciona bem para o padrão de consulta dado, como dados inseridos em ordem cronológica e consultados no carimbo de data/hora.
  • A tabela não tem consultas frequentes.
  • Você não está usando o Databricks Runtime 15.4 LTS ou superior.

Você pode aplicar clustering líquido automático a todas as tabelas geridas do Unity Catalog, independentemente das características dos dados e das consultas. Esses recursos fornecem otimização inteligente do layout de dados com base em seus padrões de uso de dados, e a heurística decidirá se é econômico selecionar chaves de clustering.

Nota

Você pode ler ou gravar tabelas com clustering automático ativado em todas as versões do Databricks Runtime que suportam liquid clustering. No entanto, a seleção inteligente de chaves depende de metadados introduzidos no Databricks Runtime 15.4 LTS. Use o Databricks Runtime 15.4 LTS ou superior para garantir que as chaves selecionadas automaticamente beneficiem todas as suas cargas de trabalho e que essas cargas de trabalho sejam consideradas ao selecionar novas chaves.

Ativar ou desativar o agrupamento automático de líquidos

Para ativar ou desativar a aglomeração líquida automática em uma tabela nova ou existente, use a seguinte sintaxe:

SQL

-- Create an empty table.
CREATE OR REPLACE TABLE table1(column01 int, column02 string) CLUSTER BY AUTO;

-- Enable automatic liquid clustering on an existing table,
-- including tables that previously had manually specified keys.
ALTER TABLE table1 CLUSTER BY AUTO;

-- Disable automatic liquid clustering on an existing table.
ALTER TABLE table1 CLUSTER BY NONE;

-- Disable automatic liquid clustering by setting the clustering keys
-- to chosen clustering columns or new columns.
ALTER TABLE table1 CLUSTER BY (column01, column02);

Nota

Se executar CREATE OR REPLACE table_name sem especificar CLUSTER BY AUTO e a tabela já existir e tiver o clustering líquido automático ativado, a configuração AUTO e as colunas de clustering para a tabela (se aplicadas) serão preservadas quando a tabela for substituída. A otimização preditiva também mantém a carga de trabalho de consulta histórica para esta tabela para identificar as melhores chaves de clustering.

Python

df = spark.read.table("table1")
df.write
  .format("delta")
  .option(“clusterByAuto”, “true”)
  .saveAsTable(...)

# To set clustering columns and auto, which serves as a way to give a hint
# for the initial selection.
df.write
  .format("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option(“clusterByAuto”, “true”)
  .saveAsTable(...)

# Using DataFrameWriterV2
df.writeTo(...).using("delta")
  .option(“clusterByAuto”, “true”)
  .create()

# To set clustering columns and auto, which serves as a way to give a hint
# for the initial selection.
df.writeTo(...).using("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option(“clusterByAuto”, “true”)
  .create()

# Similar syntax can also be used to set clusterByAuto for streaming tables.
spark.readStream.table("source_table")
  .writeStream
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

# Or to specify a hint for the clustering columns by specifying both auto and columns together
spark.readStream.table("source_table")
  .writeStream
 .clusterBy("column1", "column2")
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Nota

A API Python está disponível no Databricks Runtime 16.4 e superior.

Quando .clusterBy utilizado em conjunto com .option('clusterByAuto', 'true), então:

  • Se isso definir o agrupamento líquido automático pela primeira vez, ele sempre respeitará a entrada manual e definirá as colunas de agrupamento em .clusterBy.
  • Se esta já é uma tabela com agrupamento líquido automático, uma dica usando .clusterBy pode ser aceita uma vez. Por exemplo, as colunas especificadas por .clusterBy só serão definidas se a tabela não tiver colunas de agrupamento já definidas, seja por você ou por agrupamento líquido automático.

Você só pode usar Python ao criar ou substituir uma tabela. Use SQL para alterar o clusterByAuto status de uma tabela existente.

Verificar se o clustering automático está ativado

Para verificar se uma tabela tem o agrupamento automático de líquidos habilitado, use DESCRIBE TABLE ou SHOW TBLPROPERTIES.

Se o agrupamento automático de líquidos estiver habilitado, a clusterByAuto propriedade será definida como true. A clusteringColumns propriedade mostra as colunas de clustering atuais que foram selecionadas automática ou manualmente.

Limitações

O agrupamento automático de líquidos não está disponível para o Apache Iceberg.

Substituir a ativação de recurso padrão (opcional)

Você pode substituir o comportamento padrão que habilita os recursos da tabela Delta durante a ativação do liquid clustering. Isso impede que os protocolos de leitor e gravador associados a esses recursos de tabela sejam atualizados. Você deve ter uma tabela existente para concluir as seguintes etapas:

  1. Use ALTER TABLE para definir a propriedade da tabela que desativa uma ou mais funcionalidades. Por exemplo, para desativar vetores de exclusão, execute o seguinte:

    ALTER TABLE table_name SET TBLPROPERTIES ('delta.enableDeletionVectors' = false);

  2. Ative o agrupamento líquido na tabela executando o seguinte:

    ALTER TABLE <table_name>
CLUSTER BY (<clustering_columns>)

A tabela a seguir fornece informações sobre os recursos Delta que você pode substituir e como a habilitação afeta a compatibilidade com as versões do Databricks Runtime.

Recurso Delta Compatibilidade de tempo de execução Propriedade para substituir a habilitação Impacto da incapacidade no agrupamento de líquidos
Vetores de eliminação As leituras e gravações requerem o Databricks Runtime 12.2 LTS e superior. 'delta.enableDeletionVectors' = false A simultaneidade em nível de linha é desabilitada, tornando as transações e as operações de cluster mais propensas a conflitos. Consulte Conflitos de gravação com simultaneidade em nível de linha.
DELETE, MERGEe UPDATE os comandos podem ser executados mais lentamente.
Rastreamento de fila As gravações requerem o Databricks Runtime 13.3 LTS e superior. Pode ser lido a partir de qualquer versão do Databricks Runtime. 'delta.enableRowTracking' = false A simultaneidade em nível de linha é desabilitada, tornando as transações e as operações de cluster mais propensas a conflitos. Consulte Conflitos de gravação com simultaneidade em nível de linha.
Pontos de verificação V2 As leituras e gravações requerem o Databricks Runtime 13.3 LTS e superior. 'delta.checkpointPolicy' = 'classic' Sem impacto no comportamento de agrupamento de líquidos.

Escolher chaves de clustering

O Databricks recomenda o agrupamento líquido automático para tabelas suportadas. Consulte Agrupamento automático de líquidos.

O Databricks recomenda escolher chaves de clustering com base nas colunas mais usadas nos filtros de consulta. As chaves de agrupamento podem ser definidas em qualquer ordem. Se duas colunas estiverem altamente correlacionadas, você só precisará incluir uma delas como uma chave de clustering.

Você pode especificar até quatro chaves de clustering. Para tabelas menores (menos de 10 TB), o uso de mais chaves de cluster (por exemplo, quatro) pode prejudicar o desempenho ao filtrar em uma única coluna em comparação com o uso de menos chaves de cluster (por exemplo, duas). No entanto, à medida que o tamanho da tabela aumenta, a diferença de desempenho com o uso de mais chaves de cluster para consultas de coluna única torna-se insignificante.

Você só pode especificar colunas que tenham estatísticas coletadas como chaves de agrupamento. Por predefinição, as primeiras 32 colunas numa tabela Delta têm estatísticas recolhidas. Consulte Especificação das colunas de estatísticas delta.

O clustering suporta os seguintes tipos de dados para chaves de clustering:

  • Data
  • Data e Hora
  • TimestampNTZ (requer Databricks Runtime 14.3 LTS ou superior)
  • Cordão
  • Número inteiro
  • Longo
  • Curto
  • Flutuar
  • Duplo
  • Decimal
  • byte

Se você estiver convertendo uma tabela existente, considere as seguintes recomendações:

Técnica atual de otimização de dados Recomendação para chaves de agrupamento
Particionamento estilo colmeia Utilize colunas de partição como chaves de agrupamento.
Indexação de ordem Z Use as ZORDER BY colunas como chaves de agrupamento.
Particionamento estilo colmeia e ordem Z Utilize colunas de partição e ZORDER BY colunas como chaves de agrupamento.
Colunas geradas para reduzir a cardinalidade (por exemplo, data extraída de um carimbo de data/hora) Use a coluna original como uma chave de clustering e não crie uma coluna gerada.

Gravar dados em uma tabela clusterizada

Para gravar em uma tabela Delta agrupada, você deve usar um cliente escritor Delta que ofereça suporte a todos os recursos de tabelas do protocolo de gravação Delta usados pelo agrupamento líquido. Para gravar numa tabela Iceberg clusterizada, pode-se usar a API de Catálogo REST do Unity Catalog. No Azure Databricks, você deve usar o Databricks Runtime 13.3 LTS e superior.

As operações que se agrupam durante a escrita incluem o seguinte:

  • INSERT INTO operações
  • CTAS e RTAS declarações
  • COPY INTO a partir do formato Parquet
  • spark.write.mode("append")

As gravações de Streaming estruturado nunca acionam clustering na gravação. Aplicam-se limitações adicionais. Consulte Limitações.

O clustering na gravação só é acionado quando os dados na transação atingem um limite de tamanho. Esses limites variam de acordo com o número de colunas de clustering e são menores para tabelas geridas pelo Unity Catalog do que as outras tabelas Delta.

Número de colunas de agrupamento Tamanho limite para tabelas gerenciadas do Unity Catalog Tamanho limite para outras tabelas Delta
1 64 MB 256MB
2 256MB 1 GB
3 512 MB 2 GB
4 1 GB 4 GB

Como nem todas as operações aplicam "liquid clustering", o Databricks recomenda a execução frequente de OPTIMIZE para garantir que todos os dados sejam agrupados de forma eficiente.

Como acionar o agrupamento

A otimização preditiva executa automaticamente comandos OPTIMIZE para tabelas ativadas. Consulte Otimização preditiva para tabelas gerenciadas do Unity Catalog. Ao usar a otimização preditiva, o Databricks recomenda desabilitar todos os trabalhos agendados OPTIMIZE .

Para acionar o clustering, você deve usar o Databricks Runtime 13.3 LTS ou superior. Use o OPTIMIZE comando na sua tabela:

OPTIMIZE table_name;

O agrupamento líquido é incremental, o que significa que os dados são reescritos apenas conforme necessário para acomodar aqueles que precisam ser agrupados. Os arquivos de dados com chaves de cluster que não correspondem aos dados a serem agrupados não são regravados.

Se você não estiver usando a otimização preditiva, o Databricks recomenda agendar trabalhos regulares OPTIMIZE para agrupar dados. Para tabelas com muitas atualizações ou inserções, o Databricks recomenda agendar uma OPTIMIZE tarefa a cada uma ou duas horas. Como o agrupamento de dados em estado líquido é incremental, a maioria dos trabalhos para tabelas clusterizadas é executada rapidamente.

Forçar o reagrupamento de todos os registos

No Databricks Runtime 16.0 e superior, você pode forçar o reagrupamento de todos os registros em uma tabela com a seguinte sintaxe:

OPTIMIZE table_name FULL;

Importante

A execução do OPTIMIZE FULL reagrupa todos os dados existentes conforme necessário. Para tabelas grandes que não foram agrupadas anteriormente nas chaves especificadas, essa operação pode levar horas.

Execute OPTIMIZE FULL quando ativares a aglomeração pela primeira vez ou alterares as chaves de aglomeração. Se você já executou OPTIMIZE FULL e não houve nenhuma alteração nas chaves de clustering, OPTIMIZE FULL será executado da mesma forma que OPTIMIZE. Nesse cenário, OPTIMIZE usa uma abordagem incremental e regrava apenas arquivos que não foram compactados anteriormente. Sempre use OPTIMIZE FULL para garantir que o layout de dados reflita as chaves de cluster atuais.

Ler dados de uma tabela agrupada

Você pode ler dados em uma tabela Delta clusterizada usando qualquer cliente Delta Lake que ofereça suporte a vetores de exclusão de leitura. Usando a API do catálogo REST do Iceberg, você pode ler dados em uma tabela Iceberg clusterizada.

SELECT * FROM table_name WHERE cluster_key_column_name = "some_value";

Alterar chaves de agrupamento

Você pode alterar as chaves de clustering de uma tabela a qualquer momento executando um ALTER TABLE comando, como no exemplo a seguir:

ALTER TABLE table_name CLUSTER BY (new_column1, new_column2);

Quando se alteram as chaves de clustering, as operações subsequentes OPTIMIZE e de gravação utilizam a nova abordagem de clustering, mas os dados existentes não são reescritos.

Você também pode desativar o clustering definindo as teclas como NONE, como no exemplo a seguir:

ALTER TABLE table_name CLUSTER BY NONE;

Definir chaves de cluster como NONE não reescreve dados que já foram clusterizados, mas impede que operações futuras OPTIMIZE usem chaves de clustering.

Usando agrupamento de líquidos de um motor externo

Você pode habilitar o agrupamento de líquidos em tabelas Iceberg gerenciadas a partir de mecanismos Iceberg externos. Para habilitar o clustering líquido, especifique colunas de partição ao criar uma tabela. O Unity Catalog interpreta as partições como chaves de clustering. Por exemplo, execute o comando abaixo no OSS Spark:

CREATE OR REPLACE TABLE main.schema.icebergTable
PARTITIONED BY c1;

Você pode desativar o agrupamento líquido:

ALTER TABLE main.schema.icebergTable DROP PARTITION FIELD c2;

Você pode alterar as chaves de clustering usando a evolução da partição Iceberg:

ALTER TABLE main.schema.icebergTable ADD PARTITION FIELD c2;

Se você especificar uma partição usando uma transformação de bucket, o Unity Catalog soltará a expressão e usará a coluna como uma chave de clustering:

CREATE OR REPLACE TABLE main.schema.icebergTable
PARTITIONED BY (bucket(c1, 10));

Veja como a tabela está agrupada

Você pode usar DESCRIBE comandos para ver as chaves de clustering de uma tabela, como nos exemplos a seguir:

DESCRIBE TABLE table_name;

DESCRIBE DETAIL table_name;

Compatibilidade para tabelas com agrupamento líquido

As tabelas criadas com clustering líquido no Databricks Runtime 14.1 e posterior usam pontos de verificação v2 por predefinição. Você pode ler e escrever tabelas com pontos de verificação v2 no Databricks Runtime 13.3 LTS e superior.

Você pode desabilitar os checkpoints v2 e fazer downgrade dos protocolos de tabela para ler tabelas com liquid clustering no Databricks Runtime 12.2 LTS ou posterior. Consulte Eliminar uma funcionalidade de tabela Delta Lake e o protocolo de rebaixamento de tabela.

Limitações

As seguintes limitações existem:

  • No Databricks Runtime 15.1 e versões anteriores, o clustering na gravação não oferece suporte a consultas de origem que incluem filtros, uniões ou agregações.
  • As cargas de trabalho de Streaming Estruturado não suportam clustering-on-write.
  • No Databricks Runtime 15.4 LTS e inferiores, não é possível criar uma tabela com liquid clustering ativado usando uma operação de escrita de streaming estruturado. Pode usar Structured Streaming para gravar dados numa tabela existente com o liquid clustering ativado.
  • A simultaneidade em nível de linha não é suportada em tabelas Iceberg gerenciadas, pois vetores de exclusão e rastreamento de linha não são suportados em tabelas Iceberg.