Runbook: esquema para JSON

Seus dados chegam em JSON. O ClickHouse oferece várias maneiras de armazená-los, desde colunas totalmente tipadas até uma String bruta. A escolha certa depende de quão previsível é o seu esquema e de você precisar ou não de consultas em nível de campo.

Escopo: Esta página aborda decisões de modelagem de esquema para armazenar dados JSON. Ela não cobre formatos de entrada/saída JSON, funções JSON nem a sintaxe de consultas. Para mais contexto sobre o próprio tipo de coluna JSON, consulte Use JSON where appropriate.

Pressupõe: Familiaridade com a criação de tabelas no ClickHouse, os conceitos básicos de MergeTree e a sintaxe de tipos de coluna.

• Se cada campo tiver um tipo conhecido e estável, e o esquema raramente mudar → Colunas tipadas
• Se a maioria dos campos for estável, mas alguma seção for dinâmica ou imprevisível → Híbrido (tipado + JSON)
• Se toda a estrutura for dinâmica, com chaves que aparecem e desaparecem entre registros → Coluna JSON nativa
• Se os campos dinâmicos forem pares chave-valor com um tipo de valor consistente (por exemplo, tags de texto, métricas numéricas) → Map em vez de JSON
• Se você só armazena e recupera o blob JSON sem consultas em nível de campo → Armazenamento opaco em String

Quando usar: A estrutura do JSON é totalmente conhecida na fase de modelagem. Os campos e tipos não mudam de um registro para outro. Mesmo estruturas aninhadas complexas (arrays de objetos, mapas aninhados) podem ser expressas com os tipos Array, Tuple e Nested.

Desvantagens: Alterações no esquema exigem ALTER TABLE. Campos inesperados são descartados silenciosamente durante a inserção, a menos que o esquema seja atualizado.

CREATE TABLE events
(
    `timestamp` DateTime,
    `service`   LowCardinality(String),
    `level`     Enum8('DEBUG' = 1, 'INFO' = 2, 'WARN' = 3, 'ERROR' = 4),
    `message`   String,
    `host`      LowCardinality(String),
    `duration_ms` UInt32
)
ENGINE = MergeTree
ORDER BY (service, timestamp)

-- Confirme se os tipos das colunas correspondem ao esperado
DESCRIBE TABLE events FORMAT Vertical

-- Insira dados e consulte para validar se o esquema lida com eles
INSERT INTO events FORMAT JSONEachRow
{"timestamp":"2025-03-19 10:00:00","service":"api","level":"INFO","message":"request handled","host":"node-1","duration_ms":42}

SELECT service, level, duration_ms FROM events WHERE service = 'api'

Quando usar: Um conjunto principal de campos é estável (timestamps, IDs, códigos de status), mas parte do payload é dinâmica. Pense em atributos definidos pelo usuário, tags, metadados ou campos de extensão que variam entre os registros.

Trade-offs: Desempenho total nas colunas tipadas e flexibilidade na coluna JSON. A coluna JSON ainda traz sobrecarga na inserção e custo de armazenamento para sua parte dinâmica.

CREATE TABLE events
(
    `timestamp`  DateTime,
    `service`    LowCardinality(String),
    `level`      Enum8('DEBUG' = 1, 'INFO' = 2, 'WARN' = 3, 'ERROR' = 4),
    `message`    String,
    `host`       LowCardinality(String),
    `duration_ms` UInt32,
    `attributes` JSON(
        max_dynamic_paths = 256,
        `http.status_code` UInt16,
        `http.method` LowCardinality(String),
        SKIP REGEXP 'debug\..*'
    )
)
ENGINE = MergeTree
ORDER BY (service, timestamp)

-- Insira dados de exemplo e inspecione os caminhos inferidos
INSERT INTO events FORMAT JSONEachRow
{"timestamp":"2025-03-19 10:00:00","service":"api","level":"INFO","message":"request handled","host":"node-1","duration_ms":42,"attributes":{"http.status_code":200,"http.method":"GET","user.region":"eu-west","custom_tag":"abc"}}

SELECT JSONAllPathsWithTypes(attributes)
FROM events
FORMAT PrettyJSONEachRow

