@gscdump/engine-duckdb-wasm 1.3.2 → 1.4.1

package/dist/archetype-sql.d.mts

@@ -0,0 +1,15 @@
+import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
+/** A compiled, parameterised statement. */
+interface CompiledArchetypeSql {
+  sql: string;
+  params: unknown[];
+  /** The fact-table view the query reads. */
+  table: string;
+}
+/**
+ * Compile one archetype query to DuckDB SQL. Throws for `aux-cloud-only`.
+ */
+declare function compileArchetypeSql(query: ArchetypeQuery): CompiledArchetypeSql;
+/** The fact-table view an archetype reads — drives per-table browser routing. */
+declare function tableForArchetype(query: ArchetypeQuery): string | null;
+export { CompiledArchetypeSql, compileArchetypeSql, tableForArchetype };

package/dist/archetype-sql.mjs

@@ -0,0 +1,373 @@
+const METRIC_SQL = {
+	clicks: "SUM(clicks)",
+	impressions: "SUM(impressions)",
+	ctr: "CASE WHEN SUM(impressions) = 0 THEN 0 ELSE SUM(clicks) * 1.0 / SUM(impressions) END",
+	position: "CASE WHEN SUM(impressions) = 0 THEN NULL ELSE SUM(sum_position) * 1.0 / SUM(impressions) + 1 END"
+};
+const DIM_COLUMN = {
+	page: "url",
+	query: "query",
+	country: "country",
+	date: "date",
+	searchAppearance: "search_appearance"
+};
+function quoteIdent(value) {
+	return `"${value.replace(/"/g, "\"\"")}"`;
+}
+function qualifiedColumn(table, column) {
+	return `${quoteIdent(table)}.${quoteIdent(column)}`;
+}
+function queryCanonicalExpr(table) {
+	const queryRef = qualifiedColumn(table, "query");
+	return `COALESCE((SELECT qd.query_canonical FROM query_dim qd WHERE qd.query = ${queryRef} LIMIT 1), ${queryRef})`;
+}
+function dimExpr(dim, table) {
+	return dim === "queryCanonical" ? queryCanonicalExpr(table) : DIM_COLUMN[dim] ?? dim;
+}
+function tableForDimensions(dims) {
+	const set = new Set(dims.filter((d) => d !== "date"));
+	if (set.has("page") && (set.has("query") || set.has("queryCanonical"))) return "page_queries";
+	if (set.has("query") || set.has("queryCanonical")) return "queries";
+	if (set.has("country")) return "countries";
+	if (set.has("device")) return "dates";
+	return "pages";
+}
+function tableForTopNBreakdown(query) {
+	const dims = [query.dimension];
+	for (const facet of query.facets ?? []) {
+		const hasPage = query.dimension === "page" || facet.column === "page";
+		const hasQuery = query.dimension === "query" || query.dimension === "queryCanonical" || facet.column === "query" || facet.column === "queryCanonical";
+		if (hasPage && hasQuery) dims.push(facet.column);
+	}
+	return tableForDimensions(dims);
+}
+function metricExpr(metric) {
+	const expr = METRIC_SQL[metric];
+	if (!expr) throw new Error(`[archetype-sql] unknown metric: ${metric}`);
+	return expr;
+}
+function metricSelectList(metrics) {
+	return metrics.map((m) => `${metricExpr(m)} AS ${m}`).join(", ");
+}
+const DEVICE_VALUES = [
+	"DESKTOP",
+	"MOBILE",
+	"TABLET"
+];
+const DEVICE_SUFFIX = {
+	DESKTOP: "desktop",
+	MOBILE: "mobile",
+	TABLET: "tablet"
+};
+function deviceMetricExpr(metric, suffix) {
+	switch (metric) {
+		case "clicks": return `SUM(clicks_${suffix})`;
+		case "impressions": return `SUM(impressions_${suffix})`;
+		case "ctr": return `CASE WHEN SUM(impressions_${suffix}) = 0 THEN 0 ELSE SUM(clicks_${suffix}) * 1.0 / SUM(impressions_${suffix}) END`;
+		case "position": return `CASE WHEN SUM(impressions_${suffix}) = 0 THEN NULL ELSE SUM(sum_position_${suffix}) * 1.0 / SUM(impressions_${suffix}) + 1 END`;
+		default: throw new Error(`[archetype-sql] unknown metric: ${metric}`);
+	}
+}
+function deviceUnpivotSql(metrics, whereSql, byDate) {
+	const dateCol = byDate ? "date, " : "";
+	const dateGroup = byDate ? " GROUP BY date" : "";
+	return DEVICE_VALUES.map((dv) => {
+		const suffix = DEVICE_SUFFIX[dv];
+		const mcols = metrics.map((m) => `${deviceMetricExpr(m, suffix)} AS ${m}`).join(", ");
+		return `SELECT ${dateCol}'${dv}' AS device, ${mcols} FROM dates WHERE ${whereSql}${dateGroup}`;
+	}).join(" UNION ALL ");
+}
+function rangePredicate(q) {
+	return {
+		sql: "date BETWEEN ? AND ?",
+		params: [q.range.start, q.range.end]
+	};
+}
+function compareRangePredicate(q) {
+	if (!q.compareRange) return null;
+	return {
+		sql: "date BETWEEN ? AND ?",
+		params: [q.compareRange.start, q.compareRange.end]
+	};
+}
+const STD_METRICS = [
+	"clicks",
+	"impressions",
+	"ctr",
+	"position"
+];
+function coalesceMetric(metric, src, alias) {
+	const ref = `${src}.${metric}`;
+	return metric === "clicks" || metric === "impressions" ? `CAST(COALESCE(${ref}, 0) AS DOUBLE) AS ${alias}` : `COALESCE(${ref}, 0) AS ${alias}`;
+}
+function prevAlias(metric) {
+	return `prev${metric.charAt(0).toUpperCase()}${metric.slice(1)}`;
+}
+function moverClause(movers) {
+	const curClicks = "COALESCE(c.clicks, 0)";
+	const prevClicks = "COALESCE(p.clicks, 0)";
+	const curImpr = "COALESCE(c.impressions, 0)";
+	const prevImpr = "COALESCE(p.impressions, 0)";
+	switch (movers) {
+		case "improving": return {
+			where: `${curClicks} > ${prevClicks}`,
+			order: `(${curClicks} - ${prevClicks}) DESC`
+		};
+		case "declining": return {
+			where: `${curClicks} < ${prevClicks}`,
+			order: `(${curClicks} - ${prevClicks}) ASC`
+		};
+		case "new": return {
+			where: `${prevImpr} = 0 AND ${curImpr} > 0`,
+			order: `${curClicks} DESC, ${curImpr} DESC`
+		};
+		case "lost": return {
+			where: `${curImpr} = 0 AND ${prevImpr} > 0`,
+			order: `${prevImpr} DESC`
+		};
+		default: throw new Error(`[archetype-sql] unknown movers mode: ${movers}`);
+	}
+}
+function facetPredicate(query, table) {
+	const facets = query.facets;
+	if (!facets?.length) return {
+		sql: "",
+		params: []
+	};
+	const parts = [];
+	const params = [];
+	for (const f of facets) {
+		const col = dimExpr(f.column, table);
+		switch (f.op) {
+			case "eq":
+				parts.push(`${col} = ?`);
+				params.push(f.value);
+				break;
+			case "regex":
+				parts.push(`regexp_matches(LOWER(${col}), ?)`);
+				params.push(f.value);
+				break;
+			case "notRegex":
+				parts.push(`NOT regexp_matches(LOWER(${col}), ?)`);
+				params.push(f.value);
+				break;
+			default: throw new Error(`[archetype-sql] unknown facet op: ${f.op}`);
+		}
+	}
+	return {
+		sql: parts.length ? ` AND ${parts.join(" AND ")}` : "",
+		params
+	};
+}
+function compileArchetypeSql(query) {
+	switch (query.archetype) {
+		case "site-daily-timeseries": {
+			const table = "dates";
+			const where = rangePredicate(query);
+			return {
+				table,
+				sql: `SELECT date, ${query.metrics.map((m) => `${metricExpr(m)} AS ${m}`).join(", ")} FROM ${table} WHERE ${where.sql} GROUP BY date ORDER BY date`,
+				params: where.params
+			};
+		}
+		case "entity-daily-timeseries": {
+			const table = tableForDimensions([query.entity.dimension]);
+			const col = dimExpr(query.entity.dimension, table);
+			const where = rangePredicate(query);
+			return {
+				table,
+				sql: `SELECT date, ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql} AND ${col} = ? GROUP BY date ORDER BY date`,
+				params: [...where.params, query.entity.value]
+			};
+		}
+		case "entity-daily-sparkline": {
+			const table = tableForDimensions([query.dimension]);
+			const col = dimExpr(query.dimension, table);
+			const where = rangePredicate(query);
+			if (query.entities.length === 0) throw new Error("[archetype-sql] entity-daily-sparkline requires resolved entities");
+			const placeholders = query.entities.map(() => "?").join(", ");
+			return {
+				table,
+				sql: `SELECT ${col} AS entity, date, ${metricExpr(query.metric)} AS ${query.metric} FROM ${table} WHERE ${where.sql} AND ${col} IN (${placeholders}) GROUP BY ${col}, date ORDER BY ${col}, date`,
+				params: [...where.params, ...query.entities]
+			};
+		}
+		case "top-n-breakdown": {
+			const table = tableForTopNBreakdown(query);
+			const where = rangePredicate(query);
+			const cmp = compareRangePredicate(query);
+			const dir = query.orderBy.dir === "asc" ? "ASC" : "DESC";
+			const compareOrder = `COALESCE(c.${query.orderBy.metric}, 0) ${dir}`;
+			const metricList = query.metrics.includes(query.orderBy.metric) ? query.metrics : [...query.metrics, query.orderBy.metric];
+			const variantSel = query.dimension === "queryCanonical" ? ", COUNT(DISTINCT query) AS variantCount" : "";
+			if (query.dimension === "device") {
+				if (cmp) {
+					const curCols = metricList.map((m) => coalesceMetric(m, "c", m)).join(", ");
+					const prevCols = STD_METRICS.map((m) => coalesceMetric(m, "p", prevAlias(m))).join(", ");
+					let sql = `WITH cur AS (${deviceUnpivotSql(metricList, where.sql, false)}), prev AS (${deviceUnpivotSql(STD_METRICS, cmp.sql, false)}) SELECT COALESCE(c.device, p.device) AS device, ${curCols}, ${prevCols} FROM cur c FULL OUTER JOIN prev p ON c.device = p.device ORDER BY ${compareOrder} LIMIT ?`;
+					const params = [
+						...where.params,
+						...where.params,
+						...where.params,
+						...cmp.params,
+						...cmp.params,
+						...cmp.params,
+						query.limit
+					];
+					if (query.offset && query.offset > 0) {
+						sql += " OFFSET ?";
+						params.push(query.offset);
+					}
+					return {
+						table,
+						sql,
+						params
+					};
+				}
+				let sql = `SELECT device, ${metricList.join(", ")} FROM (${deviceUnpivotSql(metricList, where.sql, false)}) ORDER BY ${query.orderBy.metric} ${dir} LIMIT ?`;
+				const params = [
+					...where.params,
+					...where.params,
+					...where.params,
+					query.limit
+				];
+				if (query.offset && query.offset > 0) {
+					sql += " OFFSET ?";
+					params.push(query.offset);
+				}
+				return {
+					table,
+					sql,
+					params
+				};
+			}
+			const col = dimExpr(query.dimension, table);
+			const facet = facetPredicate(query, table);
+			const totalCol = query.includeTotal ? ", COUNT(*) OVER() AS __total" : "";
+			if (cmp) {
+				const curCols = metricList.map((m) => coalesceMetric(m, "c", m)).join(", ");
+				const prevCols = STD_METRICS.map((m) => coalesceMetric(m, "p", prevAlias(m))).join(", ");
+				const variantOut = query.dimension === "queryCanonical" ? ", c.variantCount AS variantCount" : "";
+				const mover = query.movers ? moverClause(query.movers) : null;
+				const moverWhere = mover ? `WHERE ${mover.where} ` : "";
+				const orderSql = mover ? mover.order : compareOrder;
+				let sql = `WITH cur AS (SELECT ${col} AS k, ${metricSelectList(metricList)}${variantSel} FROM ${table} WHERE ${where.sql}${facet.sql} GROUP BY ${col}), prev AS (SELECT ${col} AS k, ${metricSelectList(STD_METRICS)} FROM ${table} WHERE ${cmp.sql}${facet.sql} GROUP BY ${col}) SELECT COALESCE(c.k, p.k) AS ${query.dimension}, ${curCols}, ${prevCols}${variantOut}${totalCol} FROM cur c FULL OUTER JOIN prev p ON c.k = p.k ${moverWhere}ORDER BY ${orderSql} LIMIT ?`;
+				const params = [
+					...where.params,
+					...facet.params,
+					...cmp.params,
+					...facet.params,
+					query.limit
+				];
+				if (query.offset && query.offset > 0) {
+					sql += " OFFSET ?";
+					params.push(query.offset);
+				}
+				return {
+					table,
+					sql,
+					params
+				};
+			}
+			let sql = `SELECT ${col} AS ${query.dimension}, ${metricSelectList(query.metrics)}${variantSel}${totalCol} FROM ${table} WHERE ${where.sql}${facet.sql} GROUP BY ${col} ORDER BY ${query.orderBy.metric} ${dir} LIMIT ?`;
+			const params = [
+				...where.params,
+				...facet.params,
+				query.limit
+			];
+			if (query.offset && query.offset > 0) {
+				sql += " OFFSET ?";
+				params.push(query.offset);
+			}
+			return {
+				table,
+				sql,
+				params
+			};
+		}
+		case "single-row-lookup": {
+			const table = tableForDimensions(Object.keys(query.match));
+			const where = rangePredicate(query);
+			const matchParts = [];
+			const matchParams = [];
+			for (const [dim, value] of Object.entries(query.match)) {
+				const col = dimExpr(dim, table);
+				if (!col) throw new Error(`[archetype-sql] single-row-lookup: unknown dimension ${dim}`);
+				matchParts.push(`${col} = ?`);
+				matchParams.push(value);
+			}
+			const matchSql = matchParts.length ? ` AND ${matchParts.join(" AND ")}` : "";
+			return {
+				table,
+				sql: `SELECT ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql}${matchSql}`,
+				params: [...where.params, ...matchParams]
+			};
+		}
+		case "multi-series-stacked-daily": {
+			const table = tableForDimensions([query.seriesDimension]);
+			const where = rangePredicate(query);
+			if (query.seriesDimension === "device") return {
+				table,
+				sql: `SELECT date, device, ${query.metric} FROM (${deviceUnpivotSql([query.metric], where.sql, true)}) ORDER BY date, device`,
+				params: [
+					...where.params,
+					...where.params,
+					...where.params
+				]
+			};
+			const col = dimExpr(query.seriesDimension, table);
+			return {
+				table,
+				sql: `SELECT date, ${col} AS ${query.seriesDimension}, ${metricExpr(query.metric)} AS ${query.metric} FROM ${table} WHERE ${where.sql} GROUP BY date, ${col} ORDER BY date, ${col}`,
+				params: where.params
+			};
+		}
+		case "two-dimension-detail": {
+			const table = "page_queries";
+			const where = rangePredicate(query);
+			const facet = facetPredicate(query, table);
+			const filterParts = [];
+			const filterParams = [];
+			if (query.filter?.page) {
+				filterParts.push("url = ?");
+				filterParams.push(query.filter.page);
+			}
+			if (query.filter?.query) {
+				filterParts.push("query = ?");
+				filterParams.push(query.filter.query);
+			}
+			const filterSql = filterParts.length ? ` AND ${filterParts.join(" AND ")}` : "";
+			let sql = `SELECT url AS page, query, ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql}${filterSql}${facet.sql} GROUP BY url, query`;
+			const params = [
+				...where.params,
+				...filterParams,
+				...facet.params
+			];
+			if (query.orderBy) {
+				const dir = query.orderBy.dir === "asc" ? "ASC" : "DESC";
+				sql += ` ORDER BY ${query.orderBy.metric} ${dir}`;
+			}
+			if (typeof query.limit === "number") {
+				sql += " LIMIT ?";
+				params.push(query.limit);
+			}
+			return {
+				table,
+				sql,
+				params
+			};
+		}
+		case "arbitrary-sql": return {
+			table: "page_queries",
+			sql: query.sql,
+			params: [...query.params ?? []]
+		};
+		case "aux-cloud-only": throw new Error("[archetype-sql] aux-cloud-only is not an Iceberg query — route to the cloud endpoint");
+		default: throw new Error(`[archetype-sql] unhandled archetype: ${query.archetype}`);
+	}
+}
+function tableForArchetype(query) {
+	if (query.archetype === "aux-cloud-only") return null;
+	return compileArchetypeSql(query).table;
+}
+export { compileArchetypeSql, tableForArchetype };

