Tipos de mapeamento

Tipos de mapeamento no ClickHouse e no Elasticsearch

Elasticsearch e ClickHouse oferecem suporte a uma grande variedade de tipos de dados, mas seus modelos subjacentes de armazenamento e consulta são fundamentalmente diferentes. Esta seção relaciona os tipos de campo do Elasticsearch mais usados aos seus equivalentes no ClickHouse, quando disponíveis, e fornece contexto para orientar migrações. Quando não houver equivalente, são fornecidas alternativas ou observações nos comentários.

Tipo do Elasticsearch	Equivalente no ClickHouse	Observações
boolean	UInt8 ou Bool	O ClickHouse oferece suporte a Boolean como alias de UInt8 nas versões mais recentes.
keyword	String	Usado para filtragem por correspondência exata, agrupamento e ordenação.
text	String	A busca em texto completo é limitada no ClickHouse; a tokenização exige lógica personalizada usando funções como tokens, combinadas com funções de array.
long	Int64	Inteiro com sinal de 64 bits.
integer	Int32	Inteiro com sinal de 32 bits.
short	Int16	Inteiro com sinal de 16 bits.
byte	Int8	Inteiro com sinal de 8 bits.
unsigned_long	UInt64	Inteiro sem sinal de 64 bits.
double	Float64	Ponto flutuante de 64 bits.
float	Float32	Ponto flutuante de 32 bits.
half_float	Float32 ou BFloat16	Equivalente mais próximo. O ClickHouse não tem um float de 16 bits. O ClickHouse tem BFloat16 — ele é diferente de half-float IEEE-754: o half-float oferece maior precisão com um intervalo menor, enquanto o bfloat16 sacrifica precisão em troca de um intervalo maior, o que o torna mais adequado para workloads de machine learning.
scaled_float	Decimal(x, y)	Armazena valores numéricos de ponto fixo.
date	DateTime	Tipos de data equivalentes com precisão de segundos.
date_nanos	DateTime64	O ClickHouse oferece suporte a precisão de nanossegundos com DateTime64(9).
binary	String, FixedString(N)	Requer decodificação em base64 para campos binários.
ip	IPv4, IPv6	Tipos nativos IPv4 e IPv6 disponíveis.
object	Nested, Map, Tuple, JSON	O ClickHouse pode modelar objetos semelhantes a JSON usando Nested ou JSON.
flattened	String	O tipo flattened no Elasticsearch armazena objetos JSON inteiros como campos únicos, permitindo acesso flexível e sem esquema a chaves aninhadas sem mapeamento completo. No ClickHouse, funcionalidade semelhante pode ser obtida usando o tipo String, mas o processamento precisa ser feito em visões materializadas.
nested	Nested	As colunas Nested do ClickHouse fornecem semântica semelhante para subcampos agrupados, desde que os usuários usem flatten_nested=0.
join	NA	Não há um conceito direto de relacionamentos pai-filho. Isso não é necessário no ClickHouse, já que junções entre tabelas são suportadas.
alias	modificador de coluna Alias	Aliases são suportados por meio de um modificador de campo. Funções podem ser aplicadas a esses aliases, por exemplo size String ALIAS formatReadableSize(size_bytes)
range types (*_range)	Tuple(start, end) ou Array(T)	O ClickHouse não tem um tipo de intervalo nativo, mas intervalos numéricos e de data podem ser representados usando estruturas Tuple(start, end) ou Array. Para intervalos de IP (ip_range), armazene valores CIDR como String e avalie com funções como isIPAddressInRange(). Como alternativa, considere dicionários de lookup baseados em ip_trie para filtragem eficiente.
aggregate_metric_double	AggregateFunction(...) e SimpleAggregateFunction(...)	Use estados de função de agregação e visões materializadas para modelar métricas pré-agregadas. Todas as funções de agregação oferecem suporte a estados agregados.
histogram	Tuple(Array(Float64), Array(UInt64))	Represente manualmente buckets e contagens usando arrays ou esquemas personalizados.
annotated-text	String	Não há suporte nativo para busca com reconhecimento de entidades ou anotações.
completion, search_as_you_type	NA	Não há mecanismo nativo de preenchimento automático ou sugestões. Pode ser reproduzido com String e funções de busca.
semantic_text	NA	Não há busca semântica nativa — gere embeddings e use busca vetorial.
token_count	Int32	Use durante a ingestão para calcular manualmente a contagem de tokens, por exemplo com a função length(tokens()), como em uma coluna Materialized
dense_vector	Array(Float32)	Use arrays para armazenar embeddings
sparse_vector	Map(UInt32, Float32)	Simule vetores esparsos com maps. Não há suporte nativo a vetores esparsos.
rank_feature / rank_features	Float32, Array(Float32)	Sem boosting nativo no momento da consulta, mas isso pode ser modelado manualmente na lógica de pontuação.
geo_point	Tuple(Float64, Float64) ou Point	Use uma tupla de (latitude, longitude). Point está disponível como um tipo do ClickHouse.
geo_shape, shape	Ring, LineString, MultiLineString, Polygon, MultiPolygon	Suporte nativo a formas geoespaciais e indexação espacial.
percolator	NA	Não há o conceito de indexar consultas. Use SQL padrão + views materializadas incrementais em vez disso.
version	String	O ClickHouse não tem um tipo nativo para versão. Armazene versões como strings e use funções UDF personalizadas para fazer comparações semânticas, se necessário. Considere normalizar para formatos numéricos se forem necessárias consultas por intervalo.

