Apache Kylin 5.0 介绍与核心概念

Apache Kylin 5.0 介绍与核心概念：剖析 OLAP 引擎的预计算与 MOLAP/ROLAP 混合架构、元数据与算子模型、Spark/Gluten 查询链路、多角色组件体系与部署形态，全部基于 Ubuntu 22.04 实测环境撰写。

Apache KylinKylinApache数据仓库OLAP2026/10/15

Apache Kylin 5.0 介绍与核心概念

本文基于 Ubuntu 22.04 服务器对 Apache Kylin 5.0.4 官方二进制包与真实部署环境（ZooKeeper 3.5.9、Hadoop 3.2.1 伪集群、Hive 3.1.3、PostgreSQL 14）进行实测后撰写，所有版本信息、目录结构与配置摘录均为真实执行结果。

一、项目概述

1.1 Kylin 是什么

Apache Kylin 是一个开源的分布式分析型数据仓库（Open Source Distributed Analytics Data Warehouse），核心能力是在预计算（Pre-computing）技术之上对超大规模数据集提供亚秒级（Sub-second）的 SQL 多维分析查询。它由 eBay 中国团队于 2014 年开源，2015 年 11 月成为 Apache 顶级项目，是中国团队主导的首批 Apache 顶级项目之一。

与"查询时扫描原始数据"的传统 OLAP 引擎不同，Kylin 的设计哲学是"用空间换时间"：把分析任务中经常使用的维度组合与度量（如 SUM、COUNT、COUNT_DISTINCT）提前在离线阶段算好并物化存储，查询时直接命中预计算结果，避免扫描明细数据。这一思想也被称为 Cube（数据立方体）建模，源自数据仓库领域的 OLAP Cube 概念。

Kylin 5.0 相比 4.x 完成了查询与构建引擎的整体升级：构建与查询全面转向 Spark（内置定制版 Spark 3.3），向量化执行引入 Gluten + ClickHouse Native（libch.so），元数据默认支持 PostgreSQL/MySQL 关系库，部署形态大幅简化（不再依赖 Tomcat 与 HBase）。

1.2 本文实测的版本信息

从官方二进制包 /opt/apache/kylin 下读取的版本标识文件（实测输出）：

$ cd /opt/apache/kylin
$ cat VERSION SPARK_VERSION GLUTEN_VERSION package.timestamp
Apache Kylin 5.0.4
3.3.0-kylin-5.2.2
1.3.0-kylin-250110
2026-07-06

即：Kylin 5.0.4，内置定制 Spark 3.3.0（kylin 5.2.2 线），Gluten 原生向量化组件 1.3.0（2025-01-10 构建），二进制包封装时间 2026-07-06。包内还带 commit_SHA1 标识文件。官方下载页为该包提供 .sha256 校验（实测值 17572bb4413b920096d6ab3e05dfad9501cb2daf7f22e7a9a5dbc2db37f548f6，与下载文件一致）。

1.3 适用场景

Kylin 适合的典型场景：固化的高并发多维报表与聚合查询（如交易大盘、用户行为看板）、百亿级明细上的亚秒级交互式查询、以星型模型为主的数据集市。不合适的场景：高度即席的明细下钻（返回海量行）、Schema 频繁变化的探索式分析、未建模维度的任意组合（需要预计算覆盖的模型先行）。

判断「适不适合用 Kylin」可以归纳为三个特征同时成立：

  • 读多写少：分析数据通常是 T+1 批量产出的，写入节奏以天为单位，而查询以秒为单位高频发生。预计算的构建成本只在整个数据 refreshed 时支付一次，之后被成千上万次查询摊薄，这正是「空间换时间」划算的前提。如果数据频繁实时更新，物化的失效与重建会反过来吞掉收益；
  • 查询模式可枚举：BI 看板与固定报表的维度组合是有限的、可以事先梳理的。Kylin 的智能推荐机制还能从查询历史里持续学习新的维度组合并推荐补充索引，让覆盖面随使用逐步收敛；
  • 星型或雪花建模：事实表外键关联若干维表，度量是数值列上的聚合。Kylin 的模型、索引与查询改写都是围绕这一结构设计的，非星型的图状关联或深度嵌套子查询则超出其舒适区。

反过来，以下信号说明应该换方案：维度基数极高且组合近乎任意（预计算组合数爆炸）、需要返回百万行级明细（物化不划算、明细索引也未必扛得住）、数据需要秒级实时可见（构建流水线的延迟以分钟到小时计）。

