Usar clustering líquido para tabelas

O "liquid clustering" é uma técnica de otimização de organização de dados que substitui o particionamento de tabela e ZORDER. Ele simplifica o gerenciamento de tabelas e otimiza o desempenho da consulta organizando dados automaticamente com base em chaves de clustering.

Ao contrário do particionamento tradicional, você pode redefinir chaves de clustering sem reescrever dados existentes. Isso permite que o layout de dados evolua junto com a alteração das necessidades analíticas. O clustering líquido se aplica a tabelas de streaming e exibições materializadas.

Quando usar clustering líquido

Databricks recomenda liquid clustering para todas as novas tabelas, incluindo tabelas de streaming e exibições materializadas. Os seguintes cenários se beneficiam particularmente do clustering:

• Consultas que filtram colunas de alta cardinalidade.
• Tabelas com distorção de dados pesadas.
• Tabelas de rápido crescimento que exigem esforço de manutenção e ajuste.
• Tabelas com requisitos de escrita simultânea.
• Tabelas com padrões de acesso variados ou alterados.
• Tabelas em que uma chave de partição típica pode retornar resultados de muitas ou poucas partições.

Habilitar o clustering líquido

Você pode habilitar o *liquid clustering* em uma tabela não particionada existente ou durante a criação da tabela. O clustering não é compatível com particionamento ou ZORDER. O Databricks recomenda permitir que a plataforma gerencie todas as operações de layout e otimização de dados em sua tabela. Depois de habilitar o liquid clustering, execute OPTIMIZE jobs para agrupar dados incrementalmente. Consulte Como acionar o clustering.

Criar tabelas com agrupamento

Para habilitar a clusterização líquida, adicione a CLUSTER BY expressão a uma instrução de criação de tabela, como nos exemplos abaixo. No Databricks Runtime 14.3 LTS e versões posteriores, você pode usar as APIs DataFrame e DeltaTable em Python ou Scala para habilitar o clustering liquid para tabelas do Delta Lake.

SQL

Para criar uma tabela vazia com clustering:

CREATE TABLE table1 (col0 INT, col1 STRING) CLUSTER BY (col0);

Para criar uma tabela com base em dados existentes com clustering, CLUSTER BY é necessário aparecer após o nome da tabela, não na SELECT cláusula:

CREATE TABLE table2 CLUSTER BY (col0)
AS SELECT * FROM table1;

Para copiar uma estrutura de tabela, incluindo sua configuração de clustering:

CREATE TABLE table3 LIKE table1;

Python

Para criar uma tabela vazia com clustering usando a DeltaTable API:

(DeltaTable.create()
  .tableName("table1")
  .addColumn("col0", dataType = "INT")
  .addColumn("col1", dataType = "STRING")
  .clusterBy("col0")
  .execute())

Para criar uma tabela de um DataFrame existente:

df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

Para criar uma tabela usando a DataFrameWriterV2 API (disponível no Databricks Runtime 14.2 e superior):

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

Scala

Para criar uma tabela vazia com clustering usando a DeltaTable API:

DeltaTable.create()
  .tableName("table1")
  .addColumn("col0", dataType = "INT")
  .addColumn("col1", dataType = "STRING")
  .clusterBy("col0")
  .execute()

Para criar uma tabela de um DataFrame existente:

val df = spark.read.table("table1")
df.write.clusterBy("col0").saveAsTable("table2")

Para criar uma tabela usando a DataFrameWriterV2 API (disponível no Databricks Runtime 14.2 e superior):

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

No Databricks Runtime 16.4 LTS e em versões posteriores, você pode criar tabelas com a clusterização líquida habilitada usando operações de gravação com o Structured Streaming, como nos exemplos a seguir:

SQL

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

Python

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

Scala

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

Habilitar em tabelas existentes

Para habilitar o agrupamento líquido em uma tabela existente do Delta Lake não particionada, faça o seguinte:

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

