类型映射 | ClickHouse Docs

Elasticsearch 和 ClickHouse 都支持丰富的数据类型，但二者的底层存储和查询模型存在本质差异。本节将常用的 Elasticsearch 字段类型映射到对应的 ClickHouse 类型 (如果有) ，并提供相关背景信息以帮助指导迁移。对于没有对应类型的情况，我们也会在注释中提供替代方案或说明。

Elasticsearch 类型	ClickHouse 对应项	备注
`boolean`	`UInt8` 或 `Bool`	在较新版本中，ClickHouse 支持将 `Boolean` 作为 `UInt8` 的别名。
`keyword`	`String`	用于精确匹配过滤、分组和排序。
`text`	`String`	ClickHouse 的全文搜索能力有限；标记化需要借助自定义逻辑，例如将 `tokens` 与数组函数结合使用。
`long`	`Int64`	64 位有符号整数。
`integer`	`Int32`	32 位有符号整数。
`short`	`Int16`	16 位有符号整数。
`byte`	`Int8`	8 位有符号整数。
`unsigned_long`	`UInt64`	64 位无符号整数。
`double`	`Float64`	64 位浮点数。
`float`	`Float32`	32 位浮点数。
`half_float`	`Float32` 或 `BFloat16`	最接近的对应类型。ClickHouse 没有 16 位浮点类型。ClickHouse 提供 `BFloat16`，但它不同于 IEEE-754 half-float：half-float 以较小的范围换取更高精度，而 bfloat16 则牺牲精度以获得更大的范围，因此更适合机器学习工作负载。
`scaled_float`	`Decimal(x, y)`	用于存储定点数值。
`date`	`DateTime`	对应秒级精度的日期类型。
`date_nanos`	`DateTime64`	ClickHouse 可通过 `DateTime64(9)` 支持纳秒级精度。
`binary`	`String`, `FixedString(N)`	二进制字段需要进行 base64 解码。
`ip`	`IPv4`, `IPv6`	提供原生 `IPv4` 和 `IPv6` 类型。
`object`	`Nested`, `Map`, `Tuple`, `JSON`	ClickHouse 可使用 `Nested` 或 `JSON` 对类似 JSON 对象的结构进行建模。
`flattened`	`String`	Elasticsearch 中的 flattened 类型会将整个 JSON 对象存储为单个字段，从而无需完整映射即可灵活、无 schema 地访问嵌套键。在 ClickHouse 中，可使用 String 类型实现类似功能，但需要在 materialized view 中完成处理。
`nested`	`Nested`	在用户使用 `flatten_nested=0` 的前提下，ClickHouse 的 `Nested` 列可为成组子字段提供类似语义。
`join`	NA	没有直接对应的父子关系概念。在 ClickHouse 中通常不需要，因为支持跨表 join。
`alias`	`Alias` 列修饰符	可通过字段修饰符来支持别名。详见。例如，可对这些别名应用函数：`size String ALIAS formatReadableSize(size_bytes)`
`range` types (`*_range`)	`Tuple(start, end)` 或 `Array(T)`	ClickHouse 没有原生 range 类型，但数值范围和日期范围可用 `Tuple(start, end)` 或 `Array` 结构表示。对于 IP 范围 (`ip_range`) ，可将 CIDR 值存储为 `String`，并使用 `isIPAddressInRange()` 等函数进行判断。或者，也可以考虑使用基于 `ip_trie` 的 lookup 字典来实现高效过滤。
`aggregate_metric_double`	`AggregateFunction(...)` 和 `SimpleAggregateFunction(...)`	使用 aggregate function 状态和 materialized view 对预聚合指标进行建模。所有 aggregation 函数都支持 aggregate states。
`histogram`	`Tuple(Array(Float64), Array(UInt64))`	可使用数组或自定义 schema 手动表示桶及其计数。
`annotated-text`	`String`	不内置支持实体感知搜索或注解。
`completion`, `search_as_you_type`	NA	没有原生自动补全或建议器引擎。可通过 `String` 和 search functions 实现类似效果。
`semantic_text`	NA	不支持原生语义搜索；请生成嵌入向量并使用向量搜索。
`token_count`	`Int32`	可在摄取期间手动计算标记数，例如使用 `length(tokens())` 函数，或结合 Materialized 列实现。
`dense_vector`	`Array(Float32)`	使用数组存储嵌入向量。
`sparse_vector`	`Map(UInt32, Float32)`	可使用 Map 模拟稀疏向量。不支持原生稀疏向量。
`rank_feature` / `rank_features`	`Float32`, `Array(Float32)`	不支持原生的查询时权重提升，但可以在评分逻辑中手动实现。
`geo_point`	`Tuple(Float64, Float64)` 或 `Point`	使用 (纬度、经度) 的 Tuple。`Point` 也可作为 ClickHouse 类型使用。
`geo_shape`, `shape`	`Ring`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`	原生支持地理形状和空间索引。
`percolator`	NA	没有“为查询建立索引”这一概念。请改用标准 SQL + 增量materialized views。
`version`	`String`	ClickHouse 没有原生版本类型。请将版本存储为字符串，并在需要时使用自定义 UDF 函数进行语义化比较。如果需要范围查询，可考虑将其规范化为数值格式。

说明

数组：在 Elasticsearch 中，所有字段都原生支持数组。在 ClickHouse 中，数组必须显式定义 (例如 Array(String)) ；其优势是可以访问和查询特定位置的元素，例如 an_array[1]。
多字段：Elasticsearch 允许以多种方式索引同一字段 (例如同时使用 text 和 keyword) 。在 ClickHouse 中，这种模式必须通过单独的列或视图来建模。
Map 和 JSON 类型 - 在 ClickHouse 中，Map 类型通常用于表示动态键值结构，例如 resourceAttributes 和 logAttributes。该类型允许在运行时添加任意键，从而实现灵活的无 schema 摄取——这与 Elasticsearch 中的 JSON 对象在理念上类似。不过，也有一些重要限制需要注意：
- 统一的值类型：ClickHouse 的 Map 列必须具有一致的值类型 (例如 Map(String, String)) 。如果不进行强制类型转换，则不支持混合类型的值。
- 性能开销：访问 Map 中的任意键，都需要将整个 map 加载到内存中，这对性能而言可能并不理想。
- 不支持子列：与 JSON 不同，Map 中的键不会表示为真正的子列，这限制了 ClickHouse 高效进行索引、压缩和查询的能力。
由于这些限制，ClickStack 正在逐步弃用 Map，转而采用 ClickHouse 增强后的 JSON 类型。JSON 类型弥补了 Map 的许多不足：
- 真正的列式存储：每个 JSON 路径都会存储为一个子列，从而实现高效的压缩、过滤和向量化查询执行。
- 支持混合类型：不同的数据类型 (例如整数、字符串、数组) 可以在同一路径下共存，而无需强制转换或类型统一。
- 文件系统可扩展性：对动态键 (max_dynamic_paths) 和类型 (max_dynamic_types) 的内部限制，即使在高基数键集合的情况下，也能防止磁盘上的列文件数量激增。
- 紧凑存储：NULL 和缺失值会以稀疏方式存储，以避免不必要的开销。
  
  JSON 类型尤其适合可观测性工作负载，既具备无 schema 摄取的灵活性，又拥有 ClickHouse 原生类型的性能和可扩展性——因此，它是动态属性字段中替代 Map 的理想选择。
  
  如需进一步了解 JSON 类型，我们建议阅读 JSON 指南和 "How we built a new powerful JSON data type for ClickHouse"。