二、核心概念

2.1 项目（Project）

Project 是 Kylin 中的顶层组织单元，隔离元数据、模型、索引与权限。所有模型、索引、查询历史都归属某个项目。本文实测环境通过 REST API 与 WebUI 均能按项目维度管理（默认自带的项目在首次启动时初始化）。

2.2 数据源与模型（Model）

数据源（Source）在 Kylin 5 中由 Spark 支撑：模型声明事实表与维表（典型为星型模型），指定 JOIN 关系、维度列与度量列。Kylin 5 支持两种数据接入形态：Hive 表（通过 metastore 元数据）与 JDBC 数据源。实测环境将 kylin.env.apache-hive-conf-dir 指向 Hive 配置目录后，Kylin 即可通过 Hive metastore 发现表结构。

2.3 索引（Index / Cube）

Kylin 5 把预计算结果统称为 Index（历史上叫 Cube）。一个 Index 由维度列集合 + 度量聚合定义，分为：

  • 聚合索引（Aggregation Index / Cube）：预聚合的维度组合与度量，是亚秒级查询的载体；
  • 明细索引（Table Index）：物化指定表的明细列，用于明细查询加速与下钻。

模型创建后，Kylin 的智能推荐（Intelligent Recommendation）会根据查询日志推荐新的索引，也可手工定义。

理解聚合索引的规模，关键是 Cuboid（维度组合） 的概念。一个索引若声明了 N 个维度，理论上的维度组合总数是 2 的 N 次方：N=10 时就有 1024 个组合，每个组合都是一层 Cuboid（全维度组合是顶层，空组合即全局聚合是底层）。逐层全量构建会带来组合数爆炸，因此工程上依赖两条剪枝路径：

  • 聚合组（Aggregation Group）：把业务上经常一起出现的维度圈定在同一组内，组内维度的组合才被构建，跨组组合被剪掉。例如「渠道 + 日期 + 地域」是交易分析组、「商品 + 日期」是商品分析组，二者之间无需交叉组合；
  • 层级维度（Hierarchy）：年、月、日这类天然链条上只构建前缀组合（年、年+月、年+月+日），把指数级压缩为线性级；
  • 强制维度（Mandatory）与联合维度（Joint）：查询中必然出现的维度只构建含它的组合；总是同时出现的维度打包为一个整体参与组合。

存储端还有一层压缩：维度值先经**字典编码（Dictionary Encoding）变成紧凑整数 ID，聚合以 ID 进行，度量值按类型定长或变长编码落盘为 Parquet 列块。普通维度的字典按段局部构建即可；而跨段需要全局一致的度量（典型是 COUNT_DISTINCT 的精确去重）依赖全局字典（Global Dictionary）**保证同一个原始值在所有段中映射到同一 ID。字典是双刃剑：编码后聚合快、存储省，但超基数维度（用户 ID、设备号这类千万级以上基数的列）的字典构建与内存开销会显著上升，需要改用近似算法（如 HyperLogLog）或避免作为维度。

2.4 构建（Build Job）

索引构建是一个 Spark 作业流水线：从数据源抽取数据 → 维度编码（Dictionary/Global Dictionary，保证跨分区去重计数正确）→ 按维度组合聚合 → 生成列式存储文件（Parquet）→ 写入 HDFS 并更新元数据。构建作业由 Kylin 的 Job Engine 以 Spark 客户端模式提交，本文实测构建相关的 Spark 资源参数（executor 内存、核心数、offHeap 大小）均在 kylin.properties 中配置并被启动检查逐项校验。

2.5 查询（Query）与 Sparder

Kylin 5 的查询由常驻 Spark 应用 Sparder 执行：Kylin 服务启动时在 YARN 上拉起一个长驻 Spark 应用，所有 SQL 查询转为该应用内的 Spark 作业执行；命中聚合索引时走预计算结果（MOLAP 路径），未命中时退化为对明细数据（Hive/Parquet）的实时计算（ROLAP 路径）。查询结果通过 REST API（端口 7070）返回给 BI 工具或 WebUI。

Sparder 的常驻身份在文件系统与日志里都有实证：HDFS 工作目录下实测存在 sparder-history 与 spark-history 两个子目录（与 hive-scratch、kylin_metadata 并列），分别承接查询应用与构建作业的历史信息；服务日志 kylin.log 中出现 sql.SparderEnv : Init spark. 行，标记 Sparder 上下文初始化。常驻设计省去了每次查询的 Spark 上下文冷启动开销——冷启动动辄数十秒，而常驻后的单次轻量查询耗时可以压到毫秒到秒级。

