> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/pt-BR/reference/data-types/int-uint)  ou [`Bool`](/pt-BR/reference/data-types/boolean) | O ClickHouse oferece suporte a `Boolean` como alias de `UInt8` nas versões mais recentes. |
| `keyword` | [`String`](/pt-BR/reference/data-types/string) | Usado para filtragem por correspondência exata, agrupamento e ordenação. |
| `text` | [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/int-uint) | Inteiro com sinal de 64 bits. |
| `integer` | [`Int32`](/pt-BR/reference/data-types/int-uint) | Inteiro com sinal de 32 bits. |
| `short` | [`Int16`](/pt-BR/reference/data-types/int-uint) | Inteiro com sinal de 16 bits. |
| `byte` | [`Int8`](/pt-BR/reference/data-types/int-uint) | Inteiro com sinal de 8 bits. |
| `unsigned_long` | [`UInt64`](/pt-BR/reference/data-types/int-uint) | Inteiro sem sinal de 64 bits. |
| `double` | [`Float64`](/pt-BR/reference/data-types/float) | Ponto flutuante de 64 bits. |
| `float` | [`Float32`](/pt-BR/reference/data-types/float) | Ponto flutuante de 32 bits. |
| `half_float` | [`Float32`](/pt-BR/reference/data-types/float) ou [`BFloat16`](/pt-BR/reference/data-types/float) | 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)`](/pt-BR/reference/data-types/decimal) | Armazena valores numéricos de ponto fixo. |
| `date` | [`DateTime`](/pt-BR/reference/data-types/datetime) | Tipos de data equivalentes com precisão de segundos. |
| `date_nanos` | [`DateTime64`](/pt-BR/reference/data-types/datetime64) | O ClickHouse oferece suporte a precisão de nanossegundos com `DateTime64(9)`. |
| `binary` | [`String`](/pt-BR/reference/data-types/string), [`FixedString(N)`](/pt-BR/reference/data-types/fixedstring) | Requer decodificação em base64 para campos binários. |
| `ip` | [`IPv4`](/pt-BR/reference/data-types/ipv4), [`IPv6`](/pt-BR/reference/data-types/ipv6) | Tipos nativos `IPv4` e `IPv6` disponíveis. |
| `object` | [`Nested`](/pt-BR/reference/data-types/nested-data-structures/index), [`Map`](/pt-BR/reference/data-types/map), [`Tuple`](/pt-BR/reference/data-types/tuple), [`JSON`](/pt-BR/reference/data-types/newjson) | O ClickHouse pode modelar objetos semelhantes a JSON usando [`Nested`](/pt-BR/reference/data-types/nested-data-structures/index) ou [`JSON`](/pt-BR/reference/data-types/newjson). |
| `flattened` | [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/nested-data-structures/index) | 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`](/pt-BR/reference/statements/create/table#alias) | Aliases [são suportados](/pt-BR/reference/statements/create/table#alias) 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)`](/pt-BR/reference/data-types/tuple) ou [`Array(T)`](/pt-BR/reference/data-types/array) | 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)`](/pt-BR/reference/data-types/tuple) ou [`Array`](/pt-BR/reference/data-types/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(...)`](/pt-BR/reference/data-types/aggregatefunction) e [`SimpleAggregateFunction(...)`](/pt-BR/reference/data-types/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))`](/pt-BR/reference/data-types/tuple) | Represente manualmente buckets e contagens usando arrays ou esquemas personalizados. |
| `annotated-text` | [`String`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/string-search-functions). |
| `semantic_text` | NA | Não há busca semântica nativa — gere embeddings e use busca vetorial. |
| `token_count` | [`Int32`](/pt-BR/reference/data-types/int-uint) | 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)`](/pt-BR/reference/data-types/array) | Use arrays para armazenar embeddings |
| `sparse_vector` | [`Map(UInt32, Float32)`](/pt-BR/reference/data-types/map) | Simule vetores esparsos com maps. Não há suporte nativo a vetores esparsos. |
| `rank_feature` / `rank_features` | [`Float32`](/pt-BR/reference/data-types/float), [`Array(Float32)`](/pt-BR/reference/data-types/array) | Sem boosting nativo no momento da consulta, mas isso pode ser modelado manualmente na lógica de pontuação. |
| `geo_point` | [`Tuple(Float64, Float64)`](/pt-BR/reference/data-types/tuple) ou [`Point`](/pt-BR/reference/data-types/geo#point) | Use uma tupla de (latitude, longitude). [`Point`](/pt-BR/reference/data-types/geo#point) está disponível como um tipo do ClickHouse. |
| `geo_shape`, `shape` | [`Ring`](/pt-BR/reference/data-types/geo#ring), [`LineString`](/pt-BR/reference/data-types/geo#linestring), [`MultiLineString`](/pt-BR/reference/data-types/geo#multilinestring), [`Polygon`](/pt-BR/reference/data-types/geo#polygon), [`MultiPolygon`](/pt-BR/reference/data-types/geo#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`](/pt-BR/reference/data-types/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. |

<div id="notes">
  ### Notas
</div>

* **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](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/multi-fields#_multi_fields_with_multiple_analyzers) (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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/map) para o tipo [`JSON`](/pt-BR/reference/data-types/newjson) aprimorado do ClickHouse. O tipo [`JSON`](/pt-BR/reference/data-types/newjson) 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`](/pt-BR/reference/data-types/newjson) é 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`](/pt-BR/reference/data-types/map) em campos de atributos dinâmicos.

    Para mais detalhes sobre o tipo JSON, recomendamos o [guia de JSON](/pt-BR/guides/clickhouse/data-formats/json/intro) e ["How we built a new powerful JSON data type for ClickHouse"](https://clickhouse.com/blog/a-new-powerful-json-data-type-for-clickhouse).