引言在BI领域有一个长期被忽视但至关重要的技术问题指标的计算逻辑应该用什么语言来定义SQL太底层——SQL直接操作数据库表和字段业务人员无法理解且每次口径变更都需要逐个报表修改SQL脚本。Excel公式太轻量——无法处理多维度交叉聚合、时间序列计算、复杂条件分支。自然语言太模糊——同比增长率这种描述无法精确到计算逻辑的每个细节。衡石科技自研了HQLHengshi Query Language——一种面向业务指标的声明式定义语言。HQL的设计目标是在业务可理解和计算精确性之间找到平衡点让指标的计算逻辑既能被业务人员读懂又能被引擎精确执行。这不是一个简单的技术选择而是企业级BI数据建模的基础设施设计。本文将从设计原理、语法体系、工程实践、与SQL的关系四个维度深度解析HQL指标定义语言的技术内涵。一、HQL的设计哲学1.1 三大设计原则原则一业务优先HQL使用业务术语而非数据库字段名。一个HQL表达式中的sales_amount代表的是业务概念销售额而非数据库中的t_order.total_price字段。这一设计使得指标定义可以被业务人员直接理解而不需要理解底层数据表结构。业务优先原则的深层含义是指标的定义应该脱离物理数据层的实现细节在语义层面描述计算什么而非怎么计算。当底层的数据表结构变更时如字段重命名、表拆分合并HQL定义不需要修改——只需要更新数据集的字段映射。原则二声明式定义HQL采用声明式而非命令式的定义方式。用户声明我想要什么如SUM(order_net_price)HQL引擎负责将其转化为怎么做的执行计划如对应的SQL查询语句、聚合路径、Join策略。声明式定义的核心优势是关注点分离——指标的定义者关注业务逻辑执行优化的复杂度由引擎处理。当数据引擎的性能优化策略变化时如从全表扫描优化为索引扫描HQL定义不需要修改。原则三维度无关HQL的指标定义不绑定特定维度组合。一个原子指标SUM(order_net_price)的定义中不包含任何维度过滤条件——它定义的是销售额的计算逻辑而非华东区的销售额或月度销售额。维度无关原则的核心价值是最大复用性——一个原子指标可以被无数个业务指标引用每个业务指标绑定不同的维度组合。当新增一个分析维度时只需要创建新的业务指标引用现有原子指标不需要修改原子指标的定义。1.2 HQL与传统指标定义方式的对比维度SQL片段Excel公式HQL表达对象数据库表和字段Excel单元格引用业务指标和维度使用角色数据工程师业务人员业务分析师/业务运营专家维度处理WHERE条件硬编码手动筛选维度参数化、动态组合计算口径每次查询手动定义每个表格手动定义一次定义、全局复用可维护性散落在各报表中散落在各Excel中集中管理、版本控制多引擎适配需要为每种引擎编写不同SQLN/A方言适配器自动转换二、HQL的语法体系2.1 基础表达式HQL的基础表达式由数据集字段和聚合函数组成简单聚合// 销售额订单净价的求和 measure sales_amount SUM(order_net_price) // 订单量订单ID的计数 measure order_count COUNT(order_id) // 客单价销售额除以订单量 measure avg_order_value sales_amount / order_count简单聚合表达式是HQL最基础的形态——定义在单一数据集上的聚合计算结果随用户选择的维度动态变化。条件聚合// 退款订单量满足退款条件的订单计数 measure refund_order_count COUNT_IF(order_status refunded, order_id) // 高价值客户数累计消费超过10万的客户计数 measure high_value_customer_count COUNT_IF(SUM(order_amount) 100000, customer_id)条件聚合通过IF和COUNT_IF等条件函数实现——根据业务条件动态筛选聚合范围。2.2 时间序列表达式时间序列计算是BI分析的核心需求HQL提供了丰富的时序函数同比与环比// 同比增长率本期销售额相对去年同期销售额的增长率 metric yoy_growth (sales_amount - lag(sales_amount, 12)) / lag(sales_amount, 12) // 环比增长率本期销售额相对上期销售额的增长率 metric mom_growth (sales_amount - lag(sales_amount, 1)) / lag(sales_amount, 1)lag函数用于获取历史时间点的指标值——lag(sales_amount, 12)表示12个周期前的销售额值。lag函数的周期由指标的粒度声明决定如果粒度是月度则lag(x, 12)表示12个月前如果粒度是日度则表示12天前。累计与移动平均// 年度累计销售额 metric ytd_sales running_sum(sales_amount) // 7日移动平均销售额 metric ma7_sales avg(sales_amount, 7)running_sum实现从周期开始到当前的累计计算avg函数配合窗口参数实现移动平均。时间偏移// 上月销售额 measure last_month_sales offset(sales_amount, -1, month) // 去年同期销售额 measure last_year_same_period offset(sales_amount, -12, month)offset函数用于获取相对于当前时间点的历史或未来值——正数表示未来负数表示历史。2.3 复合表达式HQL支持将多个指标组合为更复杂的计算逻辑比率指标// 毛利率 measure gross_margin gross_profit / sales_amount // 库存周转率 measure inventory_turnover cost_of_goods_sold / avg(inventory_value)比率指标通过两个指标的除法实现——分子和分母各自独立聚合最后计算比率。这一设计确保了即使分子和分母的维度组合不同比率的计算结果仍然正确如华东区毛利率中毛利润和销售额都按华东区维度聚合后再相除。排名表达式// 区域销售额排名 measure region_sales_rank rank() over(partition by region order by sales_amount desc) // 品类销售额占比 measure category_sales_pct sales_amount / sum(sales_amount) over(partition by category)排名表达式通过窗口函数实现——rank()计算排名sum() over(partition by)计算分组内占比。窗口函数的引入使得HQL可以表达排名、占比、累计占比等常见业务分析需求。2.4 粒度声明HQL的粒度声明是指标管理精确化的重要工具——它定义了指标计算的聚合层次// 华东区月度销售额——粒度按区域、按月 metric east_monthly_sales sales_amount[region华东] [granularityregion,month] // 全国日度GMV——粒度按日 metric national_daily_gmv sales_amount[granularityday]粒度声明的核心价值是避免聚合冲突——当同一仪表盘中同时展示按门店按日和按区域按月的销售额时粒度声明确保两个指标各自使用正确的聚合路径不会产生计算冲突。2.5 自定义函数对于行业特有的计算需求HQL支持用户注册自定义函数// 零售行业的坪效指标——单位面积销售额 measure sales_per_sqm sales_amount / store_area // store_area是自定义函数返回的门店面积 // 金融行业的夏普比率——风险调整后收益 measure sharpe_ratio (return_rate - risk_free_rate) / stddev(return_rate, 252)自定义函数的注册通过HQL的扩展机制实现——数据团队编写自定义函数的计算逻辑通常为Python或Java注册到HQL引擎后即可在HQL表达式中使用。自定义函数的使用方式与内置函数完全一致业务人员无需关心底层实现。三、HQL引擎的执行机制3.1 从HQL到SQL的转化流程HQL引擎在运行时将HQL表达式转化为对应数据引擎的SQL查询。这一转化流程分为四个步骤Step 1表达式解析HQL引擎解析表达式构建抽象语法树AST。AST中包含了指标引用、函数调用、维度条件、粒度声明等所有语义信息。Step 2语义验证引擎验证表达式的语义正确性指标引用是否指向已定义的指标函数调用的参数类型是否匹配维度条件是否在数据集中存在粒度声明是否与指标的维度兼容语义验证未通过时引擎返回明确的错误信息如指标sales_amount未定义或维度region在数据集中不存在帮助数据团队快速定位问题。Step 3查询计划生成引擎根据AST和当前查询的维度上下文生成查询执行计划确定需要Join的数据集和Join条件确定聚合层次和分组字段确定过滤条件的注入位置选择执行优化策略如预计算命中、索引使用Step 4SQL生成与方言适配引擎将查询计划转化为目标数据引擎的SQL语句通过方言适配器处理引擎间的语法差异。3.2 动态聚合的执行逻辑HQL引擎的核心能力是动态聚合——同一指标在不同维度组合下的聚合计算场景用户查询按区域查看销售额引擎解析维度上下文维度region引擎查询指标的HQL定义measure sales_amount SUM(order_net_price)引擎生成聚合SQLSELECT region, SUM(order_net_price) FROM orders GROUP BY region方言适配器将SQL转换为目标引擎的语法数据引擎执行SQL返回各区域的销售额场景用户下钻至按区域、按门店查看销售额引擎解析新的维度上下文维度region, store引擎查询同一指标的HQL定义定义未变引擎生成新的聚合SQLSELECT region, store, SUM(order_net_price) FROM orders GROUP BY region, store方言适配和执行如前整个过程的核心是HQL定义不变维度组合在查询时动态决定。这就是维度无关原则在执行层面的体现——指标的定义与维度解耦维度组合由用户的查询行为动态确定。四、HQL的工程实践4.1 指标定义的命名规范良好的命名规范是HQL工程实践的基础原子指标命名采用业务概念_度量类型的命名模式sales_amount销售额_金额order_count订单_数量customer_count客户_数量avg_order_value平均_订单_价值业务指标命名采用维度条件_指标_粒度的命名模式east_monthly_sales华东_月度_销售额national_daily_gmv全国_日度_GMVtop10_store_salesTOP10_门店_销售额语义标注规范每个指标的语义标注应包含标准名称正式的业务术语别名列表常见的同义词和缩写业务描述1-2句话说明指标的业务含义使用场景标注该指标常用于哪些分析场景4.2 指标复用与组合模式HQL的指标复用模式是工程效率的关键基础指标层定义最底层的原子指标——通常10-20个核心指标覆盖企业的主要业务度量。这些指标是所有业务指标的基础定义质量要求最高。派生指标层基于基础指标的简单变换——如同比、环比、累计、移动平均。派生指标引用基础指标不直接操作数据集字段。组合指标层基于多个指标的复杂计算——如毛利率、库存周转率、夏普比率。组合指标引用基础指标和派生指标形成指标的层级结构。这种三层结构的核心价值是变更传播——当基础指标的口径变更时所有引用它的派生指标和组合指标自动更新不需要逐个修改。4.3 指标定义的质量管理口径一致性检查当新指标的定义与已有指标存在口径重叠时系统自动检测并提示。如新定义net_sales SUM(order_net_price)时如果已有gross_sales SUM(order_gross_price)系统提示两个指标的命名相似但计算口径不同建议在语义标注中明确区分。维度覆盖度检查系统检查每个指标的维度覆盖度——该指标在哪些维度上的聚合是有效的哪些维度上的聚合可能产生误导。如库存周转率按门店维度聚合是有效的但按客户维度聚合可能没有业务意义。性能影响评估对于复杂指标特别是多层嵌套的窗口函数和自定义函数系统评估其查询性能影响。如果某指标的典型查询响应时间超过阈值系统建议优化——如增加预计算、简化表达式、拆分为多个简单指标。五、HQL与Agentic BI的协同5.1 HQL是Text2Metrics的技术基石Text2Metrics架构的核心是将自然语言映射至指标语义层——而指标语义层的内容就是HQL定义的指标。HQL的定义质量直接决定了Text2Metrics的推理准确率口径精确性HQL表达式的计算逻辑必须精确无误——一个错误的HQL定义会导致所有引用它的ChatBI查询返回错误结果维度完整性HQL定义中的维度覆盖度决定了ChatBI可以支持哪些维度组合的查询——缺失的维度组合无法通过ChatBI查询语义标注质量HQL指标附带的语义标注别名、描述、使用场景决定了ChatBI语义匹配的准确率5.2 HQL支持ChatBI的下钻推理ChatBI Agent在下钻推理时需要理解维度的层级关系——而维度层级关系在HQL的粒度声明和维度定义中// 维度层级定义 dimension store_hierarchy { level1: store, // 门店 level2: city, // 城市 level3: region, // 区域 level4: country // 全国 }当用户查询华东区销售额后追问哪个门店最高时Agent通过维度层级定义理解华东区→门店是有效的下钻路径自动生成按门店维度下钻的查询。六、HQL的演进方向6.1 AI辅助HQL生成随着大模型能力的增强HQL的生成方式正在从人工编写向AI辅助演进自然语言转HQL业务人员用自然语言描述指标需求如华东区月度销售额同比增长率AI自动生成HQL表达式经人工审核后发布指标建议AI基于数据集的字段和已有指标自动推荐可能需要的新指标定义口径检测AI自动检测新指标与已有指标之间是否存在口径冲突6.2 HQL的跨引擎一致性保障随着企业使用多种数据引擎的趋势增强HQL的跨引擎一致性变得尤为重要。衡石正在持续扩展方言适配器的覆盖范围确保同一HQL定义在不同引擎上的计算结果完全一致——这包括数据类型转换、空值处理、舍入规则等细节层面的对齐。结语HQL不是一个又一个查询语言——它是企业级BI数据建模的基础设施。它的核心价值不在于语法有多强大而在于让指标的定义从分散走向集中、从一次性走向可复用、从IT专属走向业务可理解。当企业从每个报表手动写SQL进化为语义层集中定义HQL从口径变更逐报表修改进化为修改原子指标、自动传播从ChatBI回答不确定进化为基于HQL语义层的精确推理——数据建模就真正从技术工作进化为业务资产。好的指标定义语言不是让数据工程师更方便的工具而是让业务人员可以理解和参与的数据资产建设基础设施。这正是HQL设计的终极目标。