查询入口的 REST 响应体本身就是一份执行报告，实测 POST /kylin/api/query 返回的 JSON 包含 40 余个字段，其中信息量最大的几类：

  • 命中情况：realizations（被命中的索引/模型实体）、engineType（执行引擎类型）、pushDown（是否下推数据源执行）、storageCacheType 与 storageCacheUsed（存储缓存形态与用量）；
  • 执行成本：duration（服务端耗时）、cpu_time、dataFetchTime、scanRows/scanBytes 与 totalScanRows/totalScanBytes（实际与估算扫描量）、shufflePartitions；
  • 全链路诊断：query_plan、executed_plan、explain、traces、queryId 与 signature（供缓存与重放），以及 is_timeout、is_refused、failTimes 等限流与失败标记。

把这几个字段纳入日常巡检，可以在不打开 WebUI 的情况下回答「这条查询命中了哪个索引、扫了多少数据、为什么慢」三个最常见的问题。

需要如实记录的一个实测发现：在本环境对样例 Hive 表直接发起聚合查询，服务端返回异常 [GLUTEN Exception] Table SSB.P_LINEORDER is not an internal table.，即 5.0 的 Gluten 向量化查询链路默认只服务 Kylin 内部表（internal table，由 Kylin 托管存储的表形态），对外部 Hive 表的明细下推查询会被该层拦截。这正是 2.2 节所说的「两种数据接入形态」在查询侧的直接体现，也是评估 5.0 数据接入方案时必须提前验证的点（样例场景的预计算索引查询不受此影响）。

2.6 列式存储与 Gluten 向量化

预计算文件以 Parquet 列式存储在 HDFS 的 kylin.env.hdfs-working-dir（默认 /kylin）下。Kylin 5 引入 Gluten + ClickHouse Native 引擎做向量化执行：二进制包 server/ 目录实测包含 libch.so 原生库（GLUTEN_VERSION 1.3.0），spark/ 目录同样部署了一份，用于在 Spark 执行链路中把算子下推到原生引擎。这一层显著提升了大表扫描与聚合的吞吐，但也带来了额外的运行环境约束（如原生库的加载方式，见本系列安装篇排障实录）。

Gluten 的定位值得展开一句：它是把 Spark 部分算子（扫描、过滤、聚合、JOIN 等）替换为原生 C++ 实现的后端框架，ClickHouse Native 是其中一种后端。Kylin 对这套链路的集成方式是把定制版 Spark 与 libch.so 直接打进发行包。实测读取 spark/ 目录的 RELEASE 文件可以确认这份 Spark 的身世：

$ cat /opt/apache/kylin/spark/RELEASE | head -1
Spark 3.3.0-kylin-5.2.2 (git revision cf5c07b2794) built for Hadoop 3.3.2
Build flags: -Phadoop-2.10,hadoop2-aws -Phive -Phive-thriftserver -Pyarn -Pkubernetes,volcano

即 Kylin 官方以自定义编译开关（启用 Hive 支持、YARN 调度、Kubernetes/Volcano 等构建标志）重新构建的 Spark 3.3.0 分支，与上游社区发行版并非同一构件。排查查询引擎问题时，应以这份 RELEASE 与 server/ 下 GLUTEN_VERSION、commit_SHA1 的组合为准，而不是假定它是任何官方 Spark 发行版。

三、体系架构

3.1 组件视图

Kylin 5 的运行时组件及其实测部署位置如下：

  • Kylin Server（单进程 Web 服务，bin/kylin.sh 启动，默认端口 7070）：承载 REST API、WebUI（server/public 静态资源）、元数据服务、Job Engine 与查询路由，基于 Spring Boot（server/newten.jar + server/jars 下数百个依赖 jar，实测 server/jars 共 475 个 jar）；
  • 元数据库：独立关系库，实测使用 PostgreSQL 14（conf/kylin.properties 中 kylin.metadata.url 指向 jdbc:postgresql://…；官方推荐 PostgreSQL 或 MySQL；驱动 jar 实测内置于 server/jars/postgresql-42.4.4.jar）；
  • ZooKeeper：用于分布式锁、服务发现与 Leader 选举（conf/kylin.properties 第 38 行官方注释原文：zookeeper is used for distributed locked, service discovery, leader selection, etc.），实测 kylin.env.zookeeper-connect-string 指向 ZK 3.5.9；
  • Hadoop 集群：HDFS 存储 Parquet 索引文件与 Spark 历史目录（实测 /kylin 与 /kylin/spark-history），YARN 提供 Spark 计算资源；
  • Hive Metastore：表元数据来源（kylin.env.apache-hive-conf-dir 指向配置目录）。

