@gscdump/cloudflare 0.32.12 → 0.33.0

package/dist/server-tail/index.d.mts

@@ -8,6 +8,8 @@ interface ArchetypeSqlPlan {
   params: unknown[];
   table: ArchetypeFactTable;
 }
+type PartitionPredicateMode = 'bare' | 'r2-sql-concat';
+type PartitionKeyEncoding = 'int' | 'string';
 interface BuildArchetypeSqlOptions {
   /**
    * Set by the DuckDB file-list executor, which reads raw Iceberg parquet
@@ -25,6 +27,14 @@ interface BuildArchetypeSqlOptions {
    * virtual columns and needs the full predicate.
    */
   partitionPruned?: boolean;
+  /**
+   * Int-partition catalogs are the default and use bare equality. Legacy
+   * string-partition catalogs can request CONCAT-wrapped predicates directly
+   * instead of post-processing generated SQL.
+   */
+  partitionPredicateMode?: PartitionPredicateMode;
+  /** Preferred input for new callers. Defaults to `'int'`. */
+  partitionKeyEncoding?: PartitionKeyEncoding;
 }
 declare function buildArchetypeSql(query: ArchetypeQuery, opts?: BuildArchetypeSqlOptions): ArchetypeSqlPlan;
 /** Row returned by the DuckDB sibling. */
@@ -132,6 +142,14 @@ interface R2SqlClientConfig {
   fetchImpl?: typeof fetch;
   /** Per-query wall-clock deadline (ms). Default 25s — under the Worker CPU budget. */
   timeoutMs?: number;
+  /** Partition-key encoding of the target catalog. Defaults to `'int'`. */
+  partitionKeyEncoding?: PartitionKeyEncoding;
+  /**
+   * Host-owned mapping from public site id to the INT `site_id` partition
+   * value. Required for non-numeric public ids when `partitionKeyEncoding` is
+   * `'int'`.
+   */
+  partitionSiteId?: (siteId: string) => string | number;
 }
 /** A row as returned by R2 SQL — flat dimension + metric values. */
 type R2SqlRow = Record<string, string | number | null>;

package/dist/server-tail/index.mjs

@@ -1,12 +1,17 @@
 import { bindLiterals } from "@gscdump/engine";
 import { ARCHETYPE_EXECUTION_CLASS } from "@gscdump/contracts/archetypes";
 import { err, ok, unwrapResult } from "gscdump/result";
+import { SEARCH_TYPE_INT } from "@gscdump/engine/iceberg";
 const TABLE_PLACEHOLDER = "{{TABLE}}";
 function dimColumn(dim) {
 	if (dim === "page") return "url";
-	if (dim === "queryCanonical") return "query_canonical";
+	if (dim === "queryCanonical") return "COALESCE((SELECT qd.query_canonical FROM query_dim qd WHERE qd.query = query LIMIT 1), query)";
 	return dim;
 }
+function dimSelect(dim) {
+	const col = dimColumn(dim);
+	return dim === "queryCanonical" ? `${col} AS queryCanonical` : col;
+}
 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";