Para tabelas gerenciadas do Apache Iceberg, considere o seguinte:

• Para tabelas com a especificação v2, você deve desativar explicitamente os vetores de exclusão e o rastreamento de linhas ao habilitar o liquid clustering em uma tabela existente.
• Para tabelas com a especificação v3, não é necessário desativar esses recursos porque há suporte para vetores de exclusão e acompanhamento de linhas. Consulte Usar recursos do Apache Iceberg v3.

Converta uma tabela particionada em clusterização líquida

No Databricks Runtime 18.1 e versões posteriores, para converter uma tabela Delta Lake particionada existente em clusterização líquida, use REPLACE PARTITIONED BY WITH CLUSTER BY em uma instrução ALTER TABLE. A conversão minimiza o tempo de indisponibilidade para leitura e escrita e oferece suporte a tabelas externas e gerenciadas. Após a conversão, a tabela dá suporte a leituras com o Databricks Runtime 13.3 LTS e superior.

Os benefícios da conversão de tabelas particionadas em clustering líquido incluem:

• Melhorias de desempenho para tabelas que sofrem com a falta de dados ou o excesso de particionamento.
• Melhorias automáticas de desempenho, usando CLUSTER BY AUTO, para tabelas com padrões de consulta com alteração frequente.
• As colunas de clustering são flexíveis e simples de alterar, enquanto o particionamento é rígido e difícil de alterar.
• Redução de conflitos de gravação porque tabelas com liquid clustering permitem concorrência no nível da linha. Consulte simultaneidade em nível de linha.

Syntax

ALTER TABLE <table_name>
REPLACE PARTITIONED BY WITH CLUSTER BY [( <clustering_columns> ) | AUTO]

A CLUSTER BY cláusula dá suporte às seguintes opções:

• ( <clustering_columns> ): Especifica novas colunas de clustering. O Databricks recomenda manter as novas colunas de clustering semelhantes às colunas de partição originais. O uso de colunas muito diferentes aciona uma grande operação de reclusterização na primeira execução de OPTIMIZE.
• AUTO: usa as colunas de partição atuais como as colunas de clustering iniciais e permite que a otimização preditiva se adapte ao longo do tempo. Disponível apenas para tabelas gerenciadas no Unity Catalog. Consulte clusterização automática de líquidos.
• Nenhuma opção especificada: usa as colunas de partição atuais como as novas colunas de clustering.

Para obter diretrizes sobre como escolher chaves de clustering ao migrar de tabelas particionadas, consulte Migrando do particionamento ou da ordem Z.

Examples

Para agrupar em colunas diferentes daquelas usadas nas partições originais, como no caso de uma tabela particionada em (year, month, day), faça o seguinte:

ALTER TABLE t1 REPLACE PARTITIONED BY WITH CLUSTER BY (day, id);
OPTIMIZE t1;

Para usar o clustering líquido automático e começar com as colunas de partição atuais, faça o seguinte:

ALTER TABLE t2 REPLACE PARTITIONED BY WITH CLUSTER BY AUTO;

Para manter as colunas de partição atuais como colunas de clustering, faça o seguinte:

ALTER TABLE t3 REPLACE PARTITIONED BY WITH CLUSTER BY;

Manipular leituras e gravações simultâneas durante a conversão

Após a conversão, o Databricks Runtime 13.3 LTS e superior tem suporte para leituras e gravações. Azure Databricks recomenda o Databricks Runtime 15.4 LTS e superior para cargas de trabalho que leem ou gravam na tabela durante a conversão.

Consulte a tabela a seguir para saber como lidar com cargas de trabalho de leitura e gravação simultâneas durante a conversão:

Verificar ou reverter uma conversão

Para confirmar a conversão, execute DESCRIBE EXTENDED para ver as novas colunas de clustering. Execute DESCRIBE HISTORY para ver uma série de REORG operações, uma UPGRADE PROTOCOL operação e uma REPLACE PARTITIONED BY WITH CLUSTER BY operação.