3.2 元数据模型

Kylin 元数据包括项目、模型、索引定义、字典、快照（表数据抽样快照）、执行日志等，5.0 中全部存于关系库（通过 JDBC 访问），并配以 kylin.metadata.url 中的 metadata_name 前缀区分逻辑命名空间。bin/metastore.sh 提供元数据的备份与恢复命令行（backup/fetch/list/restore 等子命令，实测见本系列安装篇）。

实测环境的关系库中共有 30 余张 kylin_metadata_ 前缀的表，按职责分组可以直接读出 Kylin 5 的内部模块划分：

  • 模型与索引：kylin_metadata_model（模型定义）、kylin_metadata_index_plan（索引计划）、kylin_metadata_layout（索引布局，即每个 Cuboid 的物理编排）、kylin_metadata_segment（段/分区信息）、kylin_metadata_cc_model_relation 与 kylin_metadata_compute_column（计算列及其模型关联）；
  • 作业调度：kylin_metadata_job_info_v2、kylin_metadata_job_lock_v2、kylin_metadata_job_stats、kylin_metadata_async_task；
  • 查询侧：kylin_metadata_query_history、kylin_metadata_query_history_offset、kylin_metadata_query_history_realization（查询与命中索引的历史）、kylin_metadata_query_record、kylin_metadata_sql_blacklist、kylin_metadata_favorite_rule（常用查询规则）；
  • 平台能力：kylin_metadata_project、kylin_metadata_acl 与 kylin_metadata_object_acl（访问控制）、kylin_metadata_session_v2（会话）、kylin_metadata_resource_group（资源组）、kylin_metadata_logical_view（逻辑视图）、kylin_metadata_internal_table（内部表）、kylin_metadata_streaming_job 与 kylin_metadata_kafka_config（流式接入）、kylin_metadata_jar_info（扩展 jar 登记）等。

两点工程细节同样值得记录。其一是存储格式：这些表的内容列在 PostgreSQL 中为 bytea 类型，实测读取其二进制前缀为 47 5A 49 50 78 01——前四字节是 ASCII 的 GZIP 标记，其后跟随 zlib 压缩流，即 Kylin 5 把每条元数据序列化后以 zlib 压缩落库，元数据库中看不到明文 JSON，直接查库排障时需要先按该格式解压。其二是备份落点：日常运行会周期性把元数据导出到 HDFS 的 /kylin/kylin_metadata/_backup/ 目录（实测 sample.sh 加载样例时亦产生一份），配合 metastore.sh 的 backup/restore 子命令构成两级恢复手段。

3.3 部署形态

  • 单机部署（本文实测形态）：一台服务器上运行 ZK、Hadoop（伪集群）、元数据库与 Kylin Server，Spark 以 client 模式提交到 YARN；
  • 集群部署：多个 Kylin Server 实例共享元数据库与 ZK（Leader 选举产生查询与构建的主节点），Hadoop/YARN 独立成集群，Server 本身无状态可横向扩展。

3.4 端口清单（官方前提要求）

官方部署文档列出的端口核对清单（本文实测全部用到）：Kylin 7070（HTTP）；HDFS NameNode 8020/DataNode 50010；Hive metastore 9083；ZooKeeper 2181；YARN ResourceManager 8088 与 Spark 作业 4041；PostgreSQL 5432。

3.5 HDFS 工作目录布局（实测）

kylin.env.hdfs-working-dir 指向的 /kylin 在服务跑起来并加载样例后，实测形成五个子目录，各自职责清晰：

$ /opt/apache/hadoop/bin/hdfs dfs -ls /kylin
drwxrwxrwx   - root root          0 2026-10-14 22:06 /kylin/hive-scratch
drwxr-xr-x   - root root          0 2026-10-14 21:59 /kylin/kylin_metadata
drwxr-xr-x   - root root          0 2026-10-14 20:52 /kylin/root
drwxr-xr-x   - root root          0 2026-10-14 22:06 /kylin/sparder-history
drwxr-xr-x   - root root          0 2026-10-14 22:06 /kylin/spark-history
  • hive-scratch：构建过程中 Hive 临时表与中间数据的暂存区；
  • kylin_metadata：元数据备份（_backup）与元数据快照，恢复操作的目标位置；
  • root：以运行用户命名的作业工作空间；
  • spark-history 与 sparder-history：构建 Spark 作业与查询应用 Sparder 各自的事件日志目录。

