Map(LowCardinality(String), String). O ClickHouse também oferece suporte ao tipo JSON, com tipagem forte, e o ClickStack oferece suporte beta para usá-lo no lugar de Map.
Para cargas de trabalho típicas de observabilidade, recomendamos manter o esquema padrão baseado em Map. O tipo JSON está disponível para usuários que desejam avaliá-lo em cargas de trabalho com um conjunto pequeno e estável de chaves de atributo, mas não é o esquema recomendado para uso geral.
Por que Map é o padrão recomendado
Map(LowCardinality(String), String) armazena chaves e valores em uma única estrutura. A desvantagem histórica de Map era que ler uma única chave exigia ler toda a coluna de map. Isso não é mais verdade: o ClickHouse agora oferece suporte à serialização de map em buckets, que divide o map em buckets para que as consultas leiam apenas os buckets de que precisam. Em combinação com índices de texto nas chaves e nos valores do map — que é como o esquema padrão do ClickStack é configurado — isso torna Map seletivo e rápido na leitura, sem nenhum custo adicional de ingestão para novas chaves.
Na prática, isso significa:
- Custo de ingestão estável à medida que o número de chaves cresce. Adicionar uma nova chave de atributo não altera o layout da coluna em disco nem cria novos arquivos de coluna. O custo de ingestão é limitado pelo volume de dados, não pela cardinalidade das chaves.
- Sem explosão de metadados. O número de arquivos de coluna em disco não acompanha o número de chaves de atributo únicas.
- Lookups seletivos via índices. Índices de texto nas chaves e nos valores do map permitem lookups pontuais sem varrer todas as linhas.
- Comportamento previsível em alta vazão. Map lida com conjuntos de atributos variáveis e sem esquema definido, comuns em tracing e logs, sem sobrecarga por chave.
Por que não usar JSON por padrão
JSON adota uma abordagem diferente: na inserção, o ClickHouse cria dinamicamente uma subcoluna dedicada e fortemente tipada para cada path encontrado. Na leitura, isso é atraente, pois apenas as subcolunas solicitadas são lidas, os tipos são preservados e não é necessário fazer conversão de tipo durante a consulta.
A contrapartida aparece na ingestão. Criar e gerenciar muitas subcolunas dinâmicas introduz sobrecarga de escrita e complexidade nos metadados. Em workloads de observabilidade, que rotineiramente têm conjuntos de atributos muito grandes ou altamente dinâmicos e alta taxa de ingestão, essa sobrecarga é significativa. O limite max_dynamic_paths pode reduzir o impacto ao despejar paths extras em uma coluna compartilhada, mas acessar a coluna compartilhada é mais lento do que acessar subcolunas dedicadas, o que enfraquece a vantagem de leitura que motivou o uso de JSON em primeiro lugar.
Como a serialização de map em buckets elimina a maior parte da sobrecarga histórica de leitura de Map, a vantagem de JSON na leitura já não compensa seu custo de ingestão em workloads típicos de observabilidade.
Quando ainda vale a pena considerar JSON
- O conjunto de chaves dos seus atributos é pequeno e estável, ou seja, você não vê milhares de chaves exclusivas, e novas chaves aparecem raramente.
- A vazão de ingestão é modesta em relação à cardinalidade dos atributos.
- Você quer acesso fortemente tipado aos atributos, sem conversões em tempo de consulta (números continuam sendo números, booleanos continuam sendo booleanos).
- Você está disposto a operar uma funcionalidade beta no ClickStack e aceita que a integração pode mudar.
Map.
Status Beta
2.0.4.
Habilitando o suporte a JSON
Map, defina as seguintes variáveis de ambiente.
Managed ClickStack
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' no coletor. Por exemplo:
ClickStack de código aberto
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' em qualquer implantação que inclua o coletor e BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true na camada da aplicação HyperDX para que ela possa consultar os esquemas do tipo JSON.
Por exemplo:
Migrando de um esquema baseado em Map para JSON
1
Interrompa o OTel collector
2
Renomeie as tabelas existentes e atualize as fontes de dados
Renomeie as tabelas existentes e atualize as fontes de dados no HyperDX.Por exemplo:3
Implante o collector
Implante o collector comOTEL_AGENT_FEATURE_GATE_ARG definido.4
Reinicie o contêiner do HyperDX com suporte ao esquema JSON
5