Metabase ClickHouse 驱动完全指南从连接配置到查询下推的完整指南【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase本指南围绕 Metabase 仓库中modules/drivers/clickhouse/官方 ClickHouse 驱动展开系统讲解驱动的来源背景、连接参数配置、数据库同步机制、查询编译下推、类型映射与时间语义等核心能力。读完本文你将掌握如何在 Metabase 中接入 ClickHouse含自托管与 ClickHouse Cloud、如何通过 JDBC 高级选项与 HTTP 连接池调优性能以及驱动内部MBQL → SQL翻译链路与测试验证方法。驱动背景从合作伙伴驱动到官方内置驱动Metabase 的 ClickHouse 驱动最初由 ClickHouse 团队在合作伙伴驱动计划Partner Driver Program下开发并维护随后被正式并入 Metabase 主线仓库成为官方支持的驱动。这一点在 modules/drivers/clickhouse/README.md 中有明确记载原项目托管于 ClickHouse 官方组织metabase-clickhouse-driver现已合并进 Metabase 作为官方驱动主要贡献者包括 Felix Muellerenqueue、Bogdan MukvichBadya、tsl-karlp、Andrew Grigorevei-grad。驱动的实际代码位于 modules/drivers/clickhouse/src/metabase/driver/ 目录由五个相互协作的源文件构成文件职责clickhouse.clj驱动注册、连接细节到 JDBC spec 的转换、能力声明feature flags、表 DDL、角色切换clickhouse_qp.clj查询处理器Query Processor的方言翻译日期函数、时间戳转换、聚合、字符串函数、结果集读取clickhouse_introspection.clj元数据内省库/表/字段的发现、ClickHouse 类型到 Metabase base-type 的映射clickhouse_version.clj版本探测含 60 分钟 TTL 缓存与最小版本分支逻辑clickhouse_nippy.cljNippy 序列化扩展用于缓存内部传输驱动的依赖声明见 modules/drivers/clickhouse/deps.edn其核心是官方com.clickhouse/clickhouse-jdbc0.9.8并对部分传递依赖做了固定版本与替换httpcore5-h25.4.3、httpclient55.6.4以及已停更的org.lz4/lz4-java的维护分支at.yawk.lz4/lz4-java1.11.1。提示本文介绍的是当前仓库主线代码所对应的驱动实现。若需了解驱动合并前的历史演进可查看原项目维护的 HISTORY 文档此处不再展开。在 Metabase 中添加 ClickHouse 数据库连接入口与基本流程连接入口遵循 Metabase 的标准流程点击右上角网格图标进入管理员设置Admin→ 数据库Databases→ 添加数据库Add a database选择 ClickHouse 即可。创建后可通过连接与同步Connection and sync区域随时编辑连接详情、触发模式同步与字段值重扫。驱动在 clickhouse.clj 中通过(driver/register! :clickhouse :parent #{:sql-jdbc})完成注册显示名为 ClickHouse并以:sql-jdbc作为父驱动从而继承 Metabase 通用 SQL 驱动层的能力。连接字段详解官方用户文档 docs/databases/connections/clickhouse.md 对连接表单的各字段做了完整说明结合驱动源码可将它们一一对应到 JDBC 连接细节表单字段说明对应驱动实现连接字符串Connection string粘贴连接串可预填其余字段驱动支持从 URL 中解析 host 等参数显示名称Display name数据库中在 Metabase 界面中显示的名字—主机Host数据库 IP如98.137.149.56或域名如name.database.com旧版 JDBC 也接受http:///https://前缀驱动会自动剥离http://与https://前缀后再拼 JDBC URL见 clickhouse.clj端口Port默认8123HTTP 端口default-connection-details中默认:port 8123用户名Username连接账号可创建多个不同权限的账号分别连接默认用户default密码Password账号密码默认为空字符串数据库Databases可查询的数据库列表多个库用空格分隔如db1 db2 db3旧版配置中多个库名由空格/逗号分隔驱动取第一个作为连接默认库其余库通过限定名访问见 clickhouse.clj扫描所有数据库Scan all databases扫描除系统库外的所有 ClickHouse 库对应enable-multiple-db开关见下文多库同步使用安全连接SSL配置 SSL 证书详见 SSL 证书文档映射为 JDBC spec 中的:ssl (boolean ssl)使用 SSH 隧道无法直连时使用详见 SSH 隧道文档—禁用系统级代理默认关闭系统级代理可手动禁用:host-carrying-parameters中包含proxy_hostnon-host-parameters中包含proxy_password/proxy_port/proxy_type/proxy_user等见 clickhouse.clj驱动在 connection-details-spec 中组装最终 JDBC 属性关键默认值如下驱动类com.clickhouse.jdbc.ClickHouseDriver子协议clickhouseJDBC URL 形如jdbc:clickhouse://host:port/dbnameuse_server_time_zone_for_dates true日期值按服务器时区解析http_connection_provider HTTP_URL_CONNECTION使用 JDK 原生 HTTP URL 连接而非 Apache HttpClientjdbc_ignore_unsupported_values true忽略 JDBC 不支持的取值避免数据浏览崩溃remember_last_set_roles true记住最近一次SET ROLE的结果max_open_connections默认100即表单中的JDBC 驱动最大 HTTP 连接数custom_http_params默认注入select_sequential_consistency1并与用户填写的 ClickHouse 设置合并。此外驱动在加载时会设置系统属性clickhouse.jdbc.v2 true启用 JDBC v2 客户端 API见 clickhouse.clj。ClickHouse 设置逗号分隔在ClickHouse settings字段中可以追加额外设置多个设置以逗号分隔例如allow_experimental_analyzer1,max_result_rows100这些设置会与驱动默认注入的select_sequential_consistency1一并拼入 JDBC 的custom_http_params参数。需要注意的是allow_experimental_analyzer这类开关与 ClickHouse 服务端版本强相关旧版本可能不存在该设置配置前请确认目标服务端版本。附加 JDBC 连接字符串选项若需要更多底层控制可以在Additional JDBC connection string options中追加 JDBC 选项多个选项以分隔所有服务端设置必须以clickhouse_setting_为前缀例如clickhouse_setting_connection_timeout1000clickhouse_setting_socket_timeout300000驱动在 handle-additional-options 中将这些选项以 URL 风格拼接到 JDBC 连接串上。此类选项面向高级场景如调整连接/套接字超时、开启服务端日志等。连接测试的实现细节正常情况下Metabase 会走sql-jdbc.conn/can-connect?的通用实现而在测试模式下驱动则改用更严格的检查——通过SELECT count(*) 0 FROM system.databases WHERE name ?验证目标数据库确实存在见 clickhouse.clj因为默认的SELECT 1不足以支撑测试套件的语义。连接失败时的报错提示也有定制若错误消息匹配AUTHENTICATION_FAILEDMetabase 会提示用户名或密码不正确见 clickhouse.clj。元数据同步库、表、字段的发现与类型映射排除系统库与多库同步ClickHouse 自带大量系统库与内部表驱动在同步时默认排除system、information_schema、INFORMATION_SCHEMA三个 schema并过滤掉物化视图内部产生的.inner*表见 clickhouse_introspection.clj。允许同步的表类型包括 TABLE、VIEW、FOREIGN TABLE、REMOTE TABLE、DICTIONARY、MATERIALIZED VIEW、MEMORY TABLE、LOG TABLE。当连接详情中开启enable-multiple-db对应表单Scan all databases时驱动会遍历所有数据库同时支持通过db-filters-patterns逗号分隔的库名模式与db-filters-typeinclusion包含 /exclusion排除精确控制同步范围见 clickhouse_introspection.clj。ClickHouse 类型 → Metabase 基础类型映射驱动通过正则模式匹配完成类型翻译见 clickhouse_introspection.cljClickHouse 类型Metabase base-typeBool:type/BooleanInt8/16/32、UInt8/16/32:type/IntegerInt64、UInt64:type/BigIntegerFloat32/64:type/FloatDecimal:type/DecimalString:type/TextFixedString:type/TextLikeDate、Date32:type/DateDateTime、DateTime64:type/DateTime带时区时:type/DateTimeWithLocalTZEnum8/16:type/TextIPv4/IPv6:type/IPAddressUUID:type/UUIDArray:type/ArrayMap:type/DictionaryTuple:type/*normalize-db-type会递归剥离LowCardinality(...)、Nullable(...)、SimpleAggregateFunction(...)外壳后再做映射见 clickhouse_introspection.clj。例如Nullable(DateTime)→:type/DateTimeEnum8(UInt8)→:type/TextSimpleAggregateFunction(sum, Int64)→:type/BigIntegerDateTime64(3, Europe/Amsterdam)→:type/DateTimeWithLocalTZ字段的必填not-null属性也由database-required派生类型以Nullable开头则为可空否则必填同时会跳过 JDBC 无法支持、会导致数据浏览器崩溃的AggregateFunction(...)列保留SimpleAggregateFunction见 clickhouse_introspection.clj。主键探测JDBC v2 客户端已能提供主键元数据因此在非测试环境下驱动会调用通用实现获取主键见 clickhouse_introspection.clj。不过驱动将:metadata/key-constraints能力声明为false见 clickhouse.clj即 Metabase 不会基于外键约束建立自动关联——这与 ClickHouse 本身不支持外键约束的事实一致describe-fks直接告警并返回 nil。查询编译与下推MBQL 如何翻译为 ClickHouse SQL方言注册与引用风格驱动基于 HoneySQL 注册了::clickhouse方言引用风格quote style以 MySQL 为基础但对反斜杠做了额外转义见 clickhouse_qp.clj。标识符使用反引号包裹且采用反斜杠转义而非双写反引号见 clickhouse.clj。日期与时间函数映射驱动将 MBQL 的时间粒度temporal unit翻译为 ClickHouse 原生函数见 clickhouse_qp.cljMBQL 时间提取/截断ClickHouse 函数day-of-weektoDayOfWeek经adjust-day-of-week调整为周一为一周起点month-of-year / hour-of-day / minute-of-hour / day-of-month / day-of-yeartoMonth/toHour/toMinute/toDayOfMonth/toDayOfYearweek-of-year-isotoISOWeekquarter-of-yeartoQuarteryear-of-eratoYearminute / hour / daytoStartOfMinute/toStartOfHour/toStartOfDayweektoMonday即toStartOfWeekmonth / quarter / yeartoStartOfMonth/toStartOfQuarter/toStartOfYear一个值得注意的细节toStartOfWeek/Month/Quarter/Year在 ClickHouse 中返回Date而非DateTime。当这类截断结果在后续聚合阶段被引用时驱动会将列的有效类型从:type/DateTime降级为:type/Date避免把Date再包进toTimeZoneClickHouse 会报 Code 43 错误详见 clickhouse_qp.clj。时区语义上驱动遵循报表时区优先策略当数据库列带时区且与报表时区不一致时会用toTimeZone包装没有时区的DateTime也会被包装进报表时区。now()在设置了报表时区时翻译为now64(9, report-timezone)见 clickhouse_qp.clj。聚合与表达式翻译百分位percentile→quantile(p)(field)见 clickhouse_qp.clj标准差 / 方差 / 中位数stddev→stddevPop、var→varPop、median→median见 clickhouse_qp.clj条件计数/求和count-where使用sum(CASE WHEN pred THEN 1 ELSE 0 END)形式sum-where同理见 clickhouse_qp.clj偏移窗口函数offset→leadInFrame/lagInFrame配合ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING见 clickhouse_qp.clj间隔相加add-interval翻译为expr INTERVAL n unit支持 millisecond 到 year 共 9 种单位见 clickhouse_qp.clj。字符串匹配与编码细节字符串的starts-with/ends-with在 ClickHouse23.8 及以上使用 UTF-8 感知函数startsWithUTF8/endsWithUTF8更早版本回退到非 UTF-8 版本见 clickhouse_qp.cljcontains使用positionUTF8/positionCaseInsensitiveUTF8见 clickhouse_qp.clj。这在测试环境中由 docker-compose 中同时提供latest-alpine与 23.3 旧版服务来覆盖验证。substring对 Enum 列会先toString再截取见 clickhouse_qp.clj。字面量与结果集读取驱动为各类型定义了内联字面量格式inline-value日期yyyy-MM-dd、带纳秒的时间用parseDateTimeBestEffort/parseDateTime64BestEffort包裹、数组渲染为[a, b]、Map 渲染为{k:v}、UUID 参数替换为CAST(... AS UUID)见 clickhouse_qp.clj。结果集读取方面read-column-thunk有若干针对 ClickHouse 的适配TINYINT/SMALLINT用getObject避免类型换算INTEGER/BIGINT读取后用wasNull显式判空JDBC 的getInt/getLong对 NULL 会返回 0count列按Long读取UInt64太大通用路径会落到BigDecimal但 Metabase 测试期望 LongDATE转为LocalDateTIMESTAMP先取ZonedDateTime再换算到报表时区最后输出OffsetDateTimeUTC 基准IPv4/IPv6列读取为地址字符串ARRAY读取为Arrays.deepToString的字符串形式Enum8/16列按String读取。原生 SQL 美化原生查询的格式化由prettify-native-form提供驱动复用 MySQL 的 SQL 格式化与参数修正逻辑见 clickhouse.clj。表能力DDL、索引与数据写入能力声明Feature Flags驱动在 clickhouse.clj 中集中声明了全部能力值得关注的项包括:schemas true、:set-timezone true、:now true、:datetime-diff true、:expression-literals true:native-pivot-tables true原生查询可直接产出透视表:transforms/python true、:transforms/table true支持 Metabase 的数据变换Transforms功能:standard-deviation-aggregations true、:window-functions/offset true:actions false、:convert-timezone false、:database-routing false:rename true支持原子引擎下的RENAME TABLE见 clickhouse.clj。建表与索引管理驱动create-table!生成 MergeTree 引擎表仅适用于 ClickHouse Cloud 与单节点自托管见 clickhouse.cljCREATE TABLE ... ENGINE MergeTree ORDER BY (col1, col2) SETTINGS replicated_deduplication_window 0, allow_nullable_key 1replicated_deduplication_window 0用于禁用插入幂等去重允许重复插入当存在排序键且目标列可空时自动追加allow_nullable_key 1。索引管理同时覆盖两种生命周期见 clickhouse.clj排序键Sorting key即 MergeTree 的ORDER BY在建表时内联生成数据跳过索引Data-skipping index建表后以独立语句创建支持minmax最小值/最大值与bloom_filter布隆过滤两种无参数类型创建时执行两条语句——ALTER TABLE ... ADD INDEX ... TYPE ... GRANULARITY n注册元数据随后ALTER TABLE ... MATERIALIZE INDEX ...对已有分区回填。驱动还会从system.data_skipping_indices与system.tables.sorting_key读取已有索引供 Metabase 展示fetch-table-indexes。数据上传与类型映射上传Uploads仅当服务端运行在 ClickHouse Cloud 时启用database-supports? :uploads检查dbms-version :cloud见 clickhouse.clj。上传时 Metabase 通用类型映射为 ClickHouse 类型见 clickhouse.cljMetabase 上传类型ClickHouse 类型varchar-255 / textNullable(String)intNullable(Int64)floatNullable(Float64)booleanNullable(Boolean)dateNullable(Date32)datetimeNullable(DateTime64(3))写入操作通过insert-into!使用 PreparedStatement 批量addBatch/executeBatch执行并对 Java 类型String/Boolean/Long/Double/BigInteger/LocalDate/LocalDateTime/OffsetDateTime做了逐类 setter 分派见 clickhouse.clj。连接安全用户模拟User Impersonation当 ClickHouse 服务端版本不低于24.4时驱动支持连接用户模拟connection-impersonation见 clickhouse.clj。实现上每次连接建立后执行SET ROLE role默认角色为NONEdefault-database-role由于 ClickHouse 没有协议层安全的预编译语句与quote_ident()函数角色标识符在客户端完成转义按:ansibackslashes风格整体引号包裹角色名中的逗号保持为单个角色见 clickhouse.cljset-role!明确拒绝参数化语句改用原生Statement执行见 clickhouse.clj。这一能力对应测试 clickhouse_impersonation_test.clj可配合 Metabase 的行级/列级权限实现细粒度数据隔离。版本探测与兼容性策略驱动通过 clickhouse_version.clj 探测服务端版本执行WITH s AS (SELECT version() AS ver, splitByChar(., ver) AS verSplit) SELECT s.ver, toInt32(verSplit[1]), toInt32(verSplit[2]) FROM s得到主/次版本号同时查询system.settings中cloud_mode1判断是否为 ClickHouse Cloud。结果按数据库连接细节缓存60 分钟TTL 仅用于淘汰旧条目、控制缓存体积。基于版本号驱动提供is-at-least?与with-min两个分支工具见 clickhouse_version.clj典型用途是字符串函数在 23.8 前后切换 UTF-8 变体、以及 24.4 以上才启用用户模拟。兼容性下限方面仓库的数据库启动脚本将 ClickHouse 最低支持版本定为23.3见 mage/src/mage/start_db.cljdocker-compose 中同时准备了 latest 与 23.3 两套测试实例。本地测试环境用 Docker 起一套 ClickHouse驱动仓库自带完整的 Docker 测试编排 modules/drivers/clickhouse/docker-compose.yml包含四类服务服务用途端口映射clickhouse单节点latest-alpine驱动与 Metabase 主测试用8123 / 9000clickhouse_tls单节点 TLS 变体专用于 SSL 相关测试8443 / 9440clickhouse_older_version23.3 旧版覆盖 23.8 的字符串函数分支8124 / 9001clickhouse_cluster_node1/node2nginx两节点集群 Nginx 轮询负载均衡专用于SET ROLE与集群场景测试8125/8126节点、8127Nginx所有实例均设置CLICKHOUSE_SKIP_USER_SETUP1并调大nofile软硬限制至 262144单节点服务挂载 init.sql 在首次启动时创建一个含特殊字符的库SpecialCharacters~用于验证驱动对特殊字符库名的处理。镜像版本为clickhouse/clickhouse-server:latest-alpine与:23.3-alpine。注意端口已在 compose 中固定仓库开发脚本明确禁止为 ClickHouse 额外指定--port见 mage/src/mage/start_db.clj。对应的驱动测试集中在 modules/drivers/clickhouse/test/ 下覆盖数据类型映射、内省同步、参数替换、时间粒度分桶、用户模拟与主流程测试例如 clickhouse_substitution_test.clj 验证了DateTime/DateTime64列上日期参数的正确下推。常见问题与排查指引连接失败提示用户名或密码不正确驱动通过错误消息中的AUTHENTICATION_FAILED特征识别认证问题请核对用户名、密码及服务端账号权限。toTimeZone报 Code 43通常是Date类型的截断结果被当作DateTime处理当前驱动已在-honeysql [:clickhouse :field]中做类型降级若遇到异常请确认升级到包含该修复的版本。同步不到某些表先确认库是否在排除列表system、information_schema以及表是否为.inner开头的物化视图内部表多库场景下检查db-filters-type与db-filters-patterns配置。AggregateFunction列导致数据浏览崩溃驱动会自动跳过此类列SimpleAggregateFunction除外这是已知的 JDBC 兼容性边界。上传功能不可用上传仅在 ClickHouse Cloud 上启用自托管单节点需通过其他方式导入数据。时区结果与预期不符检查 Metabase 的报表时区设置与列类型是否带时区DateTime64(n, TZ)驱动按报表时区优先策略换算。更多通用排查手段可参考 数据库连接排障、同步与指纹扫描 等官方文档危险操作相关的连接设置清理见 Danger zone。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考