磁盘容量规划时应把这五类数据的增速分别评估：索引 Parquet 随模型与分区数线性增长，history 目录则随作业频次增长，需要配置清理策略，否则长期运行后占满 HDFS 是最常见的线上事故之一。

四、二进制包结构与启动检查体系

4.1 包内目录（实测）

$ ls /opt/apache/kylin
bin  commit_SHA1  conf  lib  sample_project  samples  sbin
server  spark  tool  VERSION ...
  • bin/：kylin.sh 主控脚本与 get-properties.sh、metastore.sh、admin-tool.sh、sample.sh 等运维命令（30 余个脚本）；
  • conf/：kylin.properties 主配置（发行版默认全部为注释掉的默认值，实测该文件未启用行数为 0），以及 JVM 参数模板 setenv.sh.template（默认 JAVA_VM_XMS=1g、JAVA_VM_XMX=8g，可按环境调小）；
  • sbin/：bootstrap.sh（启动编排）与一整套环境自检脚本（check-1100-os.sh、check-1200-hadoop-conf.sh、check-1300-ports.sh、check-1600-spark-dir.sh、check-1700-spark-kystorage.sh、check-1900-metadata.sh、check-2000-zookeeper-role.sh 等），另有 prepare-hadoop-conf-dir.sh（把 Hadoop/Hive 配置聚合到 kylin/hadoop_conf）、spark-test.sh（真实提交 Spark 作业做可用性验证）、replace-jars-under-spark.sh（对 MapR/FusionInsight 平台替换 Hadoop jar）；
  • server/：服务本体（newten.jar、jars 依赖、public 前端静态资源、libch.so 原生库）；
  • spark/：内置 Spark 3.3.0-kylin-5.2.2 发行（由 sbin/download-spark-user.sh 从官方资源地址下载后解压部署）；
  • samples/：SSB（Star Schema Benchmark）样例数据集目录（实测含 ssb.customer、ssb.lineorder、location、payment_type 等子目录），供 sample.sh 一键加载；
  • tool/：图形化监控与工具资源（grafana、ssb、conf）。

sbin/ 目录的脚本清单完整实测如下，可读性很高——编号前缀就是 bootstrap 的执行顺序：

$ ls /opt/apache/kylin/sbin/
bootstrap.sh
check-1000-kerberos.sh
check-1100-os-commands.sh
check-1200-hadoop-conf.sh
check-1300-hdfs-working-dir.sh
check-1400-java.sh
check-1401-kylin-config.sh
check-1500-ports.sh
check-1501-driver-host.sh
check-1600-spark-dir.sh
check-1601-spark-queue.sh
check-1700-spark-kystorage.sh
check-1800-metadata-access.sh
check-2000-zookeeper-role.sh
check-2200-query-history-access.sh
disabled-check-1900-influxdb.sh
do-check-and-prepare-spark.sh
download-grafana.sh
download-influxdb.sh
download-postgresql.sh
download-spark-user.sh
find-working-dir.sh
guardian-get-fgc-time.sh
guardian-get-process-status.sh
header.sh
init-kerberos.sh
kill-process-tree.sh
load-zookeeper-config.sh
log-rotate-cron.sh
prepare-flat-table.sh
prepare-hadoop-conf-dir.sh
prepare-hadoop-env.sh
replace-jars-under-spark.sh
rotate-logs.sh
setenv.sh
spark-test.sh

从编号即可读出启动检查的完整拓扑：1000 位是环境（kerberos/OS 命令），1200 到 1800 覆盖 Hadoop 配置、HDFS 工作目录、Java、Kylin 配置、端口、driver 主机、Spark 目录与队列、Spark 存储与元数据可达性，2000 检查 ZK 角色，2200 检查查询历史；disabled-check-1900-influxdb 说明旧版的 InfluxDB 监控依赖在 5.0 已转为可选（监控改由 grafana 脚本与 Metrics 配置承担）。此外还有面向运维的独立脚本：rotate-logs.sh（日志轮转）、kill-process-tree.sh（进程树清理）、guardian 系列（进程与 Full GC 观测）、prepare-flat-table.sh（平面表准备）与 replace-jars-under-spark.sh（定制 Hadoop 平台的 jar 替换）。

