Article body
Full article
Abstract: When enterprises involve AI in data Q&A, metric exploration, and report creation, they need a reusable analytical expression that connects business concepts in natural language to explicit calculation logic. HENGSHI HQL (Hengshi Query Language) handles metric definitions, aggregate calculations, and analytical expressions; the metric semantic layer manages business definitions; Data Agents organize the analytical process; and the tool layer carries out concrete operations. Using formulas, HE structures, and a collaboration diagram, this article explains how these capabilities form a verifiable AI analytics chain.
1. Where HQL Fits in the Analytics Chain
The value of HQL lies in expressing fields, aggregations, calculations, dimensions, and filters in business analysis as reusable formulas. It can appear in metric definitions, chart analysis, and expressions required by APIs, and can be carried by structured nodes such as HE (Hengshi Expression). This makes it possible to relatively decouple where data is stored and computed from the logic of business metrics: the same definition of “sales amount” or “completed-order amount” can be reused by dashboards, reports, ChatBI, and subsequent analytical processes.
Around the same analytical objective, each layer must have a clear division of responsibilities: HQL expresses calculations; the metric semantic layer maintains definitions; an Agent or workflow organizes steps; and scheduling and runtime systems manage execution cycles, retries, and resources. Conditional calculations can be written into formulas, while task branches, checkpoints, and failure recovery should be handled by the corresponding runtime mechanisms. This makes it possible to validate separately whether a formula is correct, whether the right metric was selected, and whether a task executed successfully, reducing the cost of error diagnosis and later maintenance.
Figure 1: Where HQL is responsible in an analytical task (a capability-division illustration, not an internal service topology)
| Layer | Primary objects | Role in the HENGSHI analytics chain |
|---|---|---|
| HQL / HE | Fields, aggregations, dimensions, filters, and calculation formulas | Expresses analytical definitions as semantic objects that can be saved, reused, and validated |
| Metric semantic layer | Business metrics, subject areas, dimensions, and definition notes | Ensures that different dashboards, reports, and data-Q&A entry points use the same interpretation of the same business concept |
| Data Agent / ChatBI | Intent, context, metric selection, explanation, and asset recommendations | Converts natural-language questions into semantic-layer-constrained analytical actions and presents the results to users |
| HENGSHI CLI and runtime plane | Data, queries, dashboards, permissions, and engineering actions | Provides executable, reviewable BI engineering interfaces for Agents capable of tool invocation |
HENGSHI’s metric-management page summarizes this idea as “define once, use everywhere, and unify definitions,” and explicitly notes that HQL can decouple data storage and computation from metric logic. Here, “decoupling” does not mean separating business definitions from the data model; it means business formulas do not have to be scattered across every chart, report, or temporary Q&A prompt.
2. Metrics Before Answers: Use HQL to Capture Reusable Definitions
2.1 From a One-Time Query to a Durable Metric Definition
Ad hoc queries are useful for rapid exploration, but they cannot inherently ensure consistency across teams. If sales, finance, and operations each write “sales amount” in their own charts, they may reach different conclusions even when using the same name, because they use different status filters, return treatments, or time fields. A more reliable approach is to manage the definitions separately: a metric formula defines “how to calculate it”; dimensions define “from which perspective to view it”; filters define “within what scope it holds”; and names, descriptions, subject areas, and owners help users understand it.
The following examples show only the syntax for HQL aggregations and dimensions. All field names are demonstration fields and do not correspond to customer data or preconfigured models. Production definitions should also be validated against the actual data set, field types, time definitions, and permission scope.
sum({amount})
sum(case when {order_status} = 'completed' then {amount} else 0 end)
group({region})The first line can serve as the aggregation basis for an amount metric; the second expresses the conditional definition “count completed orders only”; and the third treats region as a grouping dimension. These expressions do not by themselves constitute a business report. A truly reusable metric also needs a name, applicable data set, default filters, precision, and a business explanation. Formulas involving cross-data-set logic, window calculations, or complex filtering should be reviewed jointly by data and business owners, rather than generated once from natural language and published directly.
2.2 HE Allows Expressions to Be Passed in Structured Form
HQL can be represented structurally by HE nodes. The point of a structured representation is not to replace a person reading the formula; it is to enable charts, interfaces, and tool invocations to pass the same computational intent with an explicit type, data set, and expression. The following JSON only illustrates the form of a formula node; the data set identifier and fields are demonstration values:
{
"kind": "formula",
"op": "sum({{1}}.{amount})"
}In this example, formula indicates that the node carries a formula, while op stores the expression text; {{1}}.{amount} is a data-set-qualified field reference used to reduce ambiguity. Actual interfaces may also use node types such as field, function, constant, reference, and param, with the caller supplying the required context. In development, rely on the HQL reference documentation and the API contract for the current version rather than constructing JSON from memory.
3. NL2Metrics: Ground Natural Language in Defined Business Concepts First
The key to enterprise natural-language analytics is not “translating a sentence into a query,” but determining first which business concept that sentence refers to. When a user asks, “How does this month’s completed-order amount in East China compare with last month?”, the system must identify metric candidates, the time range, the regional dimension, and the comparison method in sequence. “Completed-order amount” should preferentially resolve to a governed metric that already exists, rather than a plausible-looking formula generated on the fly that may alter the definition.
HENGSHI’s AI analytics-agent page describes this architecture as centered on NL2Metrics and the modeling semantic layer. The Data Agent product manual also states that it can decompose intent and perform multiple queries, retrieving information within the user’s permissions in combination with context such as the current page and user attributes. This means the natural-language entry point can better align with the business, but must still be constrained by permissions, semantic assets, and context.
A more reliable chain can be written as: business question → metric and dimension resolution → HQL / HE expression → permission-constrained data query → result explanation and follow-up questions. In this chain, the model is responsible for understanding, candidate selection, and explanation; the metric semantic layer defines the boundaries of available concepts; and HQL defines how calculations are expressed. This also explains why business rules, synonyms, and predefined metrics in knowledge management matter: they provide enterprise context for the model to reference instead of delegating every judgment to a single generation.
One realistic expectation must be maintained: generative models do not guarantee exactly the same text or reasoning path for the same input every time. For critical operating definitions, the result should display or be traceable to the metric definition, filtering scope, and data timestamp. For asset actions such as creating metrics or dashboards, review and publication boundaries should be established rather than replacing governance with a single conversation.
4. Data Agent and CLI: Separate “Understanding Analytics” from “Executing Engineering Work”
Data Agent is suited to analytical collaboration: understanding questions, invoking governed metrics and data context, assisting with modeling or report creation, explaining anomalies, and organizing further exploration. It should not bypass the semantic layer by turning every request directly into an unconstrained query, nor should it expand data permissions on its own. For actions that must be implemented as BI engineering work—such as reading data-set information, running queries, generating dashboards, or handling permission-related operations—HENGSHI CLI provides an Agent-oriented command-line execution plane, with engineering mechanisms including structured output, skills, dry runs, and SSE echoing.
| Question | Preferred layer | Controls to retain |
|---|---|---|
| “How is this metric calculated, and can it be viewed by region?” | Metric semantic layer and HQL | The metric description, formula, dimensions, and default filters must be traceable |
| “What does this report show, and what should we investigate next?” | Data Agent / ChatBI | The user’s permissions, current context, referenced metrics, and data scope |
| “Generate analytical assets from a reviewed plan” | CLI and engineering workflow | Command-help validation, dry runs, change review, and result echoing |
| “When should it run daily, and how should it retry after failure?” | Scheduling and runtime system | Scheduling policy, alerting, retries, and resource governance belong to the runtime plane |
This division does not add layers; it limits the spread of errors. Data Agent first proposes or validates analytical intent; HQL turns reusable calculations into expressions; CLI performs explicit engineering actions when needed; and the scheduling system handles tasks that run over time. Specific commands, parameters, and available resources vary by version and deployment. Automation scripts should read the current CLI help and team runbook before performing any action that changes assets or permissions.
5. Implementation Approach: Put Verifiability Before Automation
First, inventory high-frequency and highly disputed operating metrics, and prioritize capturing their formulas, dimensions, data sets, and business descriptions; do not attempt to cover every metric at once. Second, establish synonyms, business rules, and example questions for natural-language queries so that related but distinct concepts such as “transaction value,” “sales amount,” and “GMV” can be distinguished correctly. Third, validate HQL and HE for syntax, fields, and permissions before querying or generating charts. Fourth, return data scope, definition version, and result explanation together so business users can judge whether the answer addresses the original question. Fifth, use independent engineering controls for changes such as creation, authorization, publication, and scheduled execution, so task controls and analytical formulas can each be inspected separately.
In the Data Agent era, HQL provides a stable anchor for analytical expression: it makes metric definitions reusable while allowing natural-language and tool invocations to land on verifiable computational semantics. Only by distinguishing the responsibilities of HQL, the semantic layer, NL2Metrics, Data Agent, and CLI can enterprises improve analytical efficiency while preserving definition consistency, permission boundaries, and engineering maintainability.