@gscdump/engine 1.4.0 → 1.4.1

package/dist/resolver/compile.mjs

@@ -0,0 +1,396 @@
+import { buildLogicalComparisonPlan, buildLogicalPlan } from "gscdump/query/plan";
+import { sql } from "drizzle-orm";
+import { and as and$1, gte as gte$1, impressions } from "gscdump/query";
+const COMPARISON_FILTER_SQL = {
+	new: sql`AND COALESCE(p.impressions, 0) = 0 AND COALESCE(c.impressions, 0) > 0`,
+	lost: sql`AND COALESCE(p.impressions, 0) > 0 AND COALESCE(c.impressions, 0) = 0`,
+	improving: sql`AND COALESCE(c.clicks, 0) > COALESCE(p.clicks, 0)`,
+	declining: sql`AND COALESCE(c.clicks, 0) < COALESCE(p.clicks, 0) AND COALESCE(p.clicks, 0) > 0`
+};
+function collapseWs(s) {
+	return s.replace(/\s+/g, " ").trim();
+}
+function joinAnd(parts) {
+	return sql.join(parts, sql` AND `);
+}
+function joinComma(parts) {
+	return sql.join(parts, sql`, `);
+}
+const ORDER_BY_HELPER_PREFIX = "__order_";
+function withMinimumImpressions(state, options) {
+	if (options.minimumImpressions === void 0) return state;
+	const minimum = Number(options.minimumImpressions);
+	if (!Number.isFinite(minimum) || minimum < 0) throw new RangeError("minimumImpressions must be a finite non-negative number");
+	const guard = gte$1(impressions, minimum);
+	return {
+		...state,
+		prefilter: state.prefilter ? and$1(state.prefilter, guard) : guard
+	};
+}
+function orderByClause(state, prefix = "", columnOverride) {
+	if (state.orderBy) {
+		const safeCol = (columnOverride ?? state.orderBy.column).replace(/\W/g, "");
+		const safeDir = state.orderBy.dir.toUpperCase() === "ASC" ? "ASC" : "DESC";
+		return sql.raw(`ORDER BY ${prefix}${safeCol} ${safeDir}`);
+	}
+	return sql.raw(`ORDER BY ${prefix}clicks DESC`);
+}
+function limitOffsetClause(state) {
+	const rowLimit = Math.max(0, Math.floor(Number(state.rowLimit ?? 100)));
+	const offset = state.startRow ? Math.max(0, Math.floor(Number(state.startRow))) : 0;
+	return sql.raw(offset > 0 ? `LIMIT ${rowLimit} OFFSET ${offset}` : `LIMIT ${rowLimit}`);
+}
+function aliasRaw(name) {
+	const safe = name.replace(/\W/g, "");
+	return sql.raw(`"${safe}"`);
+}
+function toInternalDimensionFilters(filters) {
+	return filters.map((filter) => ({
+		dimension: filter.dimension,
+		operator: filter.operator,
+		expression: filter.expression,
+		expression2: filter.expression2
+	}));
+}
+function toInternalMetricFilters(filters) {
+	return filters.map((filter) => ({
+		dimension: filter.metric,
+		operator: filter.operator,
+		expression: String(filter.expression),
+		expression2: filter.expression2 == null ? void 0 : String(filter.expression2)
+	}));
+}
+function topLevelFilters(plan) {
+	if (!plan.specialFilters.topLevel) return [];
+	return [{
+		dimension: "page",
+		operator: "topLevel",
+		expression: ""
+	}];
+}
+function logicalFilterToInternal(filter) {
+	return {
+		dimension: filter.dimension,
+		operator: filter.operator,
+		expression: filter.expression,
+		expression2: filter.expression2
+	};
+}
+function compileFilterTree(node, adapter, tableKey) {
+	if (!node) return void 0;
+	if (node.kind === "leaf") return adapter.dimensionPredicates([logicalFilterToInternal(node.filter)], tableKey)[0];
+	const childSqls = node.children.map((child) => compileFilterTree(child, adapter, tableKey)).filter((s) => s !== void 0);
+	if (childSqls.length === 0) return void 0;
+	if (childSqls.length === 1) return childSqls[0];
+	const sep = node.groupType === "or" ? sql` OR ` : sql` AND `;
+	return sql`(${sql.join(childSqls, sep)})`;
+}
+function buildScope(state, options) {
+	const { adapter, siteId, searchType } = options;
+	const plan = buildLogicalPlan(state, adapter.capabilities);
+	const tableKey = adapter.tableKeyForDataset(plan.dataset);
+	const dimFilters = toInternalDimensionFilters(plan.dimensionFilters);
+	const metricFilters = toInternalMetricFilters(plan.metricFilters);
+	const prefilters = toInternalMetricFilters(plan.prefilters);
+	const groupByDims = plan.groupByDimensions;
+	const hasDate = plan.hasDate;
+	const metrics = plan.metrics;
+	const queryCanonicalUsed = groupByDims.includes("queryCanonical") || plan.dimensionFilters.some((filter) => filter.dimension === "queryCanonical");
+	const wherePredicates = [];
+	if (adapter.siteIdColRef && siteId != null) wherePredicates.push(sql`${adapter.siteIdColRef(tableKey)} = ${siteId}`);
+	if (adapter.searchTypeColRef && searchType != null) wherePredicates.push(sql`${adapter.searchTypeColRef(tableKey)} = ${searchType}`);
+	wherePredicates.push(sql`${adapter.dateColRef(tableKey)} >= ${plan.dateRange.startDate}`);
+	wherePredicates.push(sql`${adapter.dateColRef(tableKey)} <= ${plan.dateRange.endDate}`);
+	wherePredicates.push(...adapter.prefilterPredicates(prefilters, tableKey));
+	const dimSql = plan.dimensionFilterTree ? compileFilterTree(plan.dimensionFilterTree, adapter, tableKey) : void 0;
+	if (dimSql) wherePredicates.push(dimSql);
+	else if (!plan.dimensionFilterTree) wherePredicates.push(...adapter.dimensionPredicates(dimFilters, tableKey));
+	const tl = adapter.topLevelPredicate(topLevelFilters(plan), tableKey);
+	if (tl) wherePredicates.push(tl);
+	return {
+		plan,
+		tableKey,
+		groupByDims,
+		hasDate,
+		metrics,
+		wherePredicates,
+		having: adapter.havingPredicates(metricFilters, tableKey),
+		dimFilters,
+		startDate: plan.dateRange.startDate,
+		endDate: plan.dateRange.endDate,
+		queryCanonicalUsed
+	};
+}
+function buildComparisonPlan(current, previous, capabilities) {
+	return buildLogicalComparisonPlan(current, previous, capabilities);
+}
+function compileCollapsed(adapter, q) {
+	const c = adapter.compile(q);
+	return {
+		sql: collapseWs(c.sql),
+		params: c.params
+	};
+}
+function resolveToSQLOptimized(state, options) {
+	state = withMinimumImpressions(state, options);
+	const { adapter } = options;
+	const { tableKey, groupByDims, hasDate, metrics, wherePredicates, having, queryCanonicalUsed } = buildScope(state, options);
+	const table = adapter.fromSql(tableKey, { queryCanonical: queryCanonicalUsed });
+	const schema = adapter.schema;
+	const cteSelect = [];
+	for (const d of groupByDims) {
+		const expr = adapter.dimExprSql(d, tableKey);
+		const colName = adapter.dimColumn(d, tableKey);
+		if (d === "page" || colName !== d) cteSelect.push(sql`${expr} as ${aliasRaw(d)}`);
+		else cteSelect.push(expr);
+	}
+	if (hasDate) cteSelect.push(adapter.dateColRef(tableKey));
+	const t = schema[tableKey];
+	cteSelect.push(sql`CAST(SUM(${t.clicks}) AS DOUBLE) as clicks`);
+	cteSelect.push(sql`CAST(SUM(${t.impressions}) AS DOUBLE) as impressions`);
+	cteSelect.push(sql`CAST(SUM(${t.sum_position}) AS DOUBLE) as sum_position`);
+	const groupByExprs = groupByDims.map((d) => adapter.dimExprSql(d, tableKey));
+	if (hasDate) groupByExprs.push(adapter.dateColRef(tableKey));
+	const outerSelect = [];
+	for (const d of groupByDims) outerSelect.push(aliasRaw(d));
+	if (hasDate) outerSelect.push(sql.raw("date"));
+	const outerTotals = [];
+	for (const m of metrics) switch (m) {
+		case "clicks":
+			outerSelect.push(sql.raw("clicks"));
+			outerTotals.push(sql.raw("CAST(SUM(clicks) OVER() AS DOUBLE) as totalClicks"));
+			break;
+		case "impressions":
+			outerSelect.push(sql.raw("impressions"));
+			outerTotals.push(sql.raw("CAST(SUM(impressions) OVER() AS DOUBLE) as totalImpressions"));
+			break;
+		case "ctr":
+			outerSelect.push(sql.raw("CAST(clicks AS REAL) / NULLIF(impressions, 0) as ctr"));
+			outerTotals.push(sql.raw("CAST(SUM(clicks) OVER() AS REAL) / NULLIF(SUM(impressions) OVER(), 0) as totalCtr"));
+			break;
+		case "position":
+			outerSelect.push(sql.raw("sum_position / NULLIF(impressions, 0) + 1 as position"));
+			outerTotals.push(sql.raw("SUM(sum_position) OVER() / NULLIF(SUM(impressions) OVER(), 0) + 1 as totalPosition"));
+			break;
+	}
+	let orderByColumnOverride;
+	const orderColumn = state.orderBy?.column;
+	if (orderColumn && orderColumn !== "date" && !metrics.includes(orderColumn)) {
+		orderByColumnOverride = `${ORDER_BY_HELPER_PREFIX}${orderColumn}`;
+		switch (orderColumn) {
+			case "clicks":
+				outerSelect.push(sql.raw(`clicks as "${orderByColumnOverride}"`));
+				break;
+			case "impressions":
+				outerSelect.push(sql.raw(`impressions as "${orderByColumnOverride}"`));
+				break;
+			case "ctr":
+				outerSelect.push(sql.raw(`CAST(clicks AS REAL) / NULLIF(impressions, 0) as "${orderByColumnOverride}"`));
+				break;
+			case "position":
+				outerSelect.push(sql.raw(`sum_position / NULLIF(impressions, 0) + 1 as "${orderByColumnOverride}"`));
+				break;
+		}
+	}
+	outerSelect.push(sql.raw("COUNT(*) OVER() as totalCount"));
+	for (const totalExpr of outerTotals) outerSelect.push(totalExpr);
+	let cte = wherePredicates.length > 0 ? sql`SELECT ${joinComma(cteSelect)} FROM ${table} WHERE ${joinAnd(wherePredicates)}` : sql`SELECT ${joinComma(cteSelect)} FROM ${table}`;
+	if (groupByExprs.length > 0) cte = sql`${cte} GROUP BY ${joinComma(groupByExprs)}`;
+	if (having.length > 0) cte = sql`${cte} HAVING ${joinAnd(having)}`;
+	return compileCollapsed(adapter, sql`WITH aggregated AS (${cte}) SELECT ${joinComma(outerSelect)} FROM aggregated ${orderByClause(state, "", orderByColumnOverride)} ${limitOffsetClause(state)}`);
+}
+function resolveToSQL(state, options) {
+	state = withMinimumImpressions(state, options);
+	const { adapter } = options;
+	const { tableKey, groupByDims, hasDate, metrics, wherePredicates, having, queryCanonicalUsed } = buildScope(state, options);
+	const table = adapter.fromSql(tableKey, { queryCanonical: queryCanonicalUsed });
+	const selectExprs = [];
+	for (const d of groupByDims) {
+		const expr = adapter.dimExprSql(d, tableKey);
+		const colName = adapter.dimColumn(d, tableKey);
+		if (d === "page" || colName !== d) selectExprs.push(sql`${expr} as ${aliasRaw(d)}`);
+		else selectExprs.push(expr);
+	}
+	if (hasDate) selectExprs.push(adapter.dateColRef(tableKey));
+	for (const m of metrics) selectExprs.push(sql`${adapter.metricSql(m, tableKey)} as ${aliasRaw(m)}`);
+	const groupByExprs = groupByDims.map((d) => adapter.dimExprSql(d, tableKey));
+	if (hasDate) groupByExprs.push(adapter.dateColRef(tableKey));
+	let body = wherePredicates.length > 0 ? sql`SELECT ${joinComma(selectExprs)} FROM ${table} WHERE ${joinAnd(wherePredicates)}` : sql`SELECT ${joinComma(selectExprs)} FROM ${table}`;
+	if (groupByExprs.length > 0) body = sql`${body} GROUP BY ${joinComma(groupByExprs)}`;
+	if (having.length > 0) body = sql`${body} HAVING ${joinAnd(having)}`;
+	const mainQuery = sql`${body} ${orderByClause(state)} ${limitOffsetClause(state)}`;
+	let countQuery;
+	if (groupByExprs.length > 0) {
+		let inner = wherePredicates.length > 0 ? sql`SELECT ${joinComma(groupByExprs)} FROM ${table} WHERE ${joinAnd(wherePredicates)} GROUP BY ${joinComma(groupByExprs)}` : sql`SELECT ${joinComma(groupByExprs)} FROM ${table} GROUP BY ${joinComma(groupByExprs)}`;
+		if (having.length > 0) inner = sql`${inner} HAVING ${joinAnd(having)}`;
+		countQuery = sql`SELECT COUNT(*) as total FROM (${inner})`;
+	} else countQuery = wherePredicates.length > 0 ? sql`SELECT COUNT(*) as total FROM ${table} WHERE ${joinAnd(wherePredicates)}` : sql`SELECT COUNT(*) as total FROM ${table}`;
+	const main = compileCollapsed(adapter, mainQuery);
+	const count = compileCollapsed(adapter, countQuery);
+	return {
+		sql: main.sql,
+		params: main.params,
+		countSql: count.sql,
+		countParams: count.params
+	};
+}
+function buildTotalsSql(state, options) {
+	state = withMinimumImpressions(state, options);
+	const { adapter } = options;
+	const { tableKey, metrics, wherePredicates, queryCanonicalUsed } = buildScope(state, options);
+	const table = adapter.fromSql(tableKey, { queryCanonical: queryCanonicalUsed });
+	const selectExprs = metrics.map((m) => sql`${adapter.metricSql(m, tableKey)} as ${aliasRaw(m)}`);
+	return compileCollapsed(adapter, wherePredicates.length > 0 ? sql`SELECT ${joinComma(selectExprs)} FROM ${table} WHERE ${joinAnd(wherePredicates)}` : sql`SELECT ${joinComma(selectExprs)} FROM ${table}`);
+}
+function resolveComparisonSQL(current, previous, options, comparisonFilter) {
+	const { adapter, siteId, searchType } = options;
+	const comparisonPlan = buildComparisonPlan(current, previous, adapter.capabilities);
+	const currentScope = buildScope(current, options);
+	const previousScope = buildScope(previous, options);
+	const { tableKey, groupByDims, metrics, wherePredicates: currentWhere, having } = currentScope;
+	const table = adapter.fromSql(tableKey, { queryCanonical: currentScope.queryCanonicalUsed || previousScope.queryCanonicalUsed });
+	const dimSelectExprs = [];
+	for (const d of groupByDims) {
+		const expr = adapter.dimExprSql(d, tableKey);
+		const colName = adapter.dimColumn(d, tableKey);
+		if (d === "page" || colName !== d) dimSelectExprs.push(sql`${expr} as ${aliasRaw(d)}`);
+		else dimSelectExprs.push(expr);
+	}
+	const currentSelect = [...dimSelectExprs, ...metrics.map((m) => sql`${adapter.metricSql(m, tableKey)} as ${aliasRaw(m)}`)];
+	const prevSelect = [...dimSelectExprs, ...adapter.METRIC_NAMES.map((m) => sql`${adapter.metricSql(m, tableKey)} as ${aliasRaw(m)}`)];
+	const groupByExprs = groupByDims.map((d) => adapter.dimExprSql(d, tableKey));
+	const prevWhere = [];
+	if (adapter.siteIdColRef && siteId != null) prevWhere.push(sql`${adapter.siteIdColRef(tableKey)} = ${siteId}`);
+	if (adapter.searchTypeColRef && searchType != null) prevWhere.push(sql`${adapter.searchTypeColRef(tableKey)} = ${searchType}`);
+	if (previousScope.startDate) prevWhere.push(sql`${adapter.dateColRef(tableKey)} >= ${previousScope.startDate}`);
+	if (previousScope.endDate) prevWhere.push(sql`${adapter.dateColRef(tableKey)} <= ${previousScope.endDate}`);
+	const prevDimSql = comparisonPlan.current.dimensionFilterTree ? compileFilterTree(comparisonPlan.current.dimensionFilterTree, adapter, tableKey) : void 0;
+	if (prevDimSql) prevWhere.push(prevDimSql);
+	else if (!comparisonPlan.current.dimensionFilterTree) prevWhere.push(...adapter.dimensionPredicates(toInternalDimensionFilters(comparisonPlan.current.dimensionFilters), tableKey));
+	let currentCte = currentWhere.length > 0 ? sql`SELECT ${joinComma(currentSelect)} FROM ${table} WHERE ${joinAnd(currentWhere)}` : sql`SELECT ${joinComma(currentSelect)} FROM ${table}`;
+	if (groupByExprs.length > 0) currentCte = sql`${currentCte} GROUP BY ${joinComma(groupByExprs)}`;
+	if (having.length > 0) currentCte = sql`${currentCte} HAVING ${joinAnd(having)}`;
+	let previousCte = prevWhere.length > 0 ? sql`SELECT ${joinComma(prevSelect)} FROM ${table} WHERE ${joinAnd(prevWhere)}` : sql`SELECT ${joinComma(prevSelect)} FROM ${table}`;
+	if (groupByExprs.length > 0) previousCte = sql`${previousCte} GROUP BY ${joinComma(groupByExprs)}`;
+	const joinOn = groupByDims.length > 0 ? sql.raw(groupByDims.map((d) => `c.${d.replace(/\W/g, "")} = p.${d.replace(/\W/g, "")}`).join(" AND ")) : sql.raw("1=1");
+	const filterClause = comparisonFilter ? COMPARISON_FILTER_SQL[comparisonFilter] : sql.raw("");
+	const orderSql = orderByClause(current, "");
+	const limitSql = limitOffsetClause(current);
+	const outerCurrentCols = [];
+	for (const d of groupByDims) {
+		const colName = d.replace(/\W/g, "");
+		outerCurrentCols.push(sql.raw(`COALESCE(c.${colName}, p.${colName}) as "${colName}"`));
+	}
+	outerCurrentCols.push(sql.raw("CAST(COALESCE(c.clicks, 0) AS DOUBLE) as \"clicks\""));
+	outerCurrentCols.push(sql.raw("CAST(COALESCE(c.impressions, 0) AS DOUBLE) as \"impressions\""));
+	outerCurrentCols.push(sql.raw("COALESCE(c.ctr, 0) as \"ctr\""));
+	outerCurrentCols.push(sql.raw("COALESCE(c.position, 0) as \"position\""));
+	const mainQuery = sql`WITH current AS (${currentCte}), previous AS (${previousCte}) SELECT ${joinComma(outerCurrentCols)}, COALESCE(CAST(p.clicks AS DOUBLE), 0) as "prevClicks", COALESCE(CAST(p.impressions AS DOUBLE), 0) as "prevImpressions", COALESCE(p.ctr, 0) as "prevCtr", COALESCE(p.position, 0) as "prevPosition" FROM current c FULL OUTER JOIN previous p ON ${joinOn} WHERE 1=1 ${filterClause} ${orderSql} ${limitSql}`;
+	const firstGroupBy = groupByDims[0] ? groupByDims[0].replace(/\W/g, "") : "clicks";
+	const countInnerSelect = groupByDims[0] ? sql.raw(`COALESCE(c.${firstGroupBy}, p.${firstGroupBy})`) : sql.raw(`c.${firstGroupBy}`);
+	const countQuery = sql`WITH current AS (${currentCte}), previous AS (${previousCte}) SELECT COUNT(*) as total FROM (SELECT ${countInnerSelect} FROM current c FULL OUTER JOIN previous p ON ${joinOn} WHERE 1=1 ${filterClause})`;
+	const main = compileCollapsed(adapter, mainQuery);
+	const count = compileCollapsed(adapter, countQuery);
+	return {
+		sql: main.sql,
+		params: main.params,
+		countSql: count.sql,
+		countParams: count.params
+	};
+}
+function buildExtrasQueries(state, options) {
+	const { adapter, siteId, searchType } = options;
+	const plan = buildLogicalPlan(state, adapter.capabilities);
+	const dims = plan.groupByDimensions;
+	const extras = [];
+	if (!dims.includes("queryCanonical")) return extras;
+	const queriesKey = adapter.tableKeyForDataset("queries");
+	const t = adapter.schema[queriesKey];
+	const table = adapter.fromSql(queriesKey, { queryCanonical: true });
+	const whereParts = [];
+	if (adapter.siteIdColRef && siteId != null) whereParts.push(sql`${adapter.siteIdColRef(queriesKey)} = ${siteId}`);
+	if (adapter.searchTypeColRef && searchType != null) whereParts.push(sql`${adapter.searchTypeColRef(queriesKey)} = ${searchType}`);
+	whereParts.push(sql`${adapter.dateColRef(queriesKey)} >= ${plan.dateRange.startDate}`);
+	whereParts.push(sql`${adapter.dateColRef(queriesKey)} <= ${plan.dateRange.endDate}`);
+	const whereExpr = whereParts.length > 0 ? sql`WHERE ${joinAnd(whereParts)}` : sql``;
+	const outerQueryCol = sql.raw("query");
+	const canonKey = adapter.dimExprSql("queryCanonical", queriesKey);
+	const compiled = compileCollapsed(adapter, sql`WITH per_variant AS (SELECT ${canonKey} as joinKey, ${t.query} as query, SUM(${t.clicks}) as clicks, SUM(${t.impressions}) as impressions, SUM(${t.sum_position}) as sum_pos, ROW_NUMBER() OVER (PARTITION BY ${canonKey} ORDER BY SUM(${t.clicks}) DESC) as rn, COUNT(*) OVER (PARTITION BY ${canonKey}) as variantCount FROM ${table} ${whereExpr} GROUP BY ${canonKey}, ${t.query}) SELECT joinKey, MAX(variantCount) as variantCount, MAX(CASE WHEN rn = 1 THEN ${outerQueryCol} END) as canonicalName, GROUP_CONCAT(CASE WHEN rn <= 10 THEN ${outerQueryCol} || ':::' || clicks || ':::' || impressions || ':::' || CAST(ROUND(CAST(sum_pos AS REAL) / NULLIF(impressions, 0) + 1, 1) AS TEXT) END, '||') as variants FROM per_variant GROUP BY joinKey`);
+	extras.push({
+		key: "canonicalExtras",
+		sql: compiled.sql,
+		params: compiled.params
+	});
+	return extras;
+}
+function mergeExtras(rows, extrasResults) {
+	if (extrasResults.length === 0) return rows;
+	const lookups = [];
+	const parseVariants = (raw) => {
+		if (raw.length === 0) return [];
+		const encoded = raw.split("||");
+		const variants = [];
+		for (const value of encoded) {
+			if (value.length === 0) continue;
+			const parts = value.split(":::");
+			variants.push({
+				query: parts[0],
+				clicks: Number(parts[1] || 0),
+				impressions: Number(parts[2] || 0),
+				position: Number(parts[3] || 0)
+			});
+		}
+		return variants;
+	};
+	for (const { key, results } of extrasResults) {
+		if (key === "canonicalExtras") {
+			const map = /* @__PURE__ */ new Map();
+			for (const r of results) {
+				const jk = String(r.joinKey);
+				const raw = r.variants;
+				map.set(jk, {
+					variantCount: r.variantCount,
+					variants: typeof raw === "string" ? parseVariants(raw) : [],
+					canonicalName: r.canonicalName
+				});
+			}
+			lookups.push({
+				kind: "canonical",
+				map
+			});
+			continue;
+		}
+		const map = /* @__PURE__ */ new Map();
+		for (const r of results) {
+			if (r.rn !== void 0 && r.rn !== 1) continue;
+			let val = r[key];
+			if (key === "variants" && typeof val === "string") val = parseVariants(val);
+			map.set(String(r.joinKey), val);
+		}
+		lookups.push({
+			kind: "generic",
+			key,
+			map
+		});
+	}
+	return rows.map((row) => {
+		const enriched = { ...row };
+		for (const lookup of lookups) {
+			if (lookup.kind === "canonical") {
+				const joinValue = String(row.queryCanonical ?? row.query_canonical ?? "");
+				const extra = joinValue ? lookup.map.get(joinValue) : void 0;
+				enriched.variantCount = extra?.variantCount ?? null;
+				enriched.variants = extra?.variants ?? [];
+				enriched.canonicalName = extra?.canonicalName ?? null;
+				if (enriched.canonicalName) enriched.queryCanonical = enriched.canonicalName;
+				continue;
+			}
+			const { key, map } = lookup;
+			const joinValue = key === "variantCount" || key === "variants" || key === "canonicalName" ? String(row.queryCanonical ?? row.query_canonical ?? "") : void 0;
+			enriched[key] = (joinValue && map.get(joinValue)) ?? (key === "variants" ? [] : null);
+			if (key === "canonicalName" && enriched[key]) enriched.queryCanonical = enriched[key];
+		}
+		return enriched;
+	});
+}
+export { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized };

package/dist/resolver/datasets.d.mts

@@ -0,0 +1,16 @@
+import { LogicalDataset as LogicalDataset$1, UnresolvableDatasetError, inferDataset as inferLogicalDataset, isDatasetResolvable } from "gscdump/query/plan";
+import { Dimension } from "gscdump/query";
+type DimensionSurface = 'api' | 'stored' | 'derived';
+interface DimensionBinding {
+  column: string;
+  surfaces: readonly DimensionSurface[];
+}
+interface LogicalDatasetDefinition {
+  dimensions: Partial<Record<Dimension, DimensionBinding>>;
+}
+declare const DIMENSION_SURFACES: Record<Dimension, readonly DimensionSurface[]>;
+declare const LOGICAL_DATASETS: Record<LogicalDataset$1, LogicalDatasetDefinition>;
+declare function dimensionColumn(dim: Dimension, dataset: LogicalDataset$1): string;
+declare function supportsDimensionOnSurface(dim: Dimension, surface: DimensionSurface): boolean;
+declare function assertDimensionsSupported(dimensions: readonly Dimension[], surface: DimensionSurface, context: string): void;
+export { DIMENSION_SURFACES, DimensionBinding, DimensionSurface, LOGICAL_DATASETS, type LogicalDataset$1 as LogicalDataset, LogicalDatasetDefinition, UnresolvableDatasetError, assertDimensionsSupported, dimensionColumn, inferLogicalDataset, isDatasetResolvable, supportsDimensionOnSurface };

package/dist/resolver/datasets.mjs

@@ -0,0 +1,159 @@
+import { UnresolvableDatasetError, inferDataset as inferLogicalDataset, isDatasetResolvable } from "gscdump/query/plan";
+const DIMENSION_SURFACES = {
+	page: ["api", "stored"],
+	query: ["api", "stored"],
+	queryCanonical: ["derived"],
+	country: ["api", "stored"],
+	device: ["api", "stored"],
+	searchAppearance: ["api", "stored"],
+	date: ["api", "stored"],
+	hour: ["api", "stored"]
+};
+const LOGICAL_DATASETS = {
+	pages: { dimensions: {
+		page: {
+			column: "url",
+			surfaces: ["api", "stored"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["api", "stored"]
+		}
+	} },
+	queries: { dimensions: {
+		query: {
+			column: "query",
+			surfaces: ["api", "stored"]
+		},
+		queryCanonical: {
+			column: "query_canonical",
+			surfaces: ["derived"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["api", "stored"]
+		}
+	} },
+	page_queries: { dimensions: {
+		page: {
+			column: "url",
+			surfaces: ["api", "stored"]
+		},
+		query: {
+			column: "query",
+			surfaces: ["api", "stored"]
+		},
+		queryCanonical: {
+			column: "query_canonical",
+			surfaces: ["derived"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["api", "stored"]
+		}
+	} },
+	countries: { dimensions: {
+		country: {
+			column: "country",
+			surfaces: ["api", "stored"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["api", "stored"]
+		}
+	} },
+	dates: { dimensions: { date: {
+		column: "date",
+		surfaces: ["api", "stored"]
+	} } },
+	search_appearance: { dimensions: {
+		searchAppearance: {
+			column: "searchAppearance",
+			surfaces: ["api", "stored"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["api", "stored"]
+		}
+	} },
+	search_appearance_pages: { dimensions: {
+		searchAppearance: {
+			column: "searchAppearance",
+			surfaces: ["stored"]
+		},
+		page: {
+			column: "url",
+			surfaces: ["stored"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["stored"]
+		}
+	} },
+	search_appearance_queries: { dimensions: {
+		searchAppearance: {
+			column: "searchAppearance",
+			surfaces: ["stored"]
+		},
+		query: {
+			column: "query",
+			surfaces: ["stored"]
+		},
+		queryCanonical: {
+			column: "query_canonical",
+			surfaces: ["derived"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["stored"]
+		}
+	} },
+	search_appearance_page_queries: { dimensions: {
+		searchAppearance: {
+			column: "searchAppearance",
+			surfaces: ["stored"]
+		},
+		page: {
+			column: "url",
+			surfaces: ["stored"]
+		},
+		query: {
+			column: "query",
+			surfaces: ["stored"]
+		},
+		queryCanonical: {
+			column: "query_canonical",
+			surfaces: ["derived"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["stored"]
+		}
+	} },
+	hourly_pages: { dimensions: {
+		page: {
+			column: "url",
+			surfaces: ["api", "stored"]
+		},
+		date: {
+			column: "date",
+			surfaces: ["api", "stored"]
+		},
+		hour: {
+			column: "hour",
+			surfaces: ["api", "stored"]
+		}
+	} }
+};
+function dimensionColumn(dim, dataset) {
+	return LOGICAL_DATASETS[dataset].dimensions[dim]?.column ?? dim;
+}
+function supportsDimensionOnSurface(dim, surface) {
+	return DIMENSION_SURFACES[dim].includes(surface);
+}
+function assertDimensionsSupported(dimensions, surface, context) {
+	const unsupported = dimensions.filter((dim) => !supportsDimensionOnSurface(dim, surface));
+	if (unsupported.length === 0) return;
+	throw new Error(`${context}: unsupported dimensions for ${surface}: ${unsupported.join(", ")}`);
+}
+export { DIMENSION_SURFACES, LOGICAL_DATASETS, UnresolvableDatasetError, assertDimensionsSupported, dimensionColumn, inferLogicalDataset, isDatasetResolvable, supportsDimensionOnSurface };

package/dist/resolver/extras-overlay.d.mts

@@ -0,0 +1,37 @@
+import { SearchType } from "../storage.mjs";
+import { ResolveExtraFn } from "./run-query.mjs";
+/**
+ * Host-supplied reader: return the materialised rollup's rows for an
+ * `(id, tenant, slice)`, in the exact shape the live extra produces, or `null`
+ * when no rollup exists (first sync, never built, stale) so the overlay
+ * declines and the resolver falls back to the live query. Typically wired with
+ * `readLatestRollup` + a `read_parquet` of the pointer.
+ *
+ * `dateRange` is the request window. `query_canonical_variants` is full-history
+ * (its grouping/variant metrics span all dates), but `buildExtrasQueries`
+ * windows the live `canonicalExtras` to the requested range — so for a narrow
+ * window the reader MUST decline (return `null`) rather than attach
+ * out-of-window variantCount/canonicalName/variants. A common rule: serve only
+ * when the request window covers full history.
+ */
+interface RollupRowsReader {
+  (opts: {
+    id: string;
+    ctx: {
+      userId: string;
+      siteId: string;
+    };
+    searchType?: SearchType;
+    dateRange: {
+      startDate: string;
+      endDate: string;
+    };
+  }): Promise<Array<Record<string, unknown>> | null>;
+}
+/**
+ * Build a {@link ResolveExtraFn} that serves resolver extras from materialised
+ * rollups when one is mapped for the extra's key, else returns `null` to fall
+ * back to the live SQL. Pure wiring around the host's `readRollupRows`.
+ */
+declare function createRollupExtrasOverlay(readRollupRows: RollupRowsReader): ResolveExtraFn;
+export { RollupRowsReader, createRollupExtrasOverlay };

package/dist/resolver/extras-overlay.mjs

@@ -0,0 +1,17 @@
+const EXTRA_ROLLUP_IDS = { canonicalExtras: "query_canonical_variants" };
+function createRollupExtrasOverlay(readRollupRows) {
+	return async ({ key, ctx, dateRange }) => {
+		const id = EXTRA_ROLLUP_IDS[key];
+		if (id === void 0) return null;
+		return readRollupRows({
+			id,
+			ctx: {
+				userId: ctx.userId,
+				siteId: ctx.siteId
+			},
+			dateRange,
+			...ctx.searchType !== void 0 ? { searchType: ctx.searchType } : {}
+		});
+	};
+}
+export { createRollupExtrasOverlay };

package/dist/resolver/filter-utils.d.mts

@@ -0,0 +1,10 @@
+import { Dimension, FilterInput, InternalFilter, Metric } from "gscdump/query";
+declare function getInternalFilters(filter: FilterInput | undefined): InternalFilter[];
+declare function getDimensionFilters(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): InternalFilter[];
+declare function getFilterDimensions(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): Dimension[];
+declare function metricValue(row: Record<string, unknown>, metric: string): number;
+declare function dimensionValue(row: Record<string, unknown>, dimension: string): string;
+declare function matchesDimensionFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
+declare function matchesMetricFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
+declare function matchesTopLevelPage(row: Record<string, unknown>): boolean;
+export { dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue };