Usar clustering líquido para tabelas

clustering líquido é uma técnica de otimização de disposição de dados que substitui o particionamento de tabela e ZORDER. Simplifica o gerenciamento de tabelas e otimiza o desempenho das consultas, organizando automaticamente os dados com base em uma chave clustering .

Ao contrário do particionamento tradicional, você pode redefinir a chave clustering sem sobrescrever os dados existentes. Isso permite que sua disposição de dados evolua juntamente com as necessidades analíticas em constante mudança. clustering líquido se aplica tanto a tabelas de transmissão quanto a visões materializadas.

important

clustering líquido está geralmente disponível para tabelas Delta Lake e em versão prévia pública para gerenciar tabelas Apache Iceberg . Para tabelas Delta Lake , o suporte ao GA está disponível no Databricks Runtime 15.2 e versões superiores. A Databricks recomenda o uso da versão mais recente do Databricks Runtime para obter o melhor desempenho. Para tabelas Apache Iceberg , é necessário Databricks Runtime 16.4 LTS ou superior.

Quando usar clusteringlíquida

Databricks recomenda o uso clustering líquido para todas as novas tabelas, incluindo tabelas de transmissão e visões materializadas. Os seguintes cenários se beneficiam particularmente do clustering:

• Tabelas que são frequentemente filtradas por colunas de alta cardinalidade.
• Tabelas que apresentam assimetria na distribuição dos dados.
• Tabelas que crescem rapidamente e exigem manutenção e ações de ajuste.
• Tabelas que possuem requisitos de escrita concorrentes.
• Tabelas cujos padrões de acesso mudam ao longo do tempo.
• Tabelas em que uma chave de partição típica poderia deixar a tabela com muitas ou poucas partições.

Habilitar líquido clustering

Você pode habilitar clustering líquido em uma tabela não particionada existente ou durante a criação da tabela. O agrupamento não é compatível com o particionamento ou ZORDER. Databricks recomenda permitir que a plataforma gerencie todas as operações de otimização e organização dos dados em sua tabela. Após habilitar clustering líquido, execute OPTIMIZE Job para cluster dados incrementalmente. Consulte Como ativar clustering.

Criar tabelas com clustering

Para habilitar clustering líquido, adicione a frase CLUSTER BY a uma instrução de criação de tabela, como nos exemplos abaixo. No Databricks Runtime 14.2 e versões superiores, você pode usar API APIs DataFrame DeltaTable em Python ou Scala para habilitar clustering líquido para tabelas Delta Lake .

SQL

SQL

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

-- Create table from existing data with clustering
-- Note: CLUSTER BY must appear after table name, not in SELECT clause
CREATE TABLE table2 CLUSTER BY (col0)
AS SELECT * FROM table1;

-- Copy table structure including clustering configuration
CREATE TABLE table3 LIKE table1;

Python

Python

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

# Create clustered table from existing DataFrame
df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

# Alternative: DataFrameWriterV2 API (DBR 14.2+)
df = spark.read.table("table1")
df.writeTo("table1").using("delta").clusterBy("col0").create()

Scala

Scala

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

// Create clustered table from existing DataFrame
val df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

// Alternative: DataFrameWriterV2 API (DBR 14.2+)
val df = spark.read.table("table1")
df.writeTo("table1").using("delta").clusterBy("col0").create()

No Databricks Runtime 16.0 e versões superiores, você pode criar tabelas com clustering líquido habilitado usando gravações de transmissão estruturada. Databricks recomenda o uso Databricks Runtime 16.4 ou superior para obter o melhor desempenho, como nos exemplos a seguir:

SQL

SQL

CREATE TABLE table1 (
  col0 STRING,
  col1 DATE,
  col2 BIGINT
)
CLUSTER BY (col0, col1);

Python

Python

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

Scala

Scala

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

atenção

As tabelas Delta com clustering líquido ativado usam o gravador Delta versão 7 e o leitor versão 3. Os clientes Delta que não suportam esses protocolos não podem ler essas tabelas. Não é possível fazer downgrade da versão do protocolo da tabela. Consulte a compatibilidade e os protocolos de recursosDelta Lake.

Para substituir a ativação default de recursos (como vetores de exclusão), consulte Substituir a ativação default de recursos (opcional).

Habilitar em tabelas existentes

Ative o clustering líquido em uma tabela Delta existente e não particionada usando a seguinte sintaxe:

SQL

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

Para Apache Iceberg, o senhor deve desativar explicitamente os vetores de exclusão e os Row IDs ao ativar o líquido clustering em uma tabela gerenciar Iceberg existente.

nota

O comportamento default não se aplica clustering aos dados gravados anteriormente. Para forçar o reclustamento de todos os registros, você deve usar OPTIMIZE FULL. Consulte Force reclustering para todos os registros.

Remover chave clustering