Para reverter uma conversão, use RESTORE para retornar à versão anterior. Como alternativa, você pode reescrever a tabela usando REPLACE TABLE ... PARTITIONED BY (...) AS SELECT * FROM ....

Para reverter usando RESTORE, execute os seguintes comandos:

ALTER TABLE my_table CLUSTER BY NONE;
ALTER TABLE my_table UNSET TBLPROPERTIES ('delta.liquid.hierarchicalClusteringColumns');
RESTORE TABLE my_table TO VERSION AS OF <version_number_before_conversion>;

Consulte RESTORE.

Converta uma tabela particionada por uma coluna de registro de data/hora

Para converter uma tabela (t1) particionada por uma coluna de carimbo de data/hora (timestamp_col) e usar a coluna de carimbo de data/hora como uma chave de clustering, você deve definir configurações adicionais:

SET spark.databricks.delta.liquidConversion.statsGeneration.enabled = false;
ALTER TABLE t1 REPLACE PARTITIONED BY WITH CLUSTER BY (timestamp_col, id);
ANALYZE TABLE t1 COMPUTE DELTA STATISTICS;

Se você tentar converter uma coluna de partição timestamp em uma coluna de clusterização sem essas configurações, o comando gerará um erro:

ALTER TABLE REPLACE PARTITIONED BY WITH CLUSTER BY cannot auto-generate stats on table with column event_ts due to unsupported type: timestamp. Disable stats auto-generation by setting 'spark.databricks.delta.liquidConversion.statsGeneration.enabled' to 'false' and retry the command again. SQLSTATE: 42000

Limitações de conversão

As seguintes limitações se aplicam ao REPLACE PARTITIONED BY WITH CLUSTER BY comando de conversão:

• Não há suporte para tabelas de streaming e exibições materializadas criadas no Lakeflow Spark Declarative Pipelines. Para usar o agrupamento líquido, você deve atualizar a definição do pipeline para usar CLUSTER BY em vez de PARTITIONED BY.
• Não há suporte para tabelas que usam o Compartilhamento Delta com filtragem de partição. Para obter informações sobre a filtragem de partição para o Compartilhamento Delta, consulte Especificar partições de tabela a serem compartilhadas.

Remover chaves de clustering

Para remover chaves de agrupamento, utilize a seguinte sintaxe:

ALTER TABLE table_name CLUSTER BY NONE;

Escolher chaves de clustering

Escolha chaves de clustering com base nas colunas mais comumente usadas em filtros de consulta. As chaves certas melhoram significativamente o salto de dados e o desempenho das consultas.

Diretrizes principais de seleção

Quando você especificar manualmente as chaves de clustering, escolha as colunas com base naquelas mais frequentemente utilizadas em filtros de consulta. Você pode definir chaves de clustering 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 clustering pode prejudicar o desempenho ao filtrar em uma única coluna. Por exemplo, filtrar com quatro chaves tem um desempenho pior do que filtrar 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.

As chaves de clustering devem ser colunas que tenham estatísticas coletadas. Por padrão, as tabelas delta lake coletam estatísticas para as primeiras 32 colunas. Consulte Especificar colunas de estatísticas.

Tipos de dados com suporte

O clustering dá suporte a esses tipos de dados para chaves de agrupamento:

• Data (calendário)
• Carimbo de data/hora
• TimestampNTZ (Databricks Runtime 14.3 LTS e superior)
• String
• Inteiro, Longo, Curto, Byte
• Float, Double, Decimal (ou seja, Ponto Flutuante, Duplo, Decimal)

Você pode agrupar por StructField usando notação de ponto, como CLUSTER BY (struct_col.field). Campos aninhados de struct são compatíveis com qualquer nível de profundidade, como CLUSTER BY (struct_col.nested.field). O tipo de dados do campo deve ser um dos tipos com suporte na lista anterior.

Você não pode agrupar por qualquer um dos seguintes:

