Por que minha chave primária não é usada? Como posso verificar?

Verificando sua chave primária

Os usuários podem se deparar com casos em que a consulta fica mais lenta do que o esperado, acreditando que estão ordenando ou filtrando por uma chave primária. Neste artigo, mostramos como confirmar se a chave está sendo usada, destacando os motivos mais comuns pelos quais isso não acontece.

Crie a tabela

Considere a tabela simples a seguir:

CREATE TABLE logs
(
    `code` LowCardinality(String),
    `timestamp` DateTime64(3)
)
ENGINE = MergeTree
ORDER BY (code, toUnixTimestamp(timestamp))

Observe que nossa chave de ordenação inclui toUnixTimestamp(timestamp) como o segundo elemento.

Popular os dados

Popule esta tabela com 100 milhões de linhas:

INSERT INTO logs SELECT
 ['200', '404', '502', '403'][toInt32(randBinomial(4, 0.1)) + 1] AS code,
    now() + toIntervalMinute(number) AS timestamp
FROM numbers(100000000)

0 rows in set. Elapsed: 15.845 sec. Processed 100.00 million rows, 800.00 MB (6.31 million rows/s., 50.49 MB/s.)

SELECT count()
FROM logs

┌───count()─┐
│ 100000000 │ -- 100.00 million
└───────────┘

1 row in set. Elapsed: 0.002 sec.

Filtragem básica

Se filtrarmos por código, veremos no resultado o número de linhas examinadas: 49.15 thousand. Observe que isso é um subconjunto do total de 100 milhões de linhas.

SELECT count() AS c
FROM logs
WHERE code = '200'

┌────────c─┐
│ 65607542 │ -- 65,61 milhões
└──────────┘

1 row in set. Elapsed: 0.021 sec. Processed 49.15 thousand rows, 49.17 KB (2.34 million rows/s., 2.34 MB/s.)
Peak memory usage: 92.70 KiB.

Além disso, podemos confirmar o uso do índice com a cláusula EXPLAIN indexes=1:

EXPLAIN indexes = 1
SELECT count() AS c
FROM logs
WHERE code = '200'

┌─explain────────────────────────────────────────────────────────────┐
│ Expression ((Project names + Projection))                          │
│   AggregatingProjection                                            │
│     Expression (Before GROUP BY)                                   │
│       Filter ((WHERE + Change column names to column identifiers)) │
│         ReadFromMergeTree (default.logs)                           │
│         Indexes:                                                   │
│           PrimaryKey                                               │
│             Keys:                                                  │
│               code                                                 │
│             Condition: (code in ['200', '200'])                    │
│             Parts: 3/3 │
│             Granules: 8012/12209 │
│     ReadFromPreparedSource (_minmax_count_projection)              │
└────────────────────────────────────────────────────────────────────┘

Observe como o número de grânulos examinados 8012 é uma fração do total 12209. A seção destacada abaixo confirma o uso do código da chave primária.

PrimaryKey
  Keys: 
   code 

Os grânulos são a unidade de processamento de dados no ClickHouse, e cada um normalmente contém 8192 linhas. Para mais detalhes sobre grânulos e como eles são filtrados, recomendamos a leitura deste guia.

Filtrar por chaves mais adiante em uma chave de ordenação não será tão eficiente quanto filtrar por aquelas que aparecem antes na tupla. Para entender o motivo, veja aqui

Filtragem por múltiplas chaves

Suponha que a filtragem seja feita por code e timestamp:

SELECT count()
FROM logs
WHERE (code = '200') AND (timestamp >= '2025-01-01 00:00:00') AND (timestamp <= '2026-01-01 00:00:00')

┌─count()─┐
│  689742 │
└─────────┘

1 row in set. Elapsed: 0.008 sec. Processed 712.70 thousand rows, 6.41 MB (88.92 million rows/s., 799.27 MB/s.)

EXPLAIN indexes = 1
SELECT count()
FROM logs
WHERE (code = '200') AND (timestamp >= '2025-01-01 00:00:00') AND (timestamp <= '2026-01-01 00:00:00')

┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Expression ((Project names + Projection))                                                                                                                         │
│   Aggregating                                                                                                                                                     │
│     Expression (Before GROUP BY)                                                                                                                                  │
│       Expression                                                                                                                                                  │
│         ReadFromMergeTree (default.logs)                                                                                                                          │
│         Indexes:                                                                                                                                                  │
│           PrimaryKey                                                                                                                                              │
│             Keys:                                                                                                                                                 │
│               code                                                                                                                                                │
│               toUnixTimestamp(timestamp)                                                                                                                          │
│             Condition: and((toUnixTimestamp(timestamp) in (-Inf, 1767225600]), and((toUnixTimestamp(timestamp) in [1735689600, +Inf)), (code in ['200', '200']))) │
│             Parts: 3/3 │
│             Granules: 87/12209 │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