​

Notas

• Arrays: No Elasticsearch, todos os campos oferecem suporte nativo a arrays. No ClickHouse, arrays precisam ser definidos explicitamente (por exemplo, Array(String)), com a vantagem de ser possível acessar e consultar posições específicas, por exemplo an_array[1].

• Multi-fields: O Elasticsearch permite indexar o mesmo campo de várias formas (por exemplo, como text e keyword). No ClickHouse, esse padrão precisa ser modelado usando colunas ou views separadas.

• Tipos Map e JSON - No ClickHouse, o tipo Map é comumente usado para modelar estruturas dinâmicas de chave-valor, como resourceAttributes e logAttributes. Esse tipo permite uma ingestão flexível sem esquema ao possibilitar a adição de chaves arbitrárias em tempo de execução — conceitualmente semelhante a objetos JSON no Elasticsearch. No entanto, há limitações importantes a considerar:

  • Tipos de valor uniformes: colunas Map no ClickHouse precisam ter um tipo de valor consistente (por exemplo, Map(String, String)). Valores de tipos mistos não são suportados sem coerção.
  • Custo de desempenho: acessar qualquer chave em um Map exige carregar o Map inteiro na memória, o que pode não ser ideal em termos de desempenho.
  • Sem subcolunas: diferentemente de JSON, chaves em um Map não são representadas como subcolunas reais, o que limita a capacidade do ClickHouse de indexar, comprimir e consultar com eficiência.

  Por causa dessas limitações, o ClickStack está migrando do Map para o tipo JSON aprimorado do ClickHouse. O tipo JSON resolve muitas das limitações do Map:

  • Armazenamento verdadeiramente colunar: cada caminho JSON é armazenado como uma subcoluna, permitindo compressão, filtragem e execução vetorizada de consultas de forma eficiente.

  • Suporte a tipos mistos: diferentes tipos de dados (por exemplo, inteiros, strings, arrays) podem coexistir no mesmo caminho sem coerção nem unificação de tipos.

  • Escalabilidade do sistema de arquivos: limites internos para chaves dinâmicas (max_dynamic_paths) e tipos (max_dynamic_types) evitam uma explosão de arquivos de coluna em disco, mesmo com conjuntos de chaves de alta cardinalidade.

  • Armazenamento denso: valores nulos e ausentes são armazenados de forma esparsa para evitar sobrecarga desnecessária.

    O tipo JSON é especialmente adequado para cargas de trabalho de observabilidade, oferecendo a flexibilidade da ingestão sem esquema com o desempenho e a escalabilidade dos tipos nativos do ClickHouse — o que o torna um substituto ideal para Map em campos de atributos dinâmicos.

    Para mais detalhes sobre o tipo JSON, recomendamos o guia de JSON e “How we built a new powerful JSON data type for ClickHouse”.