Pular para o conteúdo principal
Última atualização em

Usar cluster 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. Ele simplifica o gerenciamento de tabelas e otimiza o desempenho da consulta, organizando automaticamente os dados com base em chaves de clustering.

Ao contrário do particionamento tradicional, é possível redefinir as chaves de clustering sem reescrever os dados existentes. Isso permite que a disposição dos dados evolua junto com as necessidades analíticas em evolução. A clusterização líquida se aplica tanto a tabelas de transmissão quanto a visualizações materializadas.

importante

O clustering líquido está geralmente disponível para tabelas Delta Lake e em Pré-lançamento público para tabelas Apache Iceberg gerenciadas. Para tabelas Delta Lake, o suporte GA está disponível no Databricks Runtime 15.2 e superior. A Databricks recomenda usar a versão mais recente do Databricks Runtime para o melhor desempenho. Para tabelas Apache Iceberg gerenciadas, Databricks Runtime 16.4 LTS ou superior é exigido.

As tabelas gerenciadas Apache Iceberg v3 também suportam vetores de exclusão, acompanhamento de linha, simultaneidade em nível de linha e clusters líquido automático. Essas funcionalidades exigem Databricks Runtime 18.0 e acima. Veja Usar recursos v3 do Apache Iceberg.

Quando usar cluster líquido​

O Databricks recomenda o clustering líquido para todas as novas tabelas, incluindo tabelas de streaming e visualizações materializadas. Os cenários a seguir se beneficiam particularmente do clustering:

  • Consultas que filtram em colunas de alta cardinalidade.
  • Tabelas com assimetria acentuada de dados.
  • Tabelas que crescem rapidamente e exigem manutenção e ações de ajuste.
  • Tabelas com requisitos de gravação concorrente.
  • Tabelas com padrões de acesso variados ou em mudança.
  • Tabelas em que uma chave de partição típica poderia retornar resultados de muitas ou poucas partições.

Ativar clusters líquidos​

É possível ativar o clustering líquido em uma tabela não particionada existente ou durante a criação da tabela. Clustering não é compatível com particionamento ou ZORDER. A Databricks recomenda permitir à plataforma gerenciar todas as operações de disposição e otimização dos dados em sua tabela. Depois de habilitar o clustering líquido, execute os jobs OPTIMIZE para agrupar dados de forma incremental. Consulte Como acionar o clustering.

Criar tabelas com clustering​

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

Para criar uma tabela vazia com clustering:

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

Para criar uma tabela a partir de dados existentes com clusters, CLUSTER BY deve aparecer após o nome da tabela, não na cláusula SELECT:

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

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

SQL
CREATE TABLE table3 LIKE table1;
importante

Ao usar APIs do DataFrame para definir chaves de clustering, só é possível especificar colunas de clustering durante a criação da tabela ou ao usar o modo overwrite (como com operações de CREATE OR REPLACE TABLE). Não é possível alterar chaves de clustering quando estiver usando o modo append.

Para alterar as chaves de clustering em uma tabela existente enquanto anexa dados, utilize os comandos ALTER TABLE do SQL para modificar a configuração de clustering separadamente de suas operações de gravação de dados. Consulte Alterar chaves de clustering.

No Databricks Runtime 16.0 e acima, é possível criar tabelas com clustering líquido ativado usando gravações de transmissão estructurada. Databricks recomenda o uso do Databricks Runtime 16.4 e acima para o melhor desempenho, como nos exemplos a seguir:

SQL
CREATE TABLE table1 (
  col0 STRING,
  col1 DATE,
  col2 BIGINT
)
CLUSTER BY (col0, col1);
atenção

As tabelas do Delta Lake com clustering líquido ativado usam o gravador Delta versão 7 e o leitor versão 3. Clientes Delta que não são compatíveis com esses protocolos não podem ler essas tabelas. Não é possível fazer downgrade das versões do protocolo de tabela. Consulte a compatibilidade de recursos e protocolos do Delta Lake.

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

Habilitar em tabelas existentes​

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

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