Quando usar: A estrutura é realmente imprevisível, com chaves que aparecem e desaparecem entre registros. Esquemas gerados por usuários, sistemas de plugins ou ingestão em data lake em que você não controla o esquema upstream.

Trade-offs: Inserções mais lentas do que em colunas tipadas. Leituras do objeto completo mais lentas do que em String. Sobrecarga de armazenamento devido ao gerenciamento de subcolunas. Funciona bem para consultas em nível de campo em caminhos específicos.

CREATE TABLE dynamic_events
(
    `id`   UInt64,
    `ts`   DateTime DEFAULT now(),
    `data` JSON(
        max_dynamic_paths = 512,
        `event_type` LowCardinality(String),
        `version` UInt8
    )
)
ENGINE = MergeTree
ORDER BY (data.event_type, ts)

INSERT INTO dynamic_events (id, data) FORMAT JSONEachRow
{"id": 1, "data": {"event_type": "click", "version": 2, "page": "/home", "button_id": "cta-1"}}
{"id": 2, "data": {"event_type": "purchase", "version": 1, "item_id": "SKU-99", "amount": 49.99, "currency": "USD"}}

-- Verifique quais caminhos o ClickHouse detectou e seus tipos
SELECT JSONAllPathsWithTypes(data) FROM dynamic_events FORMAT PrettyJSONEachRow

-- Consulte um caminho específico
SELECT data.page FROM dynamic_events WHERE data.event_type = 'click'

Quando usar: Documentos JSON são armazenados e recuperados por inteiro e depois encaminhados para uma aplicação, arquivados ou enviados para sistemas downstream. Sem filtragem por campo nem agregação dentro do ClickHouse.

Trade-offs: inserts mais rápidos e esquema mais simples. Não há consulta em nível de campo sem parsing em tempo de execução (família JSONExtract), o que é lento em escala.

CREATE TABLE raw_events
(
    `id`        UInt64,
    `received`  DateTime DEFAULT now(),
    `payload`   String
)
ENGINE = MergeTree
ORDER BY (received)

INSERT INTO raw_events (id, payload) VALUES
(1, '{"type":"click","page":"/home"}'),
(2, '{"type":"purchase","item":"SKU-99","amount":49.99}')

-- Confirme que os dados permanecem intactos na ida e volta
SELECT payload FROM raw_events WHERE id = 1

-- Verifique que ainda é possível extrair campos de forma ad hoc quando necessário
SELECT JSONExtractString(payload, 'type') AS event_type FROM raw_events

Se seus campos dinâmicos forem pares chave-valor homogêneos — ou seja, todos os valores compartilham o mesmo tipo — Map(String, T) é mais simples e mais eficiente do que uma coluna JSON. Exemplos comuns: tags de string (Map(String, String)), métricas numéricas (Map(String, Float64)) ou feature flags (Map(String, Bool)).

CREATE TABLE tagged_events
(
    `timestamp` DateTime,
    `service`   LowCardinality(String),
    `tags`      Map(String, String)  -- e.g., {"env": "prod", "region": "us-east-1", "team": "platform"}
)
ENGINE = MergeTree
ORDER BY (service, timestamp)

Map oferece suporte à filtragem no nível da chave (tags['env'] = 'prod'), é mais barato de armazenar do que JSON e evita a sobrecarga de subcoluna do tipo JSON. Observe que as buscas de chave fazem uma varredura linear no map por padrão — isso é adequado para conjuntos pequenos de tags, mas, para maps com mais de 100 chaves, considere a serialização with_buckets. Use JSON quando os valores tiverem tipos mistos ou quando a estrutura tiver aninhamento — use Map quando forem pares chave-valor simples com um tipo de valor uniforme.

• Use JSON quando apropriado — quando usar o tipo de coluna JSON em vez de outras opções
• Referência do tipo de dados JSON — sintaxe completa para type hints, SKIP, max_dynamic_paths e funções de introspecção
• Escolhendo tipos de dados — orientações gerais para escolher tipos
• A New Powerful JSON Data Type for ClickHouse — análise detalhada da arquitetura de armazenamento do tipo JSON
• Referência dos formatos JSON — formatos de entrada/saída para dados JSON (JSONEachRow, JSONAsObject etc.)