Files
0pt/src/analytics/contract/compile-semantic.ts
T
Claude Opus 5 b1884a89a5
CI (SIAX Cloud) / security (push) Successful in 25s
Security Scan (SIAX Cloud) / security (push) Successful in 24s
CI (SIAX Cloud) / integration (push) Successful in 39s
CI (SIAX Cloud) / security (pull_request) Successful in 25s
CI (SIAX Cloud) / quality (push) Successful in 57s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 20s
CI (SIAX Cloud) / integration (pull_request) Successful in 1m38s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m59s
feat(analytics): BI-P016 — canonical query request contract, two compile targets
The eight-field AnalyticsQueryRequest BI-P016 names, verbatim, with the rule
that makes it safe enforced structurally rather than by convention: there is
no field that can carry SQL, and parseAnalyticsQueryRequest REJECTS unknown
keys instead of ignoring them. Ignoring an unsupported field is how it becomes
a supported one after the next refactor.

`tenant`, `tenant_id`, `project_id`, `database`, `catalog` and `table` are
rejected by name. INF0's Wave-2 cross-tenant hole was a tenant read out of a
request body; the fix that sticks is a request type in which the field does
not exist, and a parser that refuses it when a caller sends it anyway.

BI-P016's DoD ("same request compiles to ClickHouse/semantic engine without
consumer rewrite") is tested as an equality, not narrated: both targets are
projected onto a comparable shape and compared. The ClickHouse side of that
projection is obtained by PARSING the emitted SQL and its bound parameters in
the test — not by reading a field the compiler helpfully returned — so a
compiler that silently drops a filter fails the comparison instead of passing
it. The parser throws on any condition it does not recognise, which is what
would catch unbound caller text appearing in the statement.

BI-P011's forced tenant predicate is re-proven against this new path: five
request shapes are enumerated and each must have FORCED_TENANT_PREDICATE as
condition[0]; a blank tenant refuses to compile rather than emitting no
predicate; a hostile filter value appears only in params, never in sql.

45 tests, all failing-capable: every rejection assertion checks the SiaxError
code, and the DoD assertions compare reconstructed meaning rather than strings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 02:00:07 +02:00

146 lines
5.0 KiB
TypeScript

/**
* src/analytics/contract/compile-semantic.ts
* ===========================================
* BI-P016, compile target 2 of 2 — and the thing that makes BI-P016's DoD
* ("same request can compile to ClickHouse/semantic engine without consumer
* rewrite") a testable claim rather than a design intention.
*
* A `SemanticQuerySpec` is the engine-neutral form a semantic layer consumes.
* It is deliberately shaped like MetricFlow's query interface (metrics /
* group-by / where / order / limit / time-constraint) so BI-P029's
* `MetricFlowProvider` can execute it without an adapter, but it names
* nothing MetricFlow-specific: swapping MetricFlow for Cube or a hand-rolled
* compiler changes this file's CONSUMER, not this file, and never the
* product API.
*
* The `where` clauses here are STRUCTURED, not SQL strings. A semantic layer
* that accepts SQL predicate text (MetricFlow's `--where` does) would put a
* raw-SQL hole behind the closed DSL — so the spec carries operator+values
* and the provider renders them itself under its own escaping rules.
*/
import type { FilterOperator, ResolvedQuery, TimeGrain } from './query-request';
export interface SemanticMetricRef {
/** Canonical SIAX metric id — stable across semantic-engine replacement. */
metric_id: string;
name: string;
}
export interface SemanticGroupBy {
dimension_id: string;
name: string;
/** Set when this group-by is a time bucket rather than a categorical one. */
grain?: TimeGrain;
}
export interface SemanticWhere {
dimension_id: string;
name: string;
operator: FilterOperator;
values: string[];
}
export interface SemanticOrderBy {
ref: string;
direction: 'asc' | 'desc';
}
export interface SemanticTimeConstraint {
/** Inclusive lower bound. */
start?: string;
/** EXCLUSIVE upper bound — matched to the ClickHouse target exactly. */
end?: string;
dimension?: string;
}
export interface SemanticQuerySpec {
dataset_id: string;
semantic_model_version?: number;
metrics: SemanticMetricRef[];
groupBy: SemanticGroupBy[];
where: SemanticWhere[];
orderBy: SemanticOrderBy[];
limit: number;
timeConstraint?: SemanticTimeConstraint;
format: 'json' | 'arrow_ipc';
}
export function compileRequestToSemantic(resolved: ResolvedQuery): SemanticQuerySpec {
const groupBy: SemanticGroupBy[] = resolved.dimensions.map((d) => ({
dimension_id: d.dimension_id,
name: d.name,
}));
const grain = resolved.request.timeRange?.grain;
if (grain) {
groupBy.push({
dimension_id: resolved.request.timeRange?.dimension ?? '__time',
name: resolved.request.timeRange?.dimension ?? '__time',
grain,
});
}
return {
dataset_id: resolved.dataset_id,
semantic_model_version: resolved.semantic_model_version,
metrics: resolved.metrics.map((m) => ({ metric_id: m.metric_id, name: m.name })),
groupBy,
where: resolved.filters.map((f) => ({
dimension_id: f.dimension.dimension_id,
name: f.dimension.name,
operator: f.filter.operator,
values: f.filter.values ?? [],
})),
orderBy: (resolved.request.orderBy ?? []).map((o) => ({ ref: o.ref, direction: o.direction })),
limit: resolved.request.limit ?? 1000,
timeConstraint:
resolved.request.timeRange && (resolved.request.timeRange.from || resolved.request.timeRange.to)
? {
start: resolved.request.timeRange.from,
end: resolved.request.timeRange.to,
dimension: resolved.request.timeRange.dimension,
}
: undefined,
format: resolved.request.format ?? 'json',
};
}
/**
* The comparable SHAPE of a compiled query, target-independent.
*
* BI-P016's DoD is about semantic equivalence, and the honest way to test
* that is to project both targets onto the same tuple and demand equality —
* not to eyeball two strings. `tests/analytics/query-request-contract.test.ts`
* builds this from the ClickHouse SQL by PARSING the compiled artefact, so a
* compiler that quietly drops a filter fails the comparison.
*/
export interface QueryShape {
dataset_id: string;
metrics: string[];
dimensions: string[];
filters: Array<{ dimension: string; operator: FilterOperator; values: string[] }>;
order: string[];
limit: number;
timeFrom?: string;
timeTo?: string;
grain?: TimeGrain;
}
export function shapeOfSemanticSpec(spec: SemanticQuerySpec): QueryShape {
const timeBucket = spec.groupBy.find((g) => g.grain);
return {
dataset_id: spec.dataset_id,
metrics: spec.metrics.map((m) => m.name).sort(),
dimensions: spec.groupBy
.filter((g) => !g.grain)
.map((g) => g.name)
.sort(),
filters: spec.where
.map((w) => ({ dimension: w.name, operator: w.operator, values: [...w.values] }))
.sort((a, b) => (a.dimension + a.operator).localeCompare(b.dimension + b.operator)),
order: spec.orderBy.map((o) => `${o.ref}:${o.direction}`),
limit: spec.limit,
timeFrom: spec.timeConstraint?.start,
timeTo: spec.timeConstraint?.end,
grain: timeBucket?.grain,
};
}