Para tabelas gerenciadas do Apache Iceberg, considere o seguinte:

  • Para tabelas com a especificação v2, é preciso desativar explicitamente os vetores de exclusão e o acompanhamento de linhas ao habilitar o clustering líquido em uma tabela existente.
  • Para tabelas com a especificação v3, não é necessário desativar esses recursos porque os vetores de exclusão e o acompanhamento de linhas são suportados. Veja Usar recursos v3 do Apache Iceberg.
nota

O comportamento default não aplica clustering a dados previamente gravados. Para forçar o reagrupamento, use OPTIMIZE FULL ou OPTIMIZE FULL WHERE <predicate>. Consulte Forçar reagrupamento.

Converter uma tabela particionada para clustering líquido​

No Databricks Runtime 18.1 e acima, para converter uma tabela Delta Lake particionada existente em clustering líquido, use REPLACE PARTITIONED BY WITH CLUSTER BY em uma instrução ALTER TABLE. A conversão minimiza o tempo de inatividade do leitor e do gravador e oferece suporte a tabelas externas e gerenciadas. Após a conversão, a tabela oferece suporte a leituras com o Databricks Runtime 13.3 LTS e acima.

nota

Para tabelas Iceberg gerenciadas, a conversão não é necessária porque essas tabelas usam definições de partição como chaves de clustering líquido. A execução do comando de conversão gera um erro.

Os benefícios da conversão de tabelas particionadas para cluster líquido incluem:

  • Melhorias de desempenho para tabelas que sofrem com salto de dados insuficiente ou superparticionamento.
  • Melhorias automáticas de desempenho, usando CLUSTER BY AUTO, para tabelas com padrões de query que mudam com frequência.
  • Colunas de clusterização são flexíveis e fáceis de alterar, enquanto o particionamento é rígido e difícil de alterar.
  • Conflitos de gravação reduzidos porque as tabelas com clustering líquido permitem simultaneidade em nível de linha. Consulte Simultaneidade em nível de linha.

Sintaxe​

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

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

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

Para obter orientação sobre como escolher chaves de clustering ao migrar de tabelas particionadas, consulte Como migrar de particionamento ou Z-order.

Exemplos​

Para agrupar em colunas diferentes das partições originais, como para uma tabela particionada em (year, month, day), faça o seguinte:

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

Para se beneficiar da alteração das colunas de clustering, você deve executar OPTIMIZE.

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

SQL
ALTER TABLE t2 REPLACE PARTITIONED BY WITH CLUSTER BY AUTO;

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

SQL
ALTER TABLE t3 REPLACE PARTITIONED BY WITH CLUSTER BY;

Lidar com leituras e gravações concorrentes durante a conversão​

Após a conversão, o Databricks Runtime 13.3 LTS e acima é compatível com leituras e gravações. O 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 seguinte tabela para saber como lidar com cargas de trabalho de leitura e gravação concorrentes durante a conversão:

Tipo de carga de trabalho

Lê durante a conversão

Gravações durante a conversão

Batch

Sem tempo de inatividade. Todas as versões do Databricks Runtime podem ler a tabela durante a conversão.

Sem tempo de inatividade no Databricks Runtime 15.4 e acima. Para Databricks Runtime 15.3 e inferior, a Databricks recomenda que você pause as cargas de trabalho antes de converter e, em seguida, reinicie as cargas de trabalho depois que a conversão for concluída.

Transmissão

Com acompanhamento de esquema e mapeamento de colunas : Reinicie a transmissão sem perder nenhum commit. Sem acompanhamento de esquema e mapeamento de colunas : A transmissão gera uma exceção. Para reiniciar com uma nova localização de ponto de verificação e versão inicial. Commits não estão perdidos.

Reiniciar a transmissão sem perder commits.

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 operações de REORG, uma operação de UPGRADE PROTOCOL e uma operação de REPLACE PARTITIONED BY WITH CLUSTER BY.

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

Para reverter usando RESTORE, execute os comandos a seguir:

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

See RESTORE.

Converter uma tabela particionada por uma coluna de timestamp​

Para converter uma tabela (t1) que é particionada por uma coluna de timestamp (timestamp_col) e usar a coluna de timestamp como uma chave de agrupamento, você deve definir configurações adicionais:

SQL
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 de timestamp em uma coluna de agrupamento sem essas configurações, o comando gera um erro:

Text
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​

Aplicam-se as seguintes limitações ao comando REPLACE PARTITIONED BY WITH CLUSTER BY de conversão:

  • Tabelas de transmissão e views materializadas criadas a partir de um pipeline de Lakeflow Spark Declarative Pipelines não são suportadas. Para usar o cluster líquido, é necessário atualizar a definição do pipeline para usar CLUSTER BY em vez de PARTITIONED BY.
  • Tabelas que utilizam Delta Sharing com filtragem de partição não são compatíveis. Para obter informações sobre filtragem de partição para Delta Sharing, consulte Especificar partições de tabela para compartilhar.

Remover chaves de clustering​

Para remover keys de clustering, use a seguinte sintaxe:

SQL
ALTER TABLE table_name CLUSTER BY NONE;

Escolha as chaves de clustering​

dica

O Databricks recomenda o uso de clustering líquido automático para tabelas compatíveis, que seleciona de forma inteligente as chaves de clustering com base nos seus padrões de consulta. Consulte Clustering líquido automático.

Diretrizes de seleção de key​

Quando as chaves de clustering são especificadas manualmente, as colunas devem ser escolhidas com base nas colunas mais frequentemente utilizadas em filtros de consulta. As chaves de clustering podem ser definidas em qualquer ordem. Se duas colunas forem altamente correlacionadas, basta incluir uma delas como chave de clustering.

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

As chaves de clustering devem ser colunas com estatísticas coletadas. Por padrão, as primeiras 32 colunas em uma tabela Delta Lake têm estatísticas coletadas. Consulte Especificar colunas de estatísticas.

Tipos de dados compatíveis​

O clustering dá suporte a estes tipos de dados para keys de clustering:

  • Data
  • Carimbo de data/hora
  • TimestampNTZ (Databricks Runtime 14.3 LTS ou acima)
  • String
  • inteiro, longo, curto, byte
  • Ponto flutuante, Duplo, Decimal

É possível agrupar por um StructField usando a notação de ponto, como CLUSTER BY (struct_col.field). Campos de estrutura aninhados são compatíveis a qualquer profundidade, como CLUSTER BY (struct_col.nested.field). O tipo de dados do campo deve ser um dos tipos suportados na lista precedente.

Não é possível clusterizar por nenhum dos seguintes:

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

Migrando de particionamento ou Z-order​

importante

A Databricks recomenda usar a conversão automática com o comando REPLACE PARTITIONED BY WITH CLUSTER BY. Consulte Converter uma tabela particionada para clustering líquido.

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)

Utilizar a coluna original como chave de clustering e não criar uma coluna gerada.

Clusters líquidos automáticos​

No Databricks Runtime 15.4 LTS e superior, é possível habilitar o clustering líquido automático para tabelas Delta Lake gerenciadas pelo Unity Catalog. Para tabelas Apache Iceberg v3 gerenciadas pelo Unity Catalog, o clustering líquido automático requer Databricks Runtime 18.0 e acima. O liquid clustering automático permite ao Databricks escolher inteligentemente chaves de clustering para otimizar o desempenho da consulta, utilizando a cláusula CLUSTER BY AUTO.

nota

O clustering líquido automático também é suportado para visualizações materializadas e tabelas de transmissão, incluindo LakeFlow Spark Declarative Pipelines e pipelines autônomos. Especifique CLUSTER BY AUTO em sua definição de pipeline ou SQL.

Como funciona o clustering líquido automático​

O agrupamento líquido automático oferece otimização inteligente com base em seus padrões de uso:

  • Requer otimização preditiva : A seleção automática de chaves e as operações de clusters são executadas de forma assíncrona como uma operação de manutenção. Consulte Otimização preditiva para tabelas gerenciadas do Unity Catalog.
  • Analisa a carga de trabalho de query : A Databricks analisa a carga de trabalho de query histórica da tabela e identifica as melhores colunas candidatas para agrupamento.
  • Adapta-se às mudanças: se os padrões de consulta ou as distribuições de dados mudarem ao longo do tempo, o liquid clustering automático seleciona novas chaves para otimizar o desempenho.
  • Seleção consciente de custo: A Databricks altera as chaves de agrupamento somente quando a economia de custos prevista decorrente das melhorias de salto de dados superar o custo de agrupamento de dados.