Para remover a chave clustering, use a seguinte sintaxe:

SQL

ALTER TABLE table_name CLUSTER BY NONE;

Escolha a tecla clustering

dica

Databricks recomenda o uso clustering líquido automático para tabelas compatíveis, que seleciona de forma inteligente a chave clustering com base nos seus padrões de consulta. Veja clusteringautomático de líquidos.

diretrizes de seleção principais

Ao especificar manualmente a chave clustering , escolha as colunas com base nas colunas mais frequentemente usadas nos filtros de consulta. Você pode definir a chave clustering em qualquer ordem. Se duas colunas estiverem altamente correlacionadas, você só precisa incluir uma delas como key clustering .

Você pode especificar até quatro chaves clustering . Para tabelas menores (menos de 10 TB), usar mais chaves clustering pode degradar o desempenho ao filtrar em uma única coluna. Por exemplo, a filtragem com quatro chaves tem um desempenho pior do que a filtragem com duas chaves. No entanto, à medida que o tamanho da tabela aumenta, essa diferença de desempenho torna-se insignificante para consultas de coluna única.

A chave de agrupamento deve ser composta por colunas que contenham estatísticas coletadas. Por default, as estatísticas são coletadas nas primeiras 32 colunas de uma tabela Delta . Consulte Especificar colunas de estatísticas Delta.

Tipos de dados suportados

O agrupamento suporta estes tipos de dados para a chave clustering :

• Data
• Carimbo de data/hora
• TimestampNTZ (Databricks Runtime 14.3 LTS e versões superiores)
• String
• Inteiro, Longo, Curto, Byte
• Número de ponto flutuante, número de ponto flutuante duplo, decimal

Migrando de particionamento ou Z-order

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 clustering
Particionamento no estilo Hive	Utilizar colunas de partição como chaves de cluster.
indexação de Z-order	Utilizar as colunas ZORDER BY como chaves de clustering.
Particionamento no estilo Hive e Z-order	Utilizar as colunas de partição e as colunas ZORDER BY como chaves de agrupamento.
Colunas geradas para reduzir a cardinalidade (por exemplo, data para um registro de data e hora)	Use a coluna original como clustering key, e não crie uma coluna gerada.

Líquido automático clustering

No Databricks Runtime 15.4 LTS e versões superiores, você pode habilitar o clustering automático líquido para tabelas Delta Unity Catalog . clustering líquido automático permite que Databricks escolha de forma inteligente a chave clustering para otimizar o desempenho da consulta, usando a cláusula CLUSTER BY AUTO .

Como funciona o clustering automático de líquidos

clustering automático de líquidos proporciona otimização inteligente com base nos seus padrões de utilização:

• Requer otimização preditiva : seleção automática key e execução de operações clustering de forma assíncrona como operações de manutenção. Consulte Otimização preditiva para Unity Catalog gerenciar tabelas.
• Analisa a carga de trabalho de consultas : Databricks analisa o histórico de carga de trabalho de consultas da tabela e identifica as melhores colunas candidatas para clustering.
• Adapta-se às mudanças : Se os seus padrões de consulta ou distribuições de dados mudarem ao longo do tempo, clustering líquido automático seleciona uma nova chave para otimizar o desempenho.
• Seleção com foco em custos : Databricks altera a chave clustering somente quando a economia de custos prevista com as melhorias no descarte de dados supera o custo do clustering de dados.

clustering automático de líquidos pode não selecionar a chave pelos seguintes motivos:

• A tabela é muito pequena para se beneficiar do clustering líquido.
• A tabela já possui um esquema clustering eficaz, seja por meio de chave manual anterior ou por ordem de inserção natural que corresponde aos padrões de consulta.
• A tabela não tem consultas frequentes.
• O senhor não está usando Databricks Runtime 15.4 LTS ou acima.

Você pode aplicar clustering líquido automático a todas as tabelas Unity Catalog , independentemente das características dos dados e da consulta. A heurística decide se é economicamente vantajoso selecionar a chave de clustering .

Compatibilidade de versão DBR

Você pode ler ou gravar tabelas com clustering automático ativado em todas as versões Databricks Runtime que suportam clustering líquido. No entanto, a seleção inteligente key depende dos metadados introduzidos no Databricks Runtime 15.4 LTS.

Utilize Databricks Runtime 15.4 LTS ou superior para garantir que a chave selecionada automaticamente beneficie todas as suas cargas de trabalho e que essas cargas de trabalho sejam consideradas ao selecionar uma nova chave.

Ativar ou desativar o líquido automático clustering

Para ativar ou desativar o clustering líquido automático em uma tabela nova ou existente, use a seguinte sintaxe:

SQL

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);