@@ -84,13 +89,13 @@ function moverClause(movers) {
 function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
-function partitionWhere(q, partitionPruned = false) {
+function partitionWhere(q, partitionPruned = false, mode = "bare") {
 	if (partitionPruned) return {
 		clause: "date BETWEEN ? AND ?",
 		params: [q.range.start, q.range.end]
 	};
 	return {
-		clause: "site_id = ? AND search_type = ? AND date BETWEEN ? AND ?",
+		clause: `${mode === "r2-sql-concat" ? "CONCAT(site_id, '')" : "site_id"} = ? AND ${mode === "r2-sql-concat" ? "CONCAT(search_type, '')" : "search_type"} = ? AND date BETWEEN ? AND ?`,
 		params: [
 			q.siteId,
 			q.searchType,
@@ -130,8 +135,8 @@ function facetPredicate(query) {
 		params
 	};
 }
-function buildSiteDailyTimeseries(q, pruned) {
-	const w = partitionWhere(q, pruned);
+function buildSiteDailyTimeseries(q, pruned, mode) {
+	const w = partitionWhere(q, pruned, mode);
 	const metrics = q.metrics.map(metricExpr).join(", ");
 	return {
 		table: "dates",
@@ -139,9 +144,9 @@ function buildSiteDailyTimeseries(q, pruned) {
 		sql: `SELECT date, ${metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY date ORDER BY date ASC`
 	};
 }
-function buildEntityDailyTimeseries(q, pruned) {
+function buildEntityDailyTimeseries(q, pruned, mode) {
 	const table = tableForDimensions([q.entity.dimension]);
-	const w = partitionWhere(q, pruned);
+	const w = partitionWhere(q, pruned, mode);
 	const col = dimColumn(q.entity.dimension);
 	const metrics = q.metrics.map(metricExpr).join(", ");
 	return {
@@ -150,21 +155,21 @@ function buildEntityDailyTimeseries(q, pruned) {
 		sql: `SELECT date, ${metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} AND ${col} = ? GROUP BY date ORDER BY date ASC`
 	};
 }
-function buildEntityDailySparkline(q, pruned) {
+function buildEntityDailySparkline(q, pruned, mode) {
 	const table = tableForDimensions([q.dimension]);
-	const w = partitionWhere(q, pruned);
+	const w = partitionWhere(q, pruned, mode);
 	const col = dimColumn(q.dimension);
 	if (q.entities.length === 0) throw new Error("entity-daily-sparkline: empty entities - resolver must pre-resolve the top-N list");
 	const inList = q.entities.map(sqlStringLiteral).join(", ");
 	return {
 		table,
 		params: w.params,
-		sql: `SELECT date, ${col}, ${metricExpr(q.metric)} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} AND ${col} IN (${inList}) GROUP BY date, ${col} ORDER BY date ASC`
+		sql: `SELECT date, ${dimSelect(q.dimension)}, ${metricExpr(q.metric)} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} AND ${col} IN (${inList}) GROUP BY date, ${col} ORDER BY date ASC`
 	};
 }
-function buildTopNBreakdown(q, pruned) {
+function buildTopNBreakdown(q, pruned, mode) {
 	const table = tableForDimensions([q.dimension]);
-	const w = partitionWhere(q, pruned);
+	const w = partitionWhere(q, pruned, mode);
 	const order = `${q.orderBy.metric} ${q.orderBy.dir.toUpperCase()}`;
 	const limit = `LIMIT ${Math.max(0, Math.floor(q.limit))}`;
 	const offset = q.offset && q.offset > 0 ? ` OFFSET ${Math.floor(q.offset)}` : "";
@@ -175,7 +180,7 @@ function buildTopNBreakdown(q, pruned) {
 			const wPrev = partitionWhere({
 				...q,
 				range: q.compareRange
-			}, pruned);
+			}, pruned, mode);
 			const deviceSelects = (clause, ml) => DEVICE_SUFFIXES.map((suffix) => {
 				const source = deviceSource(suffix);
 				const metrics = ml.map((m) => metricExprForSource(m, source)).join(", ");
@@ -208,7 +213,7 @@ function buildTopNBreakdown(q, pruned) {
 		const wPrev = partitionWhere({
 			...q,
 			range: q.compareRange
-		}, pruned);
+		}, pruned, mode);
 		const curMetrics = metricList.map(metricExpr).join(", ");
 		const prevMetrics = STD_METRICS.map((m) => metricExpr(m)).join(", ");
 		const curCols = metricList.map((m) => coalesceMetric(m, "c", m)).join(", ");
@@ -229,17 +234,18 @@ function buildTopNBreakdown(q, pruned) {
 			sql
 		};
 	}
-	const sql = `SELECT ${col}, ${metricList.map(metricExpr).join(", ")}${variantSel}${totalCol} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause}${facet.sql} GROUP BY ${col} ORDER BY ${order} ${limit}${offset}`;
+	const metrics = metricList.map(metricExpr).join(", ");
+	const sql = `SELECT ${dimSelect(q.dimension)}, ${metrics}${variantSel}${totalCol} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause}${facet.sql} GROUP BY ${col} ORDER BY ${order} ${limit}${offset}`;
 	return {
 		table,
 		params: [...w.params, ...facet.params],
 		sql
 	};
 }
-function buildSingleRowLookup(q, pruned) {
+function buildSingleRowLookup(q, pruned, mode) {
 	const dims = Object.keys(q.match);
 	const table = tableForDimensions(dims);
-	const w = partitionWhere(q, pruned);
+	const w = partitionWhere(q, pruned, mode);
 	const params = [...w.params];
 	let clause = w.clause;
 	for (const dim of dims) {
@@ -251,12 +257,12 @@ function buildSingleRowLookup(q, pruned) {
 	return {
 		table,
 		params,
-		sql: `SELECT ${dims.length > 0 ? `${dims.map(dimColumn).join(", ")}, ${metrics}` : metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${clause}${groupBy}`
+		sql: `SELECT ${dims.length > 0 ? `${dims.map(dimSelect).join(", ")}, ${metrics}` : metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${clause}${groupBy}`
 	};
 }
-function buildMultiSeriesStackedDaily(q, pruned) {
+function buildMultiSeriesStackedDaily(q, pruned, mode) {
 	const table = tableForDimensions([q.seriesDimension]);
-	const w = partitionWhere(q, pruned);
+	const w = partitionWhere(q, pruned, mode);
 	if (q.seriesDimension === "device") {
 		const selects = DEVICE_SUFFIXES.map((suffix) => {
 			const source = deviceSource(suffix);
@@ -272,11 +278,11 @@ function buildMultiSeriesStackedDaily(q, pruned) {
 	return {
 		table,
 		params: w.params,
-		sql: `SELECT date, ${col}, ${metricExpr(q.metric)} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY date, ${col} ORDER BY date ASC`
+		sql: `SELECT date, ${dimSelect(q.seriesDimension)}, ${metricExpr(q.metric)} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY date, ${col} ORDER BY date ASC`
 	};
 }
-function buildTwoDimensionDetail(q, pruned) {
-	const w = partitionWhere(q, pruned);
+function buildTwoDimensionDetail(q, pruned, mode) {
+	const w = partitionWhere(q, pruned, mode);
 	const params = [...w.params];
 	let clause = w.clause;
 	if (q.filter?.page) {
@@ -301,14 +307,15 @@ function buildTwoDimensionDetail(q, pruned) {
 }
 function buildArchetypeSql(query, opts = {}) {
 	const pruned = opts.partitionPruned ?? false;
+	const mode = opts.partitionPredicateMode ?? (opts.partitionKeyEncoding === "string" ? "r2-sql-concat" : "bare");
 	switch (query.archetype) {
-		case "site-daily-timeseries": return buildSiteDailyTimeseries(query, pruned);
-		case "entity-daily-timeseries": return buildEntityDailyTimeseries(query, pruned);
-		case "entity-daily-sparkline": return buildEntityDailySparkline(query, pruned);
-		case "top-n-breakdown": return buildTopNBreakdown(query, pruned);
-		case "single-row-lookup": return buildSingleRowLookup(query, pruned);
-		case "multi-series-stacked-daily": return buildMultiSeriesStackedDaily(query, pruned);
-		case "two-dimension-detail": return buildTwoDimensionDetail(query, pruned);
+		case "site-daily-timeseries": return buildSiteDailyTimeseries(query, pruned, mode);
+		case "entity-daily-timeseries": return buildEntityDailyTimeseries(query, pruned, mode);
+		case "entity-daily-sparkline": return buildEntityDailySparkline(query, pruned, mode);
+		case "top-n-breakdown": return buildTopNBreakdown(query, pruned, mode);
+		case "single-row-lookup": return buildSingleRowLookup(query, pruned, mode);
+		case "multi-series-stacked-daily": return buildMultiSeriesStackedDaily(query, pruned, mode);
+		case "two-dimension-detail": return buildTwoDimensionDetail(query, pruned, mode);
 		case "arbitrary-sql": throw new Error("buildArchetypeSql: arbitrary-sql carries caller SQL - the DuckDB executor runs it verbatim");
 		case "aux-cloud-only": throw new Error("buildArchetypeSql: aux-cloud-only is not an Iceberg query");
 	}
@@ -319,6 +326,9 @@ var ServerTailRoutingError = class extends Error {
 function routingErrorToException(error) {
 	return error;
 }
+function hasRegexFacet(query) {
+	return query.facets?.some((f) => f.op === "regex" || f.op === "notRegex") ?? false;
+}
 function resolveServerTailEngineResult(query) {
 	const cls = ARCHETYPE_EXECUTION_CLASS[query.archetype];
 	if (cls === "cloud-only") return err(new ServerTailRoutingError(`archetype '${query.archetype}' is cloud-only — not a server-tail query`));
@@ -327,8 +337,7 @@ function resolveServerTailEngineResult(query) {
 	if (query.archetype === "top-n-breakdown" && query.includeTotal) return ok("duckdb");
 	if (query.archetype === "top-n-breakdown" && query.compareRange) return ok("duckdb");
 	if (query.archetype === "top-n-breakdown" && query.dimension === "queryCanonical") return ok("duckdb");
-	const facets = query.facets;
-	if (facets && facets.length > 0) return ok("duckdb");
+	if (hasRegexFacet(query)) return ok("duckdb");
 	return ok("r2-sql");
 }
 function resolveServerTailEngine(query) {
@@ -534,10 +543,28 @@ function normalizeRows(result) {
 	}
 	return [];
 }
+function coerceIntSiteId(siteId, mapper) {
+	const mapped = mapper ? mapper(siteId) : siteId;
+	const n = Number(mapped);
+	if (!Number.isSafeInteger(n)) throw new R2SqlError("int R2 SQL catalog requires a numeric site_id partition value; pass partitionSiteId for public ids");
+	return n;
+}
+function withEncodedPartitions(query, encoding, siteIdMapper) {
+	if (encoding === "string") return query;
+	const scoped = query;
+	const searchType = SEARCH_TYPE_INT[scoped.searchType];
+	if (searchType === void 0) throw new R2SqlError(`unknown search_type for int R2 SQL catalog: ${String(scoped.searchType)}`);
+	return {
+		...query,
+		siteId: coerceIntSiteId(scoped.siteId, siteIdMapper),
+		searchType
+	};
+}
 function createR2SqlClient(config) {
 	const fetchImpl = config.fetchImpl ?? globalThis.fetch;
 	const apiBase = config.apiBase ?? DEFAULT_API_BASE;
 	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const partitionKeyEncoding = config.partitionKeyEncoding ?? "int";
 	const endpoint = `${apiBase}/accounts/${config.accountId}/r2-sql/query/${config.bucket}`;
 	async function queryResult(sql) {
 		const started = Date.now();
@@ -576,12 +603,16 @@ function createR2SqlClient(config) {
 	async function query(sql) {
 		return unwrapResult(await queryResult(sql), r2SqlErrorToException);
 	}
-	function runPlan(plan) {
+	function materializePlan(plan) {
 		const tableRef = r2TableRef(config.namespace, plan.table);
-		return query(workaroundPartitionEquality(inlineParams(plan.sql.split(TABLE_PLACEHOLDER).join(tableRef), plan.params)));
+		return inlineParams(plan.sql.split(TABLE_PLACEHOLDER).join(tableRef), plan.params);
+	}
+	function runPlan(plan) {
+		const sql = materializePlan(plan);
+		return query(partitionKeyEncoding === "string" ? workaroundPartitionEquality(sql) : sql);
 	}
 	function runArchetype(archetypeQuery) {
-		return runPlan(buildArchetypeSql(archetypeQuery));
+		return query(materializePlan(buildArchetypeSql(withEncodedPartitions(archetypeQuery, partitionKeyEncoding, config.partitionSiteId), { partitionKeyEncoding })));
 	}
 	return {
 		query,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cloudflare",
   "type": "module",
-  "version": "0.32.12",
+  "version": "0.33.0",
   "description": "Cloudflare-Workers-flavored helpers for the gscdump analytics stack: AnalyticsEnv binding contract, R2 SigV4 presigner, size-hint HMAC, DuckDB Workers shims, engine factory.",
   "author": {
     "name": "Harlan Wilton",
@@ -46,10 +46,10 @@
   "dependencies": {
     "@uwdata/flechette": "^2.5.0",
     "aws4fetch": "^1.0.20",
-    "@gscdump/engine-sqlite": "0.32.12",
-    "@gscdump/engine": "0.32.12",
-    "gscdump": "0.32.12",
-    "@gscdump/contracts": "0.32.12"
+    "@gscdump/contracts": "0.33.0",
+    "@gscdump/engine": "0.33.0",
+    "@gscdump/engine-sqlite": "0.33.0",
+    "gscdump": "0.33.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.16.20",