bin/ 下的运维入口同样成体系，实测共 13 个脚本：kylin.sh（start/stop/restart 主控）、check-env.sh 与 check-env-bypass（环境检查及跳过开关）、metastore.sh、admin-tool.sh（管理员口令重置等）、diag.sh（诊断打包）、get-properties.sh（读取生效配置）、sample.sh、create-table.sh、sql-extract-tool.sh、rollback.sh、upgrade.sh 与 grafana.sh。其中 metastore.sh 的六个子命令实测输出如下，构成元数据运维的完整命令面：

$ bin/metastore.sh
usage: metastore.sh backup METADATA_BACKUP_PATH(the default path is KYLIN_HOME/meta_backups/)
       metastore.sh fetch TARGET_FILE_PATH METADATA_FETCH_PATH(the default path is KYLIN_HOME/meta_fetch/)
       metastore.sh list TARGET_FOLDER_PATH
       metastore.sh restore METADATA_RESTORE_PATH [--after-truncate]
       metastore.sh backup-project PROJECT_NAME METADATA_BACKUP_PATH(the default path is KYLIN_HOME/meta_backups/)
       metastore.sh restore-project PROJECT_NAME METADATA_RESTORE_PATH [--after-truncate]

backup/restore 面向全量元数据，backup-project/restore-project 面向单项目迁移，fetch/list 用于取出与浏览单个元数据路径，--after-truncate 选项处理恢复前是否清空既有命名空间。多环境同步（开发到测试到生产）时，backup-project 加 restore-project 是官方给出的项目级搬运通道。

4.2 启动自检体系

kylin.sh start 的执行顺序为：sbin/bootstrap.sh 先执行环境准备与逐项自检，全部通过后才拉起服务进程。实测检查项清单（bootstrap.sh 与 logs/check-env.out 中真实出现）：

Checking OS Commands           PASS
Checking Hadoop Configuration  PASS
Checking Java Version          PASS
Checking Kylin Config          PASS
Checking Ports                 PASS
Checking Spark Driver Host ... WARN/FAIL 视配置
Checking Spark Dir             PASS
Checking Spark Queue           SKIP
Checking Spark Availability    PASS/FAIL（真实提交 Spark 作业）
Checking Metadata              PASS
Checking Query History         PASS
Checking Zookeeper Role        PASS

其中 Checking Spark Availability 会用当前配置真实提交一个 Spark 作业到 YARN 并读取结果，是所有检查里最严格、最暴露环境问题的一项——本文实测过程中 Hadoop 配置目录、Spark 资源参数、原生库加载三类问题均在该项暴露并被逐一修复（全过程见安装篇）。

4.3 关键配置项（实测验证）

conf/kylin.properties 中必须为部署环境显式设置的条目（本文实测取值）：

kylin.env.apache-hadoop-conf-dir=/opt/apache/hadoop/etc/hadoop
kylin.env.apache-hive-conf-dir=/opt/apache/hive/conf
kylin.env.hdfs-working-dir=/kylin
kylin.env.zookeeper-connect-string=localhost:2181
kylin.metadata.url=kylin_metadata@jdbc,driverClassName=org.postgresql.Driver,url=jdbc:postgresql://localhost:5432/kylin,username=kylin,password=kylin123

另有三类运行期资源参数（默认值面向大型集群，小环境必须调小）：Spark executor 内存/核心数（kylin.storage.columnar.spark-conf.spark.executor.memory 等）、堆外内存（spark.memory.offHeap.size，默认 12g，小集群会因超过 yarn.scheduler.maximum-allocation-mb 被检查拒绝）以及服务 JVM 堆（conf/setenv.sh 的 JAVA_VM_XMS/JAVA_VM_XMX）。

conf/kylin.properties 发行版共 576 行，默认全部为注释状态，但官方用注释把配置项组织成了清晰的章节结构，实测各章节标题依次为：SERVER & WEB（服务形态 kylin.server.mode 取值 all/query/job、服务地址与端口、HTTPS、CORS、服务发现）、JOB EXECUTION（构建引擎与字典、Spark 旧版兼容、动态分区裁剪 DPP 开关）、QUERY SPARK CONTEXT & COLUMNAR STORAGE（以 kylin.storage.columnar.spark-conf 与 env 前缀透传 Spark 参数、Sparder driver 防解码 OOM、优化器耗时与笛卡尔积分区保护）、JOB SCHEDULER（调度线程与优先级）、LDAP/SAML 相关（用户与组的搜索过滤器、IDP 元数据位置）、Metrics（指标暴露）、Circuit Breaker（熔断阈值）、Kerberos、Cache、Diagnosis（诊断）、随后是 model/table/recommend/KG/Tool 等功能开关、Streaming（流式接入）与 gluten & internal table（向量化与内部表）。