Se você 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 será desativada e as colunas clustering não serão preservadas. Para preservar clustering líquido automático e quaisquer colunas clustering previamente selecionadas, inclua CLUSTER BY AUTO na instrução replace. Quando preservada, a otimização preditiva mantém o histórico de consultas da tabela para identificar a melhor chave clustering .

Python

Python

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

# Set clustering columns and auto to provide a hint for initial selection
df.write
  .format("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option("clusterByAuto", "true")
  .saveAsTable(...)

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

# Set clustering columns and auto to provide a hint for initial selection
df.writeTo(...).using("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option("clusterByAuto", "true")
  .create()

# Set clusterByAuto for streaming tables
spark.readStream.table("source_table")
  .writeStream
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

# Specify a hint for clustering columns with both auto and columns
spark.readStream.table("source_table")
  .writeStream
 .clusterBy("column1", "column2")
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

A API Python está disponível no Databricks Runtime 16.4 e versões superiores. Quando você usa .clusterBy junto com .option('clusterByAuto', 'true), o comportamento é o seguinte:

• Se isso configurar clustering líquido automático pela primeira vez, a entrada manual será sempre respeitada e as colunas clustering em .clusterBy serão definidas.
• Se esta já for uma tabela com clustering líquido automático, uma dica usando .clusterBy pode ser aceita uma vez. Por exemplo, as colunas especificadas por .clusterBy só são definidas se a tabela não tiver colunas clustering definidas anteriormente.

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

Verificar se o clustering automático está ativado

Para verificar se uma tabela tem o clustering líquido automático ativado, use DESCRIBE TABLE ou SHOW TBLPROPERTIES.

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

Limitações

O líquido automático clustering não está disponível para Apache Iceberg.

Gravar dados em uma tabela em cluster

Para gravar em uma tabela Delta em cluster, é necessário utilizar um cliente gravador Delta que suporte todos os recursos da tabela de protocolo de gravação Delta utilizados pelo liquid clustering. Para gravar em uma tabela Iceberg em cluster, é possível utilizar a API REST do Catálogo Iceberg do Unity Catalog. Em Databricks, é necessário utilizar Databricks Runtime 13.3 LTS e acima.

operações que suportam clustering em gravação

As operações que se agrupam na gravação incluem o seguinte:

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

Limite de tamanho para clustering

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

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

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

transmitir cargas de trabalho

spark.databricks.delta.liquid.eagerClustering.streaming.enabled As cargas de trabalho de transmissão estruturada suportam o recurso “ clustering ” (exclusão ao escrever) quando você define a configuração “ Spark ” (exclusão ao escrever) em “ true”. O agrupamento para essas cargas de trabalho só é acionado se pelo menos uma das últimas cinco atualizações de transmissão exceder um limite de tamanho da tabela acima.

Como acionar o clustering

Otimização preditiva executada automaticamente OPTIMIZE comando para tabelas habilitadas. Consulte Otimização preditiva para Unity Catalog gerenciar tabelas. Ao usar a otimização preditiva, o site Databricks recomenda desativar qualquer trabalho agendado do OPTIMIZE.

Para ativar clustering, você precisa usar Databricks Runtime 13.3 LTS ou superior. Databricks recomenda Databricks Runtime 17.2 ou superior para um desempenho OPTIMIZE mais rápido em tabelas grandes. Use o comando OPTIMIZE na sua tabela:

SQL

OPTIMIZE table_name;

clustering líquido é incremental , o que significa que OPTIMIZE apenas reescreve os dados conforme necessário para acomodar os dados que precisam clustering. OPTIMIZE não reescreve arquivos de dados com chave clustering que não correspondem aos dados que estão sendo agrupados.

Se o senhor não estiver usando a otimização preditiva, o site Databricks recomenda programar regularmente o OPTIMIZE Job para clusterizar os dados. Para tabelas com muitas atualizações ou inserções, o site Databricks recomenda programar um Job OPTIMIZE a cada uma ou duas horas. Como o clustering líquido é incremental, a maioria dos OPTIMIZE Job para tabelas em cluster é executada rapidamente.

Forçar o reclustamento para todos os registros

Em Databricks Runtime 16.0 e acima, é possível forçar o reclustering de todos os registros em uma tabela com a seguinte sintaxe:

SQL

OPTIMIZE table_name FULL;

important

A execução do OPTIMIZE FULL reagrupa todos os dados existentes conforme necessário. No caso de tabelas grandes que não tenham sido agrupadas anteriormente na chave especificada, essa operação pode levar horas.

execução OPTIMIZE FULL quando você habilita clustering pela primeira vez ou altera a chave clustering . Se você já executou OPTIMIZE FULL anteriormente e não houve alteração na chave clustering , a execução OPTIMIZE FULL é a mesma que a de OPTIMIZE. Neste cenário, OPTIMIZE usa uma abordagem incremental e reescreve apenas os arquivos que não foram compactados anteriormente. Use sempre OPTIMIZE FULL para garantir que a disposição dos dados reflita a chave de clustering atual.

Leia dados de uma tabela em cluster

Você pode ler dados em uma tabela Delta agrupada usando qualquer cliente Delta Lake que suporte a leitura de vetores de exclusão. Utilizando a API REST Catalog do Iceberg, você pode ler dados em uma tabela clusterizada do Iceberg. clustering líquido melhora o desempenho das consultas através da omissão automática de dados ao filtrar pela chave de clustering .

SQL

SELECT * FROM table_name WHERE cluster_key_column_name = "some_value";

gerenciar chave clustering

Veja como uma tabela é agrupada.

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

SQL

DESCRIBE TABLE table_name;

DESCRIBE DETAIL table_name;

Alterar a chave clustering

Você pode alterar as chaves de clustering das tabelas quando quiser, basta executar um comando ALTER TABLE , como no exemplo a seguir:

SQL

ALTER TABLE table_name CLUSTER BY (new_column1, new_column2);

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

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

SQL

ALTER TABLE table_name CLUSTER BY NONE;

Definir a chave cluster como NONE não reescreve os dados agrupados, mas impede que futuras operações OPTIMIZE usem a chave clustering .

Utilize clustering de líquidos a partir de um mecanismo externo.

O senhor pode ativar o clustering líquido para gerenciar tabelas do Iceberg a partir de mecanismos externos do Iceberg. Para ativar o clustering líquido, especifique colunas de partição ao criar uma tabela. Unity Catalog interpreta as partições como clustering key. Por exemplo, executar o comando abaixo no OSS Spark:

SQL

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

O senhor pode desativar o clustering líquido:

SQL

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

O senhor pode alterar a chave clustering usando a evolução da partição Iceberg:

SQL

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

Se você especificar uma partição usando uma transformação de bucket, Unity Catalog descarta a expressão e usa a coluna como key clustering :

SQL

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

Compatibilidade para tabelas com clustering líquido

clustering líquido utiliza recursos de tabela Delta que exigem versões específicas Databricks Runtime para leitura e gravação. As tabelas criadas com clustering líquida no Databricks Runtime 14.1 e versões superiores usam pontos de verificação v2 por default. É possível ler e gravar tabelas com pontos de verificação v2 no Databricks Runtime 13.3 LTS e versões superiores.

O senhor pode desativar os pontos de verificação v2 e fazer o downgrade dos protocolos de tabela para ler tabelas com o líquido clustering em Databricks Runtime 12.2 LTS e acima. Consulte Drop a Delta Lake table recurso e downgrade table protocol.

Substituir default recurso enablement (opcional)

Você pode substituir a ativação default do recurso da tabela Delta durante a ativação clustering líquido. Isso impede que os protocolos de leitura e gravação associados a esses recursos de tabela sejam atualizados. Você precisa ter uma tabela existente para concluir os seguintes passos:

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

   SQL

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

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

   SQL

   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 ativação afeta a compatibilidade com as versões do Databricks Runtime.

Recurso do Delta	Compatibilidade de runtime	Propriedade de substituir a ativação	Impacto da desativação no clustering líquido
Vetores de deleção	Leituras e gravações requerem Databricks Runtime 12.2 LTS ou acima.	'delta.enableDeletionVectors' = false	Desativar vetores de exclusão desativa a concorrência em nível de linha, tornando as transações e as operações clustering mais propensas a entrar em conflito. Consulte Conflitos de escrita com concorrência em nível de linha. DELETEOs comandos MERGE e UPDATE podem ser executados mais lentamente.
Acompanhamento de linha	Gravações requerem Databricks Runtime 13.3 LTS ou superior. Pode ser lido de qualquer versão do Databricks Runtime.	'delta.enableRowTracking' = false	Desativar o acompanhamento de linhas desativa a concorrência em nível de linha, tornando as transações e as operações clustering mais propensas a entrar em conflito. Consulte Conflitos de escrita com concorrência em nível de linha.
Pontos de verificação V2	Leituras e gravações exigem o Databricks Runtime 13.3 LTS e superior.	'delta.checkpointPolicy' = 'classic'	Nenhum impacto no comportamento do clustering líquido.

Limitações

• DBR 15.1 e versões anteriores : o agrupamento na gravação não oferece suporte a consultas de origem que incluam filtros, junções ou agregações.
• DBR 15.4 LTS e versões anteriores : Não é possível criar uma tabela com clustering líquido ativado usando uma transmissão estruturada de gravação. Você pode usar a transmissão estruturada para gravar dados em uma tabela existente com clustering líquido ativado.
• Apache Iceberg v2 : A concorrência em nível de linha não é suportada no gerenciamento de tabelas Iceberg com Apache Iceberg v2, pois vetores de exclusão e acompanhamento de linhas não são suportados em tabelas Iceberg .