简介：这份《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:MaxGCPauseMillis=200 \ -XX:InitiatingHeapOccupancyPercent=45"这里-Xms和-Xmx设成一样是为了避免堆动态伸缩带来的停顿；G1 的MaxGCPauseMillis设 200ms 是经验值，再低会导致 GC 线程抢 CPU 反而拖慢查询；InitiatingHeapOccupancyPercent=45比默认的 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_FORMAT=DYNAMIC，别等出错了再改。
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-threshold=52428800 kylin.query.max-scan-bytes=10737418240 kylin.query.timeout-seconds=300cache-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 里加autoReconnect=true。更稳妥的做法是配一个连接有效性检测，每隔 30 秒发一次select 1。
5.4 Cube 段合并后查询变慢
现象是原本亚秒的查询在段合并后变成几秒。原因是合并后单个段变大，超过了cache-threshold，导致每次查询都要从 HDFS 读。解决办法是调大cache-threshold，或者把大段再拆回小段。我一般会控制单个段的大小在 20GB 以内，超过就按时间再切分。
5.5 中文模型名在查询时报乱码
现象是模型名或列名含中文时，查询报Unknown column或返回乱码。原因是元数据库的字符集不是utf8mb4，或者 JDBC 连接没指定字符集。解决办法是建库时就指定utf8mb4，并在 JDBC URL 里加characterEncoding=utf8。如果已经建库了，用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.enabled=true kylin.query.pushdown.runner-class-name=org.apache.kylin.query.pushdown.SparkPushDownRunner kylin.query.pushdown.timeout-seconds=1800timeout-seconds设 1800 秒是给大查询留足时间，但别设太大，否则慢查询会占满下推队列。我一般会同时配一个告警，下推查询占比超过 20% 就说明 Cube 设计需要优化了。
6.4 一个验证 Cube 效果的小习惯
每次改完 Cube 定义，别急着上生产，先在测试环境跑一遍基准查询集。我习惯用EXPLAIN看查询计划，确认CubeHit为 true，再看扫描的段数和行数。如果扫描行数比预期多一个数量级，说明 Rowkey 或聚合组有问题。这个习惯帮我省过好几次回滚的麻烦。
希望帮到你。
本文还有配套的精品资源，点击获取
