Tipos de mapeamento | ClickHouse Docs

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".