• Tipos complexos, como StructType, MapTypeou ArrayType
• MapType e ArrayType elementos, como map_col['key'], array_col[0]ou map_col.key.

Migrando do particionamento ou da ordem Z

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

Agrupamento automático de líquidos

No Databricks Runtime 15.4 LTS e versões posteriores, você pode habilitar a clusterização líquida automática para tabelas do Delta Lake gerenciadas pelo Unity Catalog. Para tabelas Apache Iceberg v3 gerenciadas pelo Unity Catalog, a clusterização líquida automática requer o Databricks Runtime 18.0 ou superior. O agrupamento automático de líquidos permite que o Azure Databricks escolha inteligentemente as chaves de agrupamento para otimizar o desempenho das consultas, usando a cláusula CLUSTER BY AUTO.

Como funciona o agrupamento líquido automático

A clusterização automática de dados requer otimização preditiva para a seleção automática de chaves e as operações de clusterização, e é executada de forma assíncrona. Consulte Otimização Preditiva para Tabelas Gerenciadas do Unity Catalog.

O agrupamento automático de dados líquidos aplica otimizações inteligentes com base nos seus padrões de uso:

• Analisa a carga de trabalho de consulta: o Azure Databricks analisa a carga de trabalho de consulta histórica da tabela e identifica as melhores colunas candidatas para clustering.
• Adapta-se às alterações: se seus padrões de consulta ou distribuições de dados forem alterados ao longo do tempo, o clustering líquido automático selecionará novas chaves para otimizar o desempenho.
• Seleção ciente de custos: o Azure Databricks altera as chaves de agrupamento somente quando a economia de custos prevista de melhorias ao ignorar dados supera o custo de agrupamento de dados.

O agrupamento automático de líquidos pode não selecionar chaves pelos seguintes motivos:

• A tabela é muito pequena para se beneficiar do clustering líquido.
• A tabela já possui um esquema de clustering eficaz, seja devido a chaves manuais previamente definidas ou a uma ordem de inserção natural que se alinha com os padrões das consultas.
• A tabela não tem consultas frequentes.
• Você não está usando o Databricks Runtime 15.4 LTS ou superior.

Você pode aplicar o agrupamento automático de dados líquidos para todas as tabelas gerenciadas pelo Unity Catalog, independentemente das características dos dados e das consultas. A heurística decide se é econômico selecionar chaves de clustering.

Compatibilidade de versão do Databricks Runtime

Você pode ler ou gravar tabelas com agrupamento automático habilitado em todas as versões do Databricks Runtime que dão suporte ao agrupamento líquido. No entanto, a seleção de chave inteligente 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.

Habilitar ou desativar o clustering líquido automático

SQL

Para criar uma tabela com clusterização líquida automática:

CREATE OR REPLACE TABLE table1 (column01 int, column02 string) CLUSTER BY AUTO;

Para habilitar o clustering líquido automático em uma tabela existente, incluindo tabelas com chaves especificadas manualmente:

ALTER TABLE table1 CLUSTER BY AUTO;

Para definir sugestões iniciais de colunas de clustering para a seleção de chaves, defina as chaves de clustering e depois habilite o clustering automático:

ALTER TABLE table1 CLUSTER BY (c1, c2);
ALTER TABLE table1 CLUSTER BY AUTO;

Como alternativa, use a API Python para definir dicas em uma única operação.

Para desativar o agrupamento automático de líquidos:

ALTER TABLE table1 CLUSTER BY NONE;

Para desativar o clustering líquido automático e especificar colunas de clustering:

ALTER TABLE table1 CLUSTER BY (column01, column02);

Se uma tabela existente tiver a clusterização líquida automática habilitada, executar CREATE OR REPLACE table_name sem CLUSTER BY AUTO desativa a clusterização automática e não preserva as colunas de clusterização. Para preservar o agrupamento líquido automático e quaisquer colunas selecionadas anteriormente, inclua CLUSTER BY AUTO na instrução replace. Com CLUSTER BY AUTO, a otimização preditiva usa o histórico da carga de trabalho de consultas da tabela para identificar as melhores chaves de clustering.

