> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Codecs de compressão de colunas para a instrução CREATE TABLE
# Codecs de compressão de colunas
export const ExperimentalBadge = () => {
return
Recurso experimental
;
};
export const CloudNotSupportedBadge = () => {
return
Sem suporte no ClickHouse Cloud
;
};
Por padrão, o ClickHouse usa compressão `lz4` na versão autogerenciada e `zstd` no ClickHouse Cloud.
Para a família de motores `MergeTree`, é possível alterar o método de compressão padrão na seção [compression](/docs/pt-BR/reference/settings/server-settings/settings/other#compression) da configuração do servidor.
Também é possível definir o método de compressão para cada coluna na consulta [`CREATE TABLE`](/docs/pt-BR/reference/statements/create/table).
```sql theme={null}
CREATE TABLE codec_example
(
dt Date CODEC(ZSTD),
ts DateTime CODEC(LZ4HC),
float_value Float32 CODEC(NONE),
double_value Float64 CODEC(LZ4HC(9)),
value Float32 CODEC(Delta, ZSTD)
)
ENGINE =
...
```
O codec `Default` pode ser especificado para usar a compressão padrão, que pode depender de diferentes configurações (e das propriedades dos dados) em runtime.
Exemplo: `value UInt64 CODEC(Default)` — o mesmo que não especificar um codec.
Consulte também [Seleção adaptativa de codec](#adaptive-codec-selection).
Você também pode remover o CODEC atual da coluna e usar a compressão padrão definida em config.xml:
```sql theme={null}
ALTER TABLE codec_example MODIFY COLUMN float_value CODEC(Default);
```
Os codecs podem ser combinados em um pipeline, por exemplo, `CODEC(Delta, Default)`.
Não é possível descompactar arquivos de banco de dados do ClickHouse com utilitários externos, como o `lz4`. Em vez disso, use o utilitário especial [clickhouse-compressor](https://github.com/ClickHouse/ClickHouse/tree/master/programs/compressor).
A compressão é compatível com os seguintes motores de tabela:
* Família [MergeTree](/docs/pt-BR/reference/engines/table-engines/mergetree-family/mergetree). Oferece suporte a codecs de compressão de coluna e à seleção do método de compressão padrão nas configurações de [compressão](/docs/pt-BR/reference/settings/server-settings/settings/other#compression).
* Família [Log](/docs/pt-BR/reference/engines/table-engines/log-family/index). Usa o método de compressão `lz4` por padrão e oferece suporte a codecs de compressão de coluna.
* [Set](/docs/pt-BR/reference/engines/table-engines/special/set). Oferece suporte apenas à compressão padrão.
* [Join](/docs/pt-BR/reference/engines/table-engines/special/join). Oferece suporte apenas à compressão padrão.
O ClickHouse oferece suporte a codecs de uso geral e codecs especializados.
## Codecs de Uso Geral
### NONE
`NONE` — Sem compressão.
### LZ4
`LZ4` — [algoritmo de compressão de dados](https://github.com/lz4/lz4) sem perdas usado por padrão. Aplica a compressão rápida LZ4.
### LZ4HC
`LZ4HC[(level)]` — algoritmo LZ4 HC (alta compressão) com nível configurável. Nível padrão: 9. Definir `level <= 0` aplica o nível padrão. Níveis possíveis: \[1, 12]. Faixa de níveis recomendada: \[4, 9].
### ZSTD
`ZSTD[(level)]` — [algoritmo de compressão ZSTD](https://en.wikipedia.org/wiki/Zstandard) com `level` configurável. Níveis possíveis: \[1, 22]. Nível padrão: 1.
Níveis altos de compressão são úteis em cenários assimétricos, como compactar uma vez e descompactar várias vezes. Níveis mais altos proporcionam melhor compressão e maior uso de CPU.
### ZXC
`ZXC[(level)]` — algoritmo de compressão assimétrico [`zxc`](https://github.com/hellobertrand/zxc) com `level` configurável. Níveis possíveis: \[1, 7]. Nível padrão: 3.
`ZXC` prioriza a descompressão muito rápida em detrimento de uma compressão lenta, com uma razão de compressão entre `LZ4` e `ZSTD`. É adequado ao padrão de comprimir uma vez e descomprimir muitas vezes, apresentando a descompressão mais rápida em núcleos ARM modernos. Níveis mais altos proporcionam melhor compressão, porém mais lenta, enquanto a descompressão continua rápida.
Este codec é experimental e requer `SET allow_experimental_codecs = 1` para ser usado.
### Obsoleto: ZSTD\_QAT
### Obsoleto: DEFLATE\_QPL
## Codecs especializados
Estes codecs foram projetados para tornar a compressão mais eficaz ao explorar características específicas dos dados. Alguns deles não comprimem os dados diretamente; em vez disso, fazem o pré-processamento dos dados para que um segundo estágio de compressão, usando um codec de uso geral, possa alcançar uma taxa de compressão maior.
### Delta
`Delta(delta_bytes)` — Abordagem de compressão em que valores brutos são substituídos pela diferença entre dois valores adjacentes, exceto o primeiro, que permanece inalterado. `delta_bytes` é o tamanho máximo dos valores brutos; o valor padrão é `sizeof(type)`. Especificar `delta_bytes` como argumento está obsoleto, e o suporte será removido em um lançamento futuro. Delta é um codec de preparação de dados, ou seja, não pode ser usado isoladamente.
### DoubleDelta
`DoubleDelta(bytes_size)` — Calcula a delta das deltas e a grava em formato binário compacto. `bytes_size` tem significado semelhante a `delta_bytes` no codec [Delta](#delta). Especificar `bytes_size` como argumento está obsoleto, e o suporte será removido em um lançamento futuro. As taxas ideais de compressão são obtidas para sequências monotônicas com stride constante, como dados de séries temporais. Pode ser usado com qualquer tipo numérico. Implementa o algoritmo usado no Gorilla TSDB, estendendo-o para oferecer suporte a tipos de 64 bits. Usa 1 bit adicional para deltas de 32 bits: prefixos de 5 bits em vez de prefixos de 4 bits. Para mais informações, consulte Compressing Time Stamps em [Gorilla: A Fast, Scalable, In-Memory Time Series Database](http://www.vldb.org/pvldb/vol8/p1816-teller.pdf). DoubleDelta é um codec de preparação de dados, ou seja, não pode ser usado isoladamente.
### GCD
`GCD()` - - Calcula o máximo divisor comum (GCD) dos valores da coluna e, em seguida, divide cada valor pelo GCD. Pode ser usado com colunas de inteiros, decimais e data/hora. O codec é adequado para colunas cujos valores variam (aumentam ou diminuem) em múltiplos do GCD, por exemplo, 24, 28, 16, 24, 8, 24 (GCD = 4). GCD é um codec de preparação de dados, ou seja, não pode ser usado isoladamente.
### Gorilla
`Gorilla(bytes_size)` — Calcula o XOR entre o valor de ponto flutuante atual e o anterior e o grava em formato binário compacto. Quanto menor a diferença entre valores consecutivos, ou seja, quanto mais lentamente os valores da série variarem, melhor será a taxa de compressão. Implementa o algoritmo usado no Gorilla TSDB e o estende para oferecer suporte a tipos de 64 bits. Valores possíveis de `bytes_size`: 1, 2, 4, 8; o valor padrão é `sizeof(type)` se for igual a 1, 2, 4 ou 8. Em todos os outros casos, é 1. Para mais informações, consulte a seção 4.1 de [Gorilla: A Fast, Scalable, In-Memory Time Series Database](https://doi.org/10.14778/2824032.2824078).
### ALP
`ALP(variant)` — Compressão adaptativa sem perdas para dados de ponto flutuante. Compatível com `Float32` e `Float64`. Para mais detalhes, consulte [ALP: Adaptive lossless floating-point compression](https://ir.cwi.nl/pub/33334).
O codec aceita um argumento de variante opcional:
* `ALP()` ou `ALP(AUTO)` (padrão) — Usa STD e recorre a RD com base no tamanho estimado após a compressão.
* `ALP(STD)` — Variante ALP padrão. Representa cada valor como um inteiro exato escalonado com potências de dez e, em seguida, comprime os inteiros resultantes com Frame-of-Reference e empacotamento de bits. Valores não representáveis são armazenados como exceções brutas. Funciona melhor para números originados de valores decimais (por exemplo, medições e preços).
* `ALP(RD)` — Variante Real Doubles. Reinterpreta o padrão de bits de cada valor e o divide em uma parte alta (sinal + expoente + bits mais significativos da mantissa) e uma parte baixa. As partes altas são codificadas por dicionário (até 8 entradas), e as partes baixas são empacotadas em bits. Funciona melhor quando muitos valores compartilham os mesmos bits altos.
Este codec é experimental e requer `SET allow_experimental_codecs = 1` para ser usado.
### FPC
`FPC(level, float_size)` - Prevê repetidamente o próximo valor de ponto flutuante da sequência usando o melhor de dois preditores, aplica XOR entre o valor real e o previsto e, em seguida, comprime o resultado eliminando zeros à esquerda. Assim como o Gorilla, é eficiente para armazenar uma série de valores de ponto flutuante que mudam lentamente. Para valores de 64 bits (double), o FPC é mais rápido que o Gorilla; para valores de 32 bits, o desempenho pode variar. Valores possíveis de `level`: 1-28; o valor padrão é 12. Valores possíveis de `float_size`: 4, 8; o valor padrão é `sizeof(type)` se o tipo for Float. Em todos os outros casos, é 4. Para uma descrição detalhada do algoritmo, consulte [High Throughput Compression of Double-Precision Floating-Point Data](https://userweb.cs.txstate.edu/~burtscher/papers/dcc07a.pdf).
### SZ3
`SZ3` ou `SZ3(algorithm, error_bound_mode, error_bound)` - Um codec com perdas e limite de erro ([SZ3 Lossy Compressor](https://szcompressor.org/)) para colunas dos tipos Float32, Float64, Array(Float32) ou Array(Float64). Para colunas de array, a compressão é mais eficaz quando todos os arrays têm o mesmo comprimento (nesse caso, são compactados como vetores de largura fixa); arrays de comprimentos diferentes também são compatíveis e são compactados como uma sequência plana de valores. O codec não se aplica a colunas Map, pois suas chaves seriam corrompidas pela compressão com perdas. Os valores compatíveis para 'algorithm' são `ALGO_LORENZO_REG`, `ALGO_INTERP_LORENZO` e `ALGO_INTERP`. Os valores compatíveis para 'error\_bound\_mode' são `ABS`, `REL`, `PSNR` e `ABS_AND_REL`. O argumento 'error\_bound' corresponde ao erro máximo e é do tipo Float64.
Este codec é experimental e requer `SET allow_experimental_codecs = 1` para ser usado.
### T64
`T64` — Abordagem de compressão que elimina os bits mais significativos não utilizados dos valores em tipos de dados inteiros (incluindo `Enum`, `Date` e `DateTime`). Em cada passo do algoritmo, o codec recebe um bloco de 64 valores, organiza-os em uma matriz de bits 64x64, transpõe-a, elimina os bits não utilizados dos valores e retorna o restante como uma sequência. Bits não utilizados são aqueles que não diferem entre os valores máximo e mínimo em toda a parte de dados para a qual a compressão é usada.
Os codecs `DoubleDelta` e `Gorilla` são usados no Gorilla TSDB como componentes do algoritmo de compressão. A abordagem Gorilla é eficaz em cenários com uma sequência de valores que mudam lentamente e seus respectivos timestamps. Os timestamps são comprimidos de forma eficaz pelo codec `DoubleDelta`, e os valores, pelo codec `Gorilla`. Por exemplo, para obter uma tabela armazenada de forma eficiente, você pode criá-la com a seguinte configuração:
```sql theme={null}
CREATE TABLE codec_example
(
timestamp DateTime CODEC(DoubleDelta),
slow_values Float32 CODEC(Gorilla)
)
ENGINE = MergeTree()
```
### Quantized
`Quantized(method, dimensions[, ...])` — Um codec especializado que oferece suporte à busca vetorial aproximada em colunas do tipo `Array(Float32)`, `Array(Float64)` ou `Array(BFloat16)`.
Ele armazena os vetores originais em precisão total, além de um *código quantizado* compacto para cada vetor.
Em tabelas da família `MergeTree`, consultas de busca vetorial com a configuração [`vector_search_use_quantized_codes`](/docs/pt-BR/reference/settings/session-settings/vector-search#vector_search_use_quantized_codes) examinam os códigos quantizados para criar uma lista curta e, em seguida, recalculam os resultados usando os vetores em precisão total.
Essa busca em duas etapas lê menos bytes do que uma varredura normal em precisão total, em troca de menor revocação.
`dimensions` é o comprimento do vetor; os valores compatíveis de `method` são `rabitq`, `turboquant`, `int8`, `prefix` e `product`, cada um com uma combinação diferente de tamanho, precisão e função de distância.
O codec só pode ser definido em `CREATE TABLE`; não pode ser adicionado, removido ou alterado por meio de `ALTER TABLE`, inclusive com `ADD COLUMN ... CODEC(Quantized(...))`.
Ele não pode ser encadeado com nenhum outro codec, nem mesmo com um codec de criptografia como `AES_128_GCM_SIV`.
Para mais detalhes, consulte [Busca vetorial com codecs quantizados](/docs/pt-BR/reference/engines/table-engines/mergetree-family/annindexes#vector-search-with-quantized-codecs).
```sql theme={null}
SET allow_experimental_codecs = 1;
CREATE TABLE vectors
(
id UInt32,
vec Array(BFloat16) CODEC(Quantized('rabitq', 1536))
)
ENGINE = MergeTree ORDER BY id;
```
## Codecs de criptografia
Esses codecs não comprimem os dados, mas os criptografam no disco. Eles só estão disponíveis quando uma chave de criptografia é especificada nas configurações de [encryption](/docs/pt-BR/reference/settings/server-settings/settings/other#encryption). Observe que a criptografia só faz sentido no final dos pipelines de codecs, pois dados criptografados geralmente não podem ser comprimidos de maneira significativa.
Codecs de criptografia:
### AES\_128\_GCM\_SIV
`CODEC('AES-128-GCM-SIV')` — Criptografa dados com AES-128 no modo GCM-SIV especificado na [RFC 8452](https://tools.ietf.org/html/rfc8452).
### AES-256-GCM-SIV
`CODEC('AES-256-GCM-SIV')` — Criptografa dados com AES-256 no modo GCM-SIV.
Esses codecs usam um nonce fixo, portanto, a criptografia é determinística. Isso os torna compatíveis com motores de deduplicação, como o [ReplicatedMergeTree](/docs/pt-BR/reference/engines/table-engines/mergetree-family/replication), mas também apresenta uma vulnerabilidade: quando o mesmo bloco de dados é criptografado duas vezes, o texto cifrado resultante será exatamente o mesmo. Assim, um adversário que consiga ler o disco poderá identificar essa equivalência (embora apenas a equivalência, sem acesso ao conteúdo).
A maioria dos motores, incluindo a família "\*MergeTree", cria arquivos de índice no disco sem aplicar codecs. Isso significa que dados em texto simples aparecerão no disco se uma coluna criptografada for indexada.
Se você executar uma consulta SELECT que mencione um valor específico em uma coluna criptografada (como em sua cláusula WHERE), o valor poderá aparecer em [system.query\_log](/docs/pt-BR/reference/system-tables/query_log). Talvez seja recomendável desativar o logging.
**Exemplo**
```sql theme={null}
CREATE TABLE mytable
(
x String CODEC(AES_128_GCM_SIV)
)
ENGINE = MergeTree ORDER BY x;
```
Se for necessário aplicar compressão, ela deverá ser especificada explicitamente. Caso contrário, apenas a criptografia será aplicada aos dados.
**Exemplo**
```sql theme={null}
CREATE TABLE mytable
(
x String CODEC(Delta, LZ4, AES_128_GCM_SIV)
)
ENGINE = MergeTree ORDER BY x;
```
## Seleção Adaptativa de Codecs
Os codecs especializados acima podem reduzir drasticamente o tamanho dos dados adequados, mas escolhê-los exige conhecimento especializado, e nenhuma escolha única serve para uma coluna cujos dados mudam ao longo do tempo. Com a configuração do MergeTree [`allow_experimental_adaptive_codec_selection`](/docs/pt-BR/reference/settings/merge-tree-settings) habilitada, o ClickHouse escolhe por você. Para colunas que usam o codec padrão (`CODEC(Default)` ou nenhum `CODEC`), cada bloco é gravado com o codec que resulta na menor compressão, escolhido entre o codec padrão da tabela, `NONE` e codecs especializados adequados ao tipo da coluna.
Um bloco nunca fica maior do que ficaria com o codec padrão, e dados incomprimíveis são armazenados em formato bruto (compri-los produziria um arquivo um pouco maior e mais lento de ler). O trabalho é feito em segundo plano, durante merges e mutações, quando os dados já são recomprimidos. A velocidade de inserção não é afetada. As consultas geralmente ficam mais rápidas: menos dados são lidos do disco, cada bloco lido por uma consulta precisa ser descomprimido primeiro, e codecs especializados descomprimem mais rápido que o `LZ4` padrão. Cada bloco registra o codec usado para gravá-lo, portanto a leitura não exige nenhuma configuração, e o recurso pode ser desativado a qualquer momento, mantendo todos os dados legíveis.
```sql theme={null}
CREATE TABLE adaptive
(
time DateTime,
user_id UInt64
)
ENGINE = MergeTree
ORDER BY time
SETTINGS allow_experimental_adaptive_codec_selection = 1;
INSERT INTO adaptive SELECT toDateTime('2026-01-01') + number, cityHash64(number) FROM numbers(1000000);
OPTIMIZE TABLE adaptive FINAL;
```
Você pode observar como isso funciona com a função de tabela [`mergeTreeCodecBlockCounts`](/docs/pt-BR/reference/functions/table-functions/mergeTreeCodecBlockCounts). Aqui, `time` aumenta continuamente, portanto `T64`, que armazena apenas os bits que variam dentro de um bloco, superou o codec padrão em todos os blocos. `user_id` contém hashes que nenhum codec consegue comprimir, portanto seus blocos foram armazenados sem processamento:
```sql theme={null}
SELECT column, codec_block_counts FROM mergeTreeCodecBlockCounts(currentDatabase(), 'adaptive');
```
```text theme={null}
┌─column──┬─codec_block_counts─┐
1. │ time │ {'T64':62} │
2. │ user_id │ {'NONE':123} │
└─────────┴────────────────────┘
```
No momento, a seleção abrange colunas de tipos semelhantes a inteiros: inteiros, enums, datas e horários, `Decimal32`/`Decimal64` e `IPv4`.
## Conteúdo relacionado
* Blog: [Como otimizar o ClickHouse com schemas e codecs](https://clickhouse.com/blog/optimize-clickhouse-codecs-compression-schema)
* Blog: [Como trabalhar com dados de séries temporais no ClickHouse](https://clickhouse.com/blog/working-with-time-series-data-and-functions-ClickHouse)