简介这份《Kyligence Enterprise 3.4》中文PDF文档面向大数据分析工程师、Kylin运维人员及BI集成开发者系统讲解Apache Kylin的API接口与使用方式帮助读者在批处理、微批处理、Kafka流处理等场景中高效落地大数据分析。文档内容覆盖安装与配置、元数据存储、系统配置、数据源导入、模型与Cube设计、SQL查询、驱动与BI工具集成、安全控制等完整模块并针对CDH、HDP、MapR、华为FusionInsight等环境给出部署指引还涉及Cube优化器、查询下压、增量构建等进阶主题。资源包为1个PDF文件大小约96.06MB目录层级清晰便于按章节检索查阅。目前已有525人学习下载适合需要查阅Kylin API细节、搭建集群或对接Tableau、Power BI等工具的技术人员作为案头参考。1. 从一份 3.4 版中文手册说起企业级 OLAP 平台到底该怎么落地很多人第一次拿到 Kyligence Enterprise 3.4 的中文 PDF 手册时第一反应是「这不就是又一个 Hadoop 上的 MOLAP 引擎吗」。但真把它拉进生产环境跑一遍就会发现它解决的不是「能不能查」的问题而是「几百亿行明细、几十个并发分析师、还要亚秒级响应」这种企业级 OLAP 场景下的稳定性问题。这份 3.4 版中文文档覆盖了从安装部署、模型设计、Cube 构建到查询调优的完整链路适合两类人一是正在做数据仓库选型、被 Presto 或 Hive 的查询延迟折磨的架构师二是已经上手但卡在 Cube 膨胀、构建超时、内存打爆这些坑里的数据工程师。下面我按自己踩过的顺序把这份手册里最值得落地的部分拆开讲。2. 部署前先想清楚Kyligence Enterprise 3.4 的组件拓扑与资源账2.1 它到底由哪几个角色组成Kyligence Enterprise 3.4 的运行时不是单一进程而是一组协同角色。理解拓扑是后面调参的前提否则你连日志该去哪个节点看都不知道。角色职责常见部署位置元数据服务存模型、Cube 定义、任务状态独立节点接 MySQL/PostgreSQL构建引擎跑 Spark/MR 任务生成 Cube 段与 Hadoop 集群同网段查询服务接收 SQL、路由到 Cube 或下推多实例前置负载均衡协调节点任务调度、资源排队与元数据服务可合并常见做法是把查询服务和构建引擎物理隔离因为构建任务会吃满 CPU 和内存和查询抢资源时延迟会直接飙到秒级以上。我一般会在 YARN 队列层面就给构建任务单独划一个队列避免它把查询服务的资源挤掉。2.2 最小可用集群的资源估算手册里给的是理论下限但生产环境要按峰值并发反推。一个可参考的算法是查询服务单实例建议 16 核 64GB 起步每增加 10 个并发分析师加 8 核 16GB构建引擎按单次 Cube 构建的数据量算每 1TB 原始数据大约需要 200GB 内存做 shuffle。# 查询服务 JVM 参数示例放在启动脚本里 export KYLIN_QUERY_OPTS-Xms32g -Xmx32g \ -XX:UseG1GC \ -XX:MaxGCPauseMillis200 \ -XX:InitiatingHeapOccupancyPercent45这里-Xms和-Xmx设成一样是为了避免堆动态伸缩带来的停顿G1 的MaxGCPauseMillis设 200ms 是经验值再低会导致 GC 线程抢 CPU 反而拖慢查询InitiatingHeapOccupancyPercent45比默认的 45 略保守适合堆里大对象多的场景。如果查询服务频繁 Full GC先看是不是 Cube 段缓存把老年代撑满了而不是急着加堆。2.3 元数据库的选型和初始化元数据服务支持 MySQL 和 PostgreSQL我倾向 MySQL 8.0因为社区里排查问题的资料多。初始化时注意字符集必须是utf8mb4否则中文模型名会乱码。-- 创建元数据库 CREATE DATABASE kylin_meta DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_general_ci; -- 创建专用账号不要用 root CREATE USER kylin_rw% IDENTIFIED BY 强密码; GRANT ALL PRIVILEGES ON kylin_meta.* TO kylin_rw%; FLUSH PRIVILEGES;建完库之后用安装包里的init-meta.sh或等价脚本导入表结构。这一步翻车的典型表现是导入到一半报字段长度超限原因是 MySQL 的innodb_large_prefix没开或者行格式不是DYNAMIC。解决方法是建库时就指定ROW_FORMATDYNAMIC别等出错了再改。3. 模型设计把星型模型翻译成 Cube 的四个关键决策3.1 维度表和事实表的接入顺序手册里强调先接维度表再接事实表这不是随便写的。因为 Cube 的维度定义依赖维度表的列如果顺序反了后面改维度要重建整个模型。我一般会先把所有维度表按层级关系理一遍确认没有循环依赖再动事实表。接入维度表时有个容易忽略的点维度表的主键必须是单列且非空复合主键在 3.4 里支持得不好会在构建阶段报「无法确定维度成员」这种模糊错误。如果源表是复合主键先在视图层拼一个代理键。3.2 维度类型的选择普通维度、派生维度、层级维度这三种维度直接决定 Cube 的行数。普通维度就是直接映射一列派生维度是从某个维度再拆出来的列比如从「日期」派生「季度」层级维度是带上下级关系的比如「国家-省-市」。选错类型的代价是 Cube 膨胀。举个例子如果把「城市」做成普通维度而不是层级维度那么每个城市都会独立参与组合Cube 行数会多出一个数量级。判断标准很简单如果两个维度之间存在函数依赖就用层级维度。3.3 度量列和聚合函数怎么配度量列决定了 Cube 里预聚合什么。3.4 支持 SUM、COUNT、COUNT DISTINCT、MAX、MIN、TOP_N 等。这里有个血泪经验COUNT DISTINCT 的精度和内存消耗是矛盾的手册里默认用 HyperLogLog误差在 1% 左右。如果业务要求精确去重得改成精确算法但内存会涨 3 到 5 倍。{ measures: [ { name: order_count, function: COUNT, column: order_id }, { name: unique_buyer, function: COUNT_DISTINCT, column: buyer_id, precision: approx, max_cardinality: 1000000 } ] }precision设approx走 HLL设exact走精确位图max_cardinality是给优化器的一个提示设得太小会导致去重结果被截断设得太大浪费内存。我一般按实际基数的 1.5 倍来设。3.4 分区列和分片列的区别分区列是按时间切 Cube 段查询时能裁剪掉不相关的段分片列是把一个段内的数据按哈希打散到多个文件提升并行度。两者不能混用同一列。常见错误是把日期同时设成分区和分片结果构建时数据倾斜严重。正确做法是分区列用日期分片列用高基数的 ID 列比如shop_id或region_id。分片数建议设成构建引擎可用核数的 2 到 4 倍太少并行度不够太多小文件拖慢查询。4. 构建与查询从 Cube 任务提交到 SQL 命中的完整链路4.1 提交构建任务前必须检查的三件事第一源表分区是否有数据。我遇到过源表当天分区还没产出就提交构建结果 Cube 段是空的查询直接报「无可用数据」。第二Cube 定义的维度列在源表里是否存在列名大小写是否一致。第三构建队列是否有空闲资源否则任务会一直排队。# 通过 REST API 提交构建任务 curl -X PUT \ -H Content-Type: application/json \ -u admin:密码 \ -d { startTime: 1704067200000, endTime: 1704153600000, buildType: BUILD } \ http://coordinator-host:7070/kylin/api/cubes/项目名/cube名/buildstartTime和endTime是毫秒时间戳对应源表的分区范围buildType设BUILD是增量构建设REFRESH是全量重建。提交后别急着走用任务 ID 查状态确认进入RUNNING再离开。4.2 构建慢的排查顺序构建慢通常卡在三个阶段读源数据、shuffle、写 HDFS。排查顺序是先从构建日志里找Stage耗时如果读源数据慢看是不是源表小文件太多如果 shuffle 慢看是不是数据倾斜某个 key 的数据量远超其他如果写 HDFS 慢看是不是副本数设太高。数据倾斜的典型表现是某个 reduce 任务卡在 99% 不动。解决办法是在分片列上加盐比如给shop_id拼一个随机后缀构建完再在查询层去掉。这个操作手册里没写但实际很管用。4.3 查询命不中 Cube 的五个原因查询没走 Cube 而是下推到 Hive延迟会从亚秒变成几十秒。常见原因有查询里用了 Cube 没定义的维度聚合函数不匹配过滤条件用了函数包裹列比如where date_format(dt,yyyy)2024查询涉及多张事实表Cube 段还没构建完。排查方法是看查询计划里的CubeHit标记。如果没命中逐条对照上面五个原因。最容易被忽略的是函数包裹列改成where dt between 2024-01-01 and 2024-12-31就能命中。4.4 查询服务的内存调优查询服务的内存主要花在 Cube 段缓存和查询执行上。3.4 里有个kylin.query.cache-threshold参数控制多大的段才进缓存。设太小会导致频繁读 HDFS设太大会把堆撑爆。# kylin.properties 里的查询相关配置 kylin.query.cache-threshold52428800 kylin.query.max-scan-bytes10737418240 kylin.query.timeout-seconds300cache-threshold设 50MB 是折中值小于这个的段直接缓存大于的走流式读max-scan-bytes限制单次查询扫描的数据量防止一个大查询把集群拖垮timeout-seconds设 300 秒超过就杀避免慢查询堆积。5. 避坑与排查Kyligence Enterprise 3.4 落地时最容易翻车的五件事5.1 构建任务报「内存不足」但集群明明有空闲现象是构建任务在 YARN 上被 kill日志显示Container killed by YARN for exceeding memory limits。原因是构建引擎的 executor 内存设得太小而 Cube 的维度组合爆炸导致 shuffle 数据量远超预期。解决办法是先算维度组合数如果超过 100 万就要考虑拆 Cube 或者用聚合组裁剪。我一般会把spark.executor.memory设成spark.executor.memoryOverhead的 4 倍以上给堆外内存留足空间。5.2 查询结果和源表对不上现象是同一个 SQL 在 Hive 里查出来的数和在 Kyligence 里查出来的不一致。原因通常是 Cube 的聚合粒度比查询粒度粗或者 COUNT DISTINCT 用了近似算法。解决方法是先确认查询的维度是否都在 Cube 定义里再看度量列的聚合函数是否和源表一致。如果是 COUNT DISTINCT 的误差要么接受 1% 的偏差要么改成精确算法。5.3 元数据服务启动后连不上数据库现象是元数据服务日志报Communications link failure。原因是数据库连接池配置里的maxActive太小或者数据库的wait_timeout太短导致连接被服务端断开。解决办法是把连接池的maxActive设成查询服务实例数的 2 倍同时在 JDBC URL 里加autoReconnecttrue。更稳妥的做法是配一个连接有效性检测每隔 30 秒发一次select 1。5.4 Cube 段合并后查询变慢现象是原本亚秒的查询在段合并后变成几秒。原因是合并后单个段变大超过了cache-threshold导致每次查询都要从 HDFS 读。解决办法是调大cache-threshold或者把大段再拆回小段。我一般会控制单个段的大小在 20GB 以内超过就按时间再切分。5.5 中文模型名在查询时报乱码现象是模型名或列名含中文时查询报Unknown column或返回乱码。原因是元数据库的字符集不是utf8mb4或者 JDBC 连接没指定字符集。解决办法是建库时就指定utf8mb4并在 JDBC URL 里加characterEncodingutf8。如果已经建库了用ALTER DATABASE改字符集然后重建元数据表。6. 进阶技巧用聚合组和 Rowkey 调优把查询压进亚秒6.1 聚合组怎么切才能既省空间又不漏查询聚合组是 Cube 裁剪的核心手段。原理是把维度按查询频率分组每组独立生成 Cuboid避免全维度组合爆炸。切分原则是高频查询的维度放一组低频的放另一组互斥的维度不要放同一组。我一般会先跑一周的查询日志统计每个维度被用到的次数然后按 80/20 原则切。比如把「日期、地区、品类」放一组覆盖 80% 的查询剩下的「渠道、促销类型」放另一组。这样 Cube 行数能降一个数量级而查询命中率还能保持在 90% 以上。6.2 Rowkey 顺序对查询性能的影响Rowkey 是 Cube 里维度列的排列顺序直接决定查询时能跳过多少数据。原则是把过滤频率最高的维度放前面基数低的放前面因为前缀匹配才能生效。举个例子如果查询经常按「日期 地区」过滤Rowkey 就应该是date, region, category而不是category, date, region。后者会导致日期过滤无法利用前缀扫描数据量翻倍。调整 Rowkey 需要重建 Cube所以设计阶段就要想清楚。6.3 用查询下推兜底 Cube 覆盖不到的 SQL再好的 Cube 设计也不可能覆盖所有查询。3.4 支持把不命中的查询下推到 Hive 或 Spark SQL虽然慢但能保证结果正确。配置下推引擎时注意两点一是下推引擎的队列要和构建引擎隔离二是下推查询的超时要设得比 Cube 查询长因为下推本身就走的是批处理链路。# 配置下推引擎 kylin.query.pushdown.enabledtrue kylin.query.pushdown.runner-class-nameorg.apache.kylin.query.pushdown.SparkPushDownRunner kylin.query.pushdown.timeout-seconds1800timeout-seconds设 1800 秒是给大查询留足时间但别设太大否则慢查询会占满下推队列。我一般会同时配一个告警下推查询占比超过 20% 就说明 Cube 设计需要优化了。6.4 一个验证 Cube 效果的小习惯每次改完 Cube 定义别急着上生产先在测试环境跑一遍基准查询集。我习惯用EXPLAIN看查询计划确认CubeHit为 true再看扫描的段数和行数。如果扫描行数比预期多一个数量级说明 Rowkey 或聚合组有问题。这个习惯帮我省过好几次回滚的麻烦。希望帮到你。本文还有配套的精品资源点击获取