Python

A API Python está disponível no Databricks Runtime 16.4 e superior. Você só pode usar Python ao criar ou substituir uma tabela. Use o SQL para alterar o clusterByAuto status de uma tabela existente.

Para criar uma tabela com agrupamento líquido automático usando DataFrameWriter:

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

Para definir dicas iniciais de colunas de agrupamento para a seleção de chaves usando DataFrameWriter:

df.write
  .format("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option("clusterByAuto", "true")
  .saveAsTable(...)

Para criar uma tabela com agrupamento líquido automático usando DataFrameWriterV2:

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

Para definir dicas iniciais de colunas de agrupamento para a seleção de chaves usando DataFrameWriterV2:

df.writeTo(...).using("delta")
  .clusterBy("clusteringColumn1", "clusteringColumn2")
  .option("clusterByAuto", "true")
  .create()

Para criar uma tabela de streaming com clusterização líquida automática:

spark.readStream.table("source_table")
  .writeStream
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Para definir dicas iniciais de colunas de agrupamento para a seleção de chaves em uma tabela de streaming:

spark.readStream.table("source_table")
  .writeStream
  .clusterBy("column1", "column2")
  .option("clusterByAuto", "true")
  .option("checkpointLocation", checkpointPath)
  .toTable("target_table")

Quando você usa .clusterBy para instruções de seleção da chave de cluster em conjunto com .option('clusterByAuto', 'true'), o comportamento é o seguinte:

• Se esta for a primeira vez que o clustering líquido automático é definido, as colunas de clustering são definidas para as colunas especificadas em .clusterBy.
• Se esta for uma tabela existente com agrupamento líquido automático habilitado, a dica .clusterBy é aceita apenas uma vez. Por exemplo, as colunas especificadas por .clusterBy só serão definidas se a tabela não tiver colunas de clustering definidas.

Verificar se o clustering automático está habilitado

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

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

Limitations

A clusterização líquida automática não está disponível para tabelas gerenciadas do Apache Iceberg v2. Há suporte para tabelas gerenciadas do Apache Iceberg v3 no Databricks Runtime 18.0 e superior.

Gravar dados em uma tabela clusterizada

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

Operações que oferecem suporte ao clustering durante a gravação

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

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

Limites de tamanho para agrupamento

O clustering na gravação só dispara 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 menores para tabelas gerenciadas do Unity Catalog do que para outras tabelas do Delta Lake.

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

Tarefas de streaming

As cargas de trabalho de streaming estruturadas dão suporte ao agrupamento na escrita quando você define a configuração spark.databricks.delta.liquid.eagerClustering.streaming.enabled do Spark como true. A clusterização dessas cargas de trabalho só é disparada se pelo menos uma das últimas cinco atualizações de streaming exceder um limite de tamanho conforme a tabela acima.

Como acionar clustering

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

Para disparar o clustering, você deve usar o Databricks Runtime 13.3 LTS ou superior. O Databricks recomenda o Databricks Runtime 17.3 LTS e superior para obter um desempenho mais rápido OPTIMIZE em tabelas grandes. Use o OPTIMIZE comando em sua tabela:

OPTIMIZE table_name;

O agrupamento líquido é incremental, o que significa que OPTIMIZE só reescreve os dados conforme necessário para acomodar dados que precisam de agrupamento. OPTIMIZE não reescreve arquivos de dados com chaves de clustering que não correspondem aos dados que estão sendo clusterizados. Veja Forçar reagrupamento.

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

Forçar o reagrupamento

No Databricks Runtime 16.4 LTS e versões posteriores, você pode forçar a reclusterização de todos os registros em uma tabela com a seguinte sintaxe:

OPTIMIZE table_name FULL;

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

Reagrupamento parcial

No Databricks Runtime 18.1 e versões superiores, você pode forçar o reagrupamento para um subconjunto de registros usando OPTIMIZE FULL WHERE <predicate>. Um arquivo é incluído se alguma parte de seu intervalo se sobrepor ao predicado. Consulte Parâmetros.

OPTIMIZE events FULL WHERE event_date >= '2025-01-01';

Ler dados de uma tabela clusterizada

Você pode ler dados em uma tabela do Delta Lake clusterizado usando qualquer cliente Delta Lake que dê suporte à leitura de vetores de exclusão. Usando a API do Catálogo REST do Iceberg, você pode ler dados em uma tabela agrupada do Iceberg. O clustering líquido melhora o desempenho da consulta por meio do salto automático de dados ao filtrar as chaves de clustering.

SELECT * FROM table_name WHERE cluster_key_column_name = "some_value";

Gerenciar chaves de clustering

Veja como uma tabela é 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;

Alterar chaves de clustering

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

ALTER TABLE table_name CLUSTER BY (new_column1, new_column2);

Quando você altera as chaves de clustering, as operações de OPTIMIZE e gravação subsequentes usam a nova abordagem de clustering, mas os dados existentes não são regravados. Para reescrever os dados existentes com as chaves de clustering atualizadas, consulte Forçar a reclusterização.

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

ALTER TABLE table_name CLUSTER BY NONE;

Definir chaves de cluster para NONE não envolve reescrever dados clusterizados, mas impede que operações futuras OPTIMIZE utilizem chaves de clusterização.

Usar clusterização líquida de um mecanismo externo

Você pode habilitar o clustering líquido em tabelas Iceberg gerenciadas a partir de mecanismos do Iceberg externos. Para habilitar o clustering líquido, especifique colunas de partição ao criar uma tabela. O Catálogo do Unity 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;

Para desativar o agrupamento de líquidos:

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

Para alterar as chaves de clustering usando a evolução da partição do Iceberg:

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

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

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

Compatibilidade para tabelas com o clustering líquido

O clustering líquido usa recursos de tabela do Delta Lake que exigem versões específicas do Databricks Runtime para leitura e gravação. Tabelas criadas com Liquid Clustering no Databricks Runtime 14.3 LTS e versões posteriores usam checkpoint V2 por padrão. Você pode ler e gravar tabelas com o ponto de verificação V2 no Databricks Runtime 13.3 LTS e superior. Consulte Ponto de Verificação V2.

Para dar suporte aos leitores que utilizam Databricks Runtime 12.2 LTS até 13.2, desabilite o ponto de verificação V2 e rebaixe o protocolo da tabela. Consulte Downgrade para clássico.

Substituir a habilitação de recursos padrão (opcional)

Você pode substituir a configuração padrão de habilitação dos recursos de tabela do Delta Lake durante a habilitação do liquid clustering. Isso impede atualizações dos protocolos de leitor e gravador associados a esses recursos de tabela. Você precisa ter uma tabela existente para concluir as seguintes etapas:

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:

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

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

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

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

Limitations

• Databricks Runtime 15.1 e abaixo: durante a gravação, o clustering não dá suporte a consultas de origem que incluem filtros, junções ou agregações.
• Databricks Runtime 15.4 LTS e abaixo: Você não pode criar uma tabela com agrupamento líquido habilitado usando uma escrita de Streaming Estruturado. Você pode usar o Streaming Estruturado para gravar dados em uma tabela existente com clustering líquido habilitado.
• Apache Iceberg v2: não há suporte para simultaneidade no nível de linha em tabelas gerenciadas do Apache Iceberg v2 porque não há suporte para vetores de exclusão e acompanhamento de linhas.
  • Há suporte para simultaneidade em nível de linha em tabelas gerenciadas do Apache Iceberg v3 porque a especificação v3 dá suporte a vetores de exclusão e acompanhamento de linhas. Consulte Usar recursos do Apache Iceberg v3.