Mapping types - ClickHouse Documentation

Elasticsearch and ClickHouse support a wide variety of data types, but their underlying storage and query models are fundamentally different. This section maps commonly used Elasticsearch field types to their ClickHouse equivalents, where available, and provides context to help guide migrations. Where no equivalent exists, alternatives or notes are provided in the comments.

Elasticsearch Type	ClickHouse Equivalent	Comments
`boolean`	`UInt8` or `Bool`	ClickHouse supports `Boolean` as an alias for `UInt8` in newer versions.
`keyword`	`String`	Used for exact-match filtering, grouping, and sorting.
`text`	`String`	Full-text search is limited in ClickHouse; tokenization requires custom logic using functions such as `tokens` combined with array functions.
`long`	`Int64`	64-bit signed integer.
`integer`	`Int32`	32-bit signed integer.
`short`	`Int16`	16-bit signed integer.
`byte`	`Int8`	8-bit signed integer.
`unsigned_long`	`UInt64`	Unsigned 64-bit integer.
`double`	`Float64`	64-bit floating-point.
`float`	`Float32`	32-bit floating-point.
`half_float`	`Float32` or `BFloat16`	Closest equivalent. ClickHouse doesn’t have a 16-bit float. ClickHouse has a `BFloat16`- this is different from Half-float IEE-754: half-float offers higher precision with a smaller range, while bfloat16 sacrifices precision for a wider range, making it better suited for machine learning workloads.
`scaled_float`	`Decimal(x, y)`	Store fixed-point numeric values.
`date`	`DateTime`	Equivalent date types with second precision.
`date_nanos`	`DateTime64`	ClickHouse supports nanosecond precision with `DateTime64(9)`.
`binary`	`String`, `FixedString(N)`	Needs base64 decoding for binary fields.
`ip`	`IPv4`, `IPv6`	Native `IPv4` and `IPv6` types available.
`object`	`Nested`, `Map`, `Tuple`, `JSON`	ClickHouse can model JSON-like objects using `Nested` or `JSON`.
`flattened`	`String`	The flattened type in Elasticsearch stores entire JSON objects as single fields, enabling flexible, schemaless access to nested keys without full mapping. In ClickHouse, similar functionality can be achieved using the String type, but requires processing to be done in materialized views.
`nested`	`Nested`	ClickHouse `Nested` columns provide similar semantics for grouped sub fields assuming users use `flatten_nested=0`.
`join`	NA	No direct concept of parent-child relationships. Not required in ClickHouse as joins across tables are supported.
`alias`	`Alias` column modifier	Aliases are supported through a field modifier. Functions can be applied to these alias e.g. `size String ALIAS formatReadableSize(size_bytes)`
`range` types (`*_range`)	`Tuple(start, end)` or `Array(T)`	ClickHouse has no native range type, but numerical and date ranges can be represented using `Tuple(start, end)` or `Array` structures. For IP ranges (`ip_range`), store CIDR values as `String` and evaluate with functions like `isIPAddressInRange()`. Alternatively, consider `ip_trie` based lookup dictionaries for efficient filtering.
`aggregate_metric_double`	`AggregateFunction(...)` and `SimpleAggregateFunction(...)`	Use aggregate function states and materialized views to model pre-aggregated metrics. All aggregation functions support aggregate states.
`histogram`	`Tuple(Array(Float64), Array(UInt64))`	Manually represent buckets and counts using arrays or custom schemas.
`annotated-text`	`String`	No built-in support for entity-aware search or annotations.
`completion`, `search_as_you_type`	NA	No native autocomplete or suggester engine. Can be reproduced with `String` and search functions.
`semantic_text`	NA	No native semantic search - generate embeddings and use vector search.
`token_count`	`Int32`	Use during ingestion to compute token count manually e.g. `length(tokens())` function e.g. with a Materialized column
`dense_vector`	`Array(Float32)`	Use arrays for embedding storage
`sparse_vector`	`Map(UInt32, Float32)`	Simulate sparse vectors with maps. No native sparse vector support.
`rank_feature` / `rank_features`	`Float32`, `Array(Float32)`	No native query-time boosting, but can be modeled manually in scoring logic.
`geo_point`	`Tuple(Float64, Float64)` or `Point`	Use tuple of (latitude, longitude). `Point` is available as a ClickHouse type.
`geo_shape`, `shape`	`Ring`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`	Native support for geo shapes and spatial indexing.
`percolator`	NA	No concept of indexing queries. Use standard SQL + Incremental Materialized Views instead.
`version`	`String`	ClickHouse doesn’t have a native version type. Store versions as strings and use custom UDFs functions to perform semantic comparisons if needed. Consider normalizing to numeric formats if range queries are required.

Notes

Arrays: In Elasticsearch, all fields support arrays natively. In ClickHouse, arrays must be explicitly defined (e.g., Array(String)), with the advantage specific positions can be accessed and queried e.g. an_array[1].
Multi-fields: Elasticsearch allows indexing the same field multiple ways (e.g., both text and keyword). In ClickHouse, this pattern must be modeled using separate columns or views.
Map and JSON Types - In ClickHouse, the Map type is commonly used to model dynamic key-value structures such as resourceAttributes and logAttributes. This type enables flexible schema-less ingestion by allowing arbitrary keys to be added at runtime — similar in spirit to JSON objects in Elasticsearch. However, there are important limitations to consider:
- Uniform value types: ClickHouse Map columns must have a consistent value type (e.g., Map(String, String)). Mixed-type values aren’t supported without coercion.
- Performance cost: accessing any key in a Map requires loading the entire map into memory, which can be suboptimal for performance.
- No subcolumns: unlike JSON, keys in a Map aren’t represented as true subcolumns, which limits ClickHouse’s ability to index, compress, and query efficiently.
Because of these limitations, ClickStack is migrating away from Map in favor of ClickHouse’s enhanced JSON type. The JSON type addresses many of the shortcomings of Map:
- True columnar storage: each JSON path is stored as a subcolumn, allowing efficient compression, filtering, and vectorized query execution.
- Mixed-type support: different data types (e.g., integers, strings, arrays) can coexist under the same path without coercion or type unification.
- File system scalability: internal limits on dynamic keys (max_dynamic_paths) and types (max_dynamic_types) prevent an explosion of column files on disk, even with high cardinality key sets.
- Dense storage: nulls and missing values are stored sparsely to avoid unnecessary overhead. The JSON type is especially well-suited for observability workloads, offering the flexibility of schemaless ingestion with the performance and scalability of native ClickHouse types — making it an ideal replacement for Map in dynamic attribute fields. For further details on the JSON type we recommend the JSON guide and “How we built a new powerful JSON data type for ClickHouse”.

​Notes

Notes