O clustering líquido automático pode não selecionar chaves pelos seguintes motivos:

  • A tabela é muito pequena para se beneficiar do liquid clustering.
  • A tabela já possui um esquema de clusterização eficaz, seja de chaves manuais anteriores ou da ordem de inserção natural que corresponde aos padrões de consulta.
  • A tabela não tem Queries frequentes.
  • Não está sendo usado o Databricks Runtime 15.4 LTS ou acima.

É possível aplicar o clustering líquido automático para todas as tabelas gerenciadas do Unity Catalog, independentemente das características de dados e consulta. A heurística decide se é vantajoso em termos de custo selecionar as chaves de clustering.

Compatibilidade da versão do Databricks Runtime​

É possível ler ou gravar tabelas com clustering automático ativado em todas as versões do Databricks Runtime que dão suporte a clustering líquido. No entanto, a seleção inteligente de chaves baseia-se em metadados introduzidos no Databricks Runtime 15.4 LTS.

Use o Databricks Runtime 15.4 LTS ou acima 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 liquid clustering automático​

Para criar uma tabela com clustering líquido automático:

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

Para ativar o liquid clustering automático em uma tabela existente, incluindo tabelas com chaves especificadas manualmente:

SQL
ALTER TABLE table1 CLUSTER BY AUTO;

Para definir dicas de coluna de clustering iniciais para seleção de chave, definir as chaves de clustering e, em seguida, ativar o clustering automático:

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

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

Para desativar a atualização automática de clusters líquidos:

SQL
ALTER TABLE table1 CLUSTER BY NONE;

Para desativar clusters líquidos automáticos e especificar colunas de clusters:

SQL
ALTER TABLE table1 CLUSTER BY (column01, column02);

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

Verifique se o clustering automático está ativado​

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

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

Limitações​

O cluster líquido automático não está disponível para tabelas Apache Iceberg v2 gerenciadas. Tem suporte para tabelas Apache Iceberg v3 gerenciadas no Databricks Runtime 18.0 e acima.

Gravar dados em uma tabela de clusters​

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

Operações que suportam clustering na 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")

Limites 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 clusters e são mais baixos para tabelas gerenciadas pelo Unity Catalog do que para outras tabelas Delta Lake.

Número de colunas de clustering

Tamanho do limite para tabelas gerenciadas do Unity Catalog

Tamanho limite para outras tabelas Delta Lake

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.

Cargas de trabalho de transmissão​

Cargas de trabalho de transmissão estruturada oferecem suporte a clustering na gravação quando a configuração do Spark spark.databricks.delta.liquid.eagerClustering.streaming.enabled é definida como true. O clustering 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​

A otimização preditiva executa automaticamente os comandos OPTIMIZE para tabelas habilitadas. Consulte Otimização preditiva para tabelas gerenciadas do Unity Catalog. Ao utilizar a otimização preditiva, a Databricks recomenda desabilitar quaisquer jobs OPTIMIZE programados.

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

SQL
OPTIMIZE table_name;

Os clusters líquidos são **progressivos**, o que significa que OPTIMIZE reescreve os dados apenas quando necessário para acomodar os dados que precisam ser colocados em clusters. OPTIMIZE não regrava arquivos de dados com chaves de clustering que não correspondem aos dados a serem colocados em clusters. Consulte Forçar reagrupamento.

Se você não estiver usando a otimização preditiva, o Databricks recomenda programar jobs OPTIMIZE regulares para clustering de dados. Para tabelas com muitas atualizações ou inserções, o Databricks recomenda agendar um job OPTIMIZE a cada uma ou duas horas. Como o clustering líquido é incremental, a maioria dos OPTIMIZE jobs para tabelas em cluster são executados rapidamente.

Forçar reagrupamento​

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

SQL
OPTIMIZE table_name FULL;
importante

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

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 alteração nas chaves de clusterização, OPTIMIZE FULL é executado da mesma forma que OPTIMIZE. Nesse cenário, OPTIMIZE usa uma abordagem incremental e reescreve apenas os arquivos que não foram compactados anteriormente. Utilize sempre OPTIMIZE FULL para garantir que a disposição de dados reflita as chaves de clustering atuais.

Reagrupamento parcial​

No Databricks Runtime 18.1 e acima, você pode forçar o reclustering para um subconjunto de registros usando OPTIMIZE FULL WHERE <predicate>. Um arquivo é incluído se qualquer parte de seu intervalo se sobrepuser ao predicado. Consulte Parâmetros.

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

Leia dados de uma tabela com clusters​

É possível ler dados em uma tabela Delta Lake com clusters utilizando qualquer cliente Delta Lake que permita a leitura de vetores de exclusão. Com a API REST Catalog Iceberg, é possível ler dados em uma tabela Iceberg em cluster. O Liquid clustering melhora o desempenho de queries por meio do salto automático de dados ao filtrar em chaves de clustering.

SQL
SELECT * FROM table_name WHERE cluster_key_column_name = "some_value";

Gerenciar chaves de key​

Veja como uma tabela é colocada em clusters​

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

Ao alterar 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. Para reescrever dados existentes com as chaves de clustering atualizadas, consulte Reclusterização Forçada.

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 chaves de clustering como NONE não regrava dados clusterizados, mas impede que futuras operações OPTIMIZE utilizem chaves de clustering.

Usar cluster líquido a partir de um mecanismo externo​

É possível habilitar a clusterização líquida em tabelas gerenciadas do Iceberg a partir de mecanismos externos do Iceberg. Para habilitar o clustering líquido, especificar colunas de partição ao criar uma tabela. O Unity Catalog interpreta as partições como chaves de cluster. Por exemplo, execute o comando abaixo no OSS Spark:

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

Para desativar clusters líquidos:

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

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

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

Ao especificar uma partição usando uma transformação de bucket, o Unity Catalog remove a expressão e usa a coluna como uma chave de agrupamento:

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

Compatibilidade para tabelas com clustering líquido​

O clustering líquido usa recursos de tabela do Delta Lake que requerem versões específicas do Databricks Runtime para leitura e gravação. As tabelas criadas com liquid clustering no Databricks Runtime 14.1 e acima usam pontos de verificação v2 por padrão. Você pode ler e gravar tabelas com ponto de verificação V2 no Databricks Runtime 13.3 LTS e acima. Consulte Pontos de verificação V2.

Para dar suporte aos leitores que usam o Databricks Runtime 12.2 LTS a 13.2, desabilite o checkpoint V2 e faça o downgrade do protocolo da tabela. Consulte Downgrade para clássico.

Substituir a ativação de recursos padrão (opcional)​

Você pode substituir a ativação default de recursos da tabela Delta Lake durante a ativação do clustering líquido. Isso impede atualizações dos protocolos de leitura e gravação associados a esses recursos de tabela. Você deve ter uma tabela existente para concluir os passos seguintes.

  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 simultaneidade em nível de linha, tornando as transações e as operações de clusters mais propensas a entrar em conflito. Consulte Simultaneidade 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 linha desativa a simultaneidade em nível de linha, tornando as transações e as operações de clustering mais propensas a entrar em conflito. Consulte Simultaneidade em nível de linha.

Ponto 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. Consulte Pontos de verificação V2.

Limitações​

  • Databricks Runtime 15.1 e versões abaixo : o clustering na gravação não é compatível com consultas de origem que incluam filtros, joins ou agregações.
  • Databricks Runtime 15.4 LTS e abaixo : Não é possível criar uma tabela com clustering líquido ativado usando uma gravação de transmissão estruturada. É possível 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 em tabelas gerenciadas Apache Iceberg v2 porque os vetores de exclusão e o acompanhamento de linha não são suportados.
    • A simultaneidade em nível de linha é suportada em tabelas Apache Iceberg v3 gerenciadas porque a especificação v3 suporta vetores de exclusão e acompanhamento de linha. Veja Usar recursos v3 do Apache Iceberg.
Nesta página