阅读这份文件本身就是理解 Kylin 5 能力面的捷径：query/job 两种 server.mode 对应「只跑查询」与「只跑构建」的分工部署；Circuit Breaker 章节的熔断参数配合资源组（元数据库中的 kylin_metadata_resource_group 表）实现查询侧的自我保护；gluten & internal table 章节则印证了 2.5 节实测发现的内部表约束。

五、权限与安全模型

Kylin 支持项目级与行/列级的访问控制：用户经 LDAP/AD、SAML 或内置账户体系认证，角色映射到项目权限；行级权限（Row-level Security）在模型上定义过滤条件实现数据隔离。REST API 使用 Basic 认证，默认管理员账号为 ADMIN。生产部署建议置于反向代理之后启用 HTTPS。

六、与同类引擎的定位对比

  • Kylin vs Hive/SparkSQL：Hive/SparkSQL 每次查询都扫描明细计算，适合灵活探索；Kylin 预先物化聚合，适合高并发固定模式查询，代价是需要建模与构建时间；
  • Kylin vs ClickHouse：ClickHouse 单表极致性能但 SQL 方言与 JOIN 能力有限；Kylin 以标准 SQL + 星型模型见长，5.0 借助 Gluten/ClickHouse Native 融合了后者的向量化执行优势；
  • Kylin vs Druid：Druid 面向事件流与时序摄入，Kylin 面向数据仓库批处理建模场景。

再补两组更常见的选型对照：

  • Kylin vs Doris/StarRocks：Doris 一类 MPP 数据库把「导入即预聚合」与实时更新结合得更好，运维面也更简单；Kylin 的优势在于与 Hadoop 生态（Hive 元数据、YARN 资源、HDFS 存储）的天然衔接，以及在大宽表之上按模型精细控制物化范围的能力。存量 Hadoop 数仓叠加高并发聚合层，Kylin 更顺；新建实时分析平台，MPP 数据库常是更短链路的选择；
  • Kylin vs Impala/Presto（Trino）：Impala/Presto 是交互式查询引擎，无预计算，靠 MPP 并行扫描换速度，适合多表即席 JOIN；Kylin 以 O(1) 级别的物化命中换亚秒响应，两者实际可以共存——Presto 负责探索，Kylin 负责报表。

一句话总结选型逻辑：查询模式越固化、并发越高、数据规模越大，预计算的收益越突出；查询模式越随机、更新越频繁，越应该退回查询时计算引擎。

七、样例模型实测剖析

空谈概念不如解剖一个真实模型。sample.sh 加载的 SSB 样例在元数据库中落成一条模型记录，实测解压其 JSON 内容（zlib 解压后约 10.5KB），关键字段如下：

model_type: BATCH        storage_type: 3
fact_table: SSB.P_LINEORDER
lookups: SSB.CUSTOMER / SSB.PART / SSB.SUPPLIER / SSB.DATES（均为 INNER 连接的维表）
all_named_columns: 59（事实表与维表全部参与建模的列）
all_measures: 1（默认度量 COUNT_ALL：COUNT(constant 1)，返回类型 bigint）
partition_desc: null（未配置分区列）
segment_config: auto_merge_enabled/auto_merge_time_ranges/volatile_range/
                retention_range 均 null，create_empty_segment_enabled=false

这份定义逐项对应 2.x 节的概念：

  • model_type 为 BATCH 表示批处理模型（相对流式模型的 STREAMING），storage_type 标识列式存储方案；
  • 四张 LOOKUP 维表与事实表构成标准星型，JOIN 类型均为 INNER；
  • 59 个命名列是「可被选为维度或度量」的原料池，真正的维度/度量组合由索引定义圈定；
  • 初始只带 COUNT 度量，SUM、COUNT_DISTINCT 等要在设计器里按需添加——模型是骨架，索引才是血肉；
  • segment_config 的四个字段（自动合并时间窗、易变区、保留区、空段启用）是 4.x 以来的分区治理语义：易变区内的新数据不立即合并（降低重算成本），过了易变窗才自动合并成大段；retention_range 决定过期段的自动清理边界。

对初学者最直接的启发是：把样例模型当作「最小合格模型」的参照系——一张事实表、四张维表、一个默认度量，先跑通构建与查询闭环，再逐步加维度、加度量、加分区治理，复杂度是在这个骨架上渐进生长出来的。

八、实测环境摘要

本文所有实测均在以下环境完成（完整部署过程见本系列安装篇）：

  • 操作系统：Ubuntu 22.04（64 位），JDK 8（1.8.0_504）；
  • 依赖组件：ZooKeeper 3.5.9、Hadoop 3.2.1（伪集群，HDFS+YARN）、Hive 3.1.3（metastore 9083）、PostgreSQL 14（元数据库 kylin 库）；
  • Kylin：apache-kylin-5.0.4-bin.tar.gz（676,933,976 字节，sha256 校验通过），解压于 /opt/apache/kylin；
  • 服务 JVM 堆实测调整为 512m（conf/setenv.sh），全栈 Java 进程内存占用可控；
  • 验证：kylin.sh start 全部自检通过后，WebUI 与 REST API 于 7070 端口可访问（详细命令与回显见安装篇与 CLI 篇）。

九、FAQ

Q1：Kylin 5.0 与 4.x 相比最本质的变化是什么？ 引擎栈整体换代：构建与查询从 MapReduce/HBase/Kylin 自研查询服务转向 Spark + Parquet + Sparder 常驻查询应用，元数据从 HBase/文件迁到关系库，再叠加 Gluten 向量化。部署运维面大幅简化，但也带来新的环境约束（原生库加载、内部表形态），本系列安装篇的排障实录大多源于此。

Q2：预计算要占多少额外存储？如何估算？ 取决于维度数、聚合组剪枝后的 Cuboid 数、维度基数与度量类型。粗估方法：各 Cuboid 行数之和乘以每行（编码后维度 ID + 度量）宽度，再乘 Parquet 压缩比（通常 2 到 5 倍）。设计阶段先用小分区数据试构建，读取实际产出的 layout 大小外推全量，是比任何公式都可靠的做法。

Q3：COUNT_DISTINCT 为什么推荐近似算法？ 精确去重依赖全局字典，字典本身要跨段一致，构建成本与维度基数线性相关，超基数场景会成为瓶颈。HyperLogLog 类近似度量以可接受的误差（默认约 1% 量级）换取定长存储与快速合并，绝大多数大盘类指标足够；确需精确的场景再付出全局字典的成本。

Q4：查询没有命中索引会怎样？ 回退为对明细数据的实时计算（ROLAP 路径），可用性不受影响但耗时回到扫描级。通过查询响应里的 realizations 与 pushDown 字段可以立即识别未命中；持续观察查询历史，让智能推荐把高频未命中模式变成新索引，是 Kylin 使用方法论的核心循环。

Q5：内部表与外部表（Hive 表）在 5.0 里如何选择？ 本文实测对样例 Hive 表的明细下推查询被 Gluten 层以 Table SSB.P_LINEORDER is not an internal table 拦截，说明向量化查询链路面向 Kylin 内部表设计。以 Hive 为主的存量数仓可以继续用 Hive 表构建预计算索引（索引查询不受影响），但涉及明细下推与内部表能力时要提前验证，必要时把热表迁移为 Kylin 托管的内部表。

Q6：ZooKeeper 在 Kylin 5 里承担什么职责？能去掉吗？ 官方注释原文明确其用于分布式锁、服务发现与 Leader 选举。单机部署也需要一个 ZK 实例（本文实测即单点 ZK），因此不能省略；多实例部署时它更是选主与互斥的唯一协调者。

Q7：Kylin 服务本身是有状态的吗？能否直接横向扩容？ Server 的状态全部外置：元数据在关系库、数据在 HDFS、协调在 ZK，进程本身近似无状态。因此扩容即「多起一个实例接在负载均衡后面」，注意 server.mode 拆分（query 与 job 分离）可以让构建作业与查询负载互不抢占。

Q8：构建作业失败后重跑会重复构建吗？ 构建作业以段（Segment）为单位并有作业状态机管理，失败的作业重试会从断点或重新执行该段的构建，幂等性由「同一段不会有两个成功产物」的元数据约束保证。治理大量历史分区时，配合 auto_merge 与 retention 配置可减少手工介入。

Q9：为什么本文反复强调「以真实回显为准」？ Kylin 5 的组件组合（定制 Spark、Gluten 原生库、关系库元数据）相互耦合，任何一项版本或配置偏差都可能改变行为。本文的版本号、目录结构、接口字段与异常信息均取自实际运行输出，读者复现时应以同版本实测对照，而非记忆或旧版文档。