13 rows in set. Elapsed: 0.002 sec.

Neste caso, ambas as chaves de ordenação são usadas para filtrar linhas, de modo que seja necessário ler apenas 87 grânulos.

Uso de chaves para ordenação

O ClickHouse também pode aproveitar chaves de ordenação para ordenar os dados com eficiência. Especificamente, Quando a configuração optimize_read_in_order está habilitada (por padrão), o ClickHouse server usa o índice da tabela e lê os dados na ordem da chave ORDER BY. Isso permite evitar a leitura de todos os dados quando um LIMIT é especificado. Assim, consultas sobre grandes volumes de dados com LIMITs pequenos são processadas mais rapidamente. Veja aqui e aqui para mais detalhes. No entanto, isso exige que as chaves usadas estejam alinhadas. Por exemplo, considere esta consulta:

SELECT *
FROM logs
WHERE (code = '200') AND (timestamp >= '2025-01-01 00:00:00') AND (timestamp <= '2026-01-01 00:00:00')
ORDER BY timestamp ASC
LIMIT 10

┌─code─┬───────────────timestamp─┐
│ 200 │ 2025-01-01 00:00:01.000 │
│ 200 │ 2025-01-01 00:00:45.000 │
│ 200 │ 2025-01-01 00:01:01.000 │
│ 200 │ 2025-01-01 00:01:45.000 │
│ 200 │ 2025-01-01 00:02:01.000 │
│ 200 │ 2025-01-01 00:03:01.000 │
│ 200 │ 2025-01-01 00:03:45.000 │
│ 200 │ 2025-01-01 00:04:01.000 │
│ 200 │ 2025-01-01 00:05:45.000 │
│ 200 │ 2025-01-01 00:06:01.000 │
└──────┴─────────────────────────

10 linhas no conjunto. Elapsed: 0.009 sec. Processed 712.70 thousand rows, 6.41 MB (80.13 million rows/s., 720.27 MB/s.)
Peak memory usage: 125.50 KiB.

Podemos confirmar que a otimização não foi aplicada aqui com EXPLAIN pipeline:

EXPLAIN PIPELINE
SELECT *
FROM logs
WHERE (code = '200') AND (timestamp >= '2025-01-01 00:00:00') AND (timestamp <= '2026-01-01 00:00:00')
ORDER BY timestamp ASC
LIMIT 10

┌─explain───────────────────────────────────────────────────────────────────────┐
│ (Expression)                                                                  │
│ ExpressionTransform                                                           │
│   (Limit)                                                                     │
│   Limit │
│     (Sorting)                                                                 │
│     MergingSortedTransform 12 → 1 │
│       MergeSortingTransform × 12 │
│         LimitsCheckingTransform × 12 │
│           PartialSortingTransform × 12 │
│             (Expression)                                                      │
│             ExpressionTransform × 12 │
│               (Expression)                                                    │
│               ExpressionTransform × 12 │
│                 (ReadFromMergeTree)                                           │
│                 MergeTreeSelect(pool: ReadPool, algorithm: Thread) × 12 0 → 1 │
└───────────────────────────────────────────────────────────────────────────────┘

15 rows in set. Elapsed: 0.004 sec.

A linha MergeTreeSelect(pool: ReadPool, algorithm: Thread) aqui não indica o uso da otimização, mas sim uma leitura padrão. Isso ocorre porque a chave de ordenação da nossa tabela usa toUnixTimestamp(Timestamp) e NÃO timestamp. Corrigir essa incompatibilidade resolve o problema:

EXPLAIN PIPELINE
SELECT *
FROM logs
WHERE (code = '200') AND (timestamp >= '2025-01-01 00:00:00') AND (timestamp <= '2026-01-01 00:00:00')
ORDER BY toUnixTimestamp(timestamp) ASC
LIMIT 10

┌─explain──────────────────────────────────────────────────────────────────────────┐
│ (Expression)                                                                     │
│ ExpressionTransform                                                              │
│   (Limit)                                                                        │
│   Limit │
│     (Sorting)                                                                    │
│     MergingSortedTransform 3 → 1 │
│       BufferChunks × 3 │
│         (Expression)                                                             │
│         ExpressionTransform × 3 │
│           (Expression)                                                           │
│           ExpressionTransform × 3 │
│             (ReadFromMergeTree)                                                  │
│             MergeTreeSelect(pool: ReadPoolInOrder, algorithm: InOrder) × 3 0 → 1 │
└──────────────────────────────────────────────────────────────────────────────────┘

13 rows in set. Elapsed: 0.003 sec.

​Verificando sua chave primária

​Crie a tabela

​Popular os dados

​Filtragem básica

​Filtragem por múltiplas chaves

​Uso de chaves para ordenação

Verificando sua chave primária

Crie a tabela

Popular os dados

Filtragem básica

Filtragem por múltiplas chaves

Uso de chaves para ordenação