package/dist/drizzle-adapter/client.d.mts

@@ -0,0 +1,9 @@
+import { AsyncDuckDB, AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
+interface DuckDBWasmClient {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  query: (sql: string, params?: unknown[]) => Promise<Record<string, unknown>[]>;
+  close: () => Promise<void>;
+}
+declare function createClient(db: AsyncDuckDB, conn: AsyncDuckDBConnection): Promise<DuckDBWasmClient>;
+export { DuckDBWasmClient, createClient };

package/dist/drizzle-adapter/client.mjs

@@ -0,0 +1,20 @@
+import { arrowToRows } from "@gscdump/engine/arrow";
+async function createClient(db, conn) {
+	return {
+		db,
+		conn,
+		async query(sql, params = []) {
+			if (params.length === 0) return arrowToRows(await conn.query(sql));
+			const stmt = await conn.prepare(sql);
+			try {
+				return arrowToRows(await stmt.query(...params));
+			} finally {
+				await stmt.close();
+			}
+		},
+		async close() {
+			await conn.close();
+		}
+	};
+}
+export { createClient };

package/dist/drizzle-adapter/driver.d.mts

@@ -0,0 +1,14 @@
+import { DuckDBWasmClient } from "./client.mjs";
+import { DuckDBWasmQueryResultHKT } from "./session.mjs";
+import { DrizzleConfig, entityKind } from "drizzle-orm";
+import { PgAsyncDatabase } from "drizzle-orm/pg-core";
+import { AnyRelations, EmptyRelations, ExtractTablesWithRelations, Schema } from "drizzle-orm/relations";
+type SchemaRelations<TSchema extends Schema> = ExtractTablesWithRelations<Record<string, never>, TSchema>;
+declare class DuckDBWasmDatabase<TRelations extends AnyRelations = EmptyRelations> extends PgAsyncDatabase<DuckDBWasmQueryResultHKT, TRelations> {
+  static readonly [entityKind]: string;
+}
+interface DuckDBWasmDrizzleDatabase<TSchema extends Schema = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>> extends DuckDBWasmDatabase<TRelations> {
+  $client: Promise<DuckDBWasmClient>;
+}
+declare function drizzle<TSchema extends Schema = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>>(client: Promise<DuckDBWasmClient> | DuckDBWasmClient, config?: DrizzleConfig<TSchema, TRelations>): DuckDBWasmDrizzleDatabase<TSchema, TRelations>;
+export { DuckDBWasmDatabase, DuckDBWasmDrizzleDatabase, drizzle };

package/dist/drizzle-adapter/driver.mjs

@@ -0,0 +1,21 @@
+import { DuckDBWasmSession } from "./session.mjs";
+import { DefaultLogger, entityKind } from "drizzle-orm";
+import { PgAsyncDatabase, PgDialect } from "drizzle-orm/pg-core";
+import { buildRelations } from "drizzle-orm/relations";
+var DuckDBWasmDatabase = class extends PgAsyncDatabase {
+	static [entityKind] = "DuckDBWasmDatabase";
+};
+function drizzle(client, config = {}) {
+	const dialect = new PgDialect();
+	const clientPromise = Promise.resolve(client);
+	let logger;
+	if (config.logger === true) logger = new DefaultLogger();
+	else if (config.logger !== false) logger = config.logger;
+	const db = new DuckDBWasmDatabase(dialect, new DuckDBWasmSession(clientPromise, dialect, {
+		logger,
+		cache: config.cache
+	}), config.relations ?? (config.schema ? buildRelations(config.schema, {}) : {}));
+	db.$client = clientPromise;
+	return db;
+}
+export { DuckDBWasmDatabase, drizzle };

package/dist/drizzle-adapter/index.d.mts

@@ -0,0 +1,3 @@
+import { DuckDBWasmClient, createClient } from "./client.mjs";
+import { DuckDBWasmDatabase, DuckDBWasmDrizzleDatabase, drizzle } from "./driver.mjs";
+export { type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, createClient, drizzle };

package/dist/drizzle-adapter/index.mjs

@@ -0,0 +1,3 @@
+import { createClient } from "./client.mjs";
+import { DuckDBWasmDatabase, drizzle } from "./driver.mjs";
+export { DuckDBWasmDatabase, createClient, drizzle };

package/dist/drizzle-adapter/session.d.mts

@@ -0,0 +1,8 @@
+import "./client.mjs";
+import { Assume, entityKind } from "drizzle-orm";
+import { PgAsyncPreparedQuery, PgAsyncSession, PgDialect, PgQueryResultHKT } from "drizzle-orm/pg-core";
+type Row = Record<string, unknown>;
+interface DuckDBWasmQueryResultHKT extends PgQueryResultHKT {
+  type: Assume<this['row'], Row>[];
+}
+export { DuckDBWasmQueryResultHKT, Row };

package/dist/drizzle-adapter/session.mjs

@@ -0,0 +1,28 @@
+import { NoopLogger, entityKind } from "drizzle-orm";
+import { PgAsyncPreparedQuery, PgAsyncSession } from "drizzle-orm/pg-core";
+var DuckDBWasmSession = class extends PgAsyncSession {
+	client;
+	options;
+	static [entityKind] = "DuckDBWasmSession";
+	logger;
+	cache;
+	constructor(client, dialect, options = {}) {
+		super(dialect);
+		this.client = client;
+		this.options = options;
+		this.logger = options.logger ?? new NoopLogger();
+		this.cache = options.cache;
+	}
+	prepareQuery(query, mode, _name, mapper, queryMetadata, cacheConfig) {
+		const client = this.client;
+		const executor = async (params = []) => {
+			const rows = await (await client).query(query.sql, params);
+			return mode === "arrays" ? rows.map((row) => Object.values(row)) : rows;
+		};
+		return new PgAsyncPreparedQuery(executor, query, mapper, mode, this.logger, this.cache, queryMetadata, cacheConfig);
+	}
+	transaction() {
+		throw new Error("Transactions are not supported by the DuckDB-WASM drizzle adapter. The analytics workload is read-only; if transactions become necessary, implement PgAsyncSession.transaction() in @gscdump/engine-duckdb-wasm.");
+	}
+};
+export { DuckDBWasmSession };