@gscdump/engine 0.31.8 → 0.31.9

package/dist/rollups.d.mts

@@ -364,6 +364,34 @@ declare const queryCanonicalVariantsRollup: RollupDef;
  * `RunOptimizedQueryOptions.canonicalSource`).
  */
 declare const queryCanonicalDailyRollup: RollupDef;
+/**
+ * Resumable, cross-invocation build of `query_canonical_daily` for a high-
+ * cardinality site whose full windowed build exceeds one job reservation (300s).
+ *
+ * Each call builds the day-capped windows from `windowOffset` until `deadlineMs`,
+ * writes that batch's rows to a STAGING partial parquet (windows are disjoint by
+ * date, so partials never overlap), and returns `{ done:false, nextWindowOffset }`
+ * for the caller to re-enqueue. When the last window is built it MERGES every
+ * staging partial into the canonical `query_canonical_daily` parquet + envelope
+ * (the read path is unchanged — still one rollup file) and deletes the staging,
+ * returning `{ done:true }`. `builtAt` MUST be stable across the continuation chain
+ * (it versions both the staging keys and the final rollup key).
+ */
+declare function rebuildCanonicalDailyResumable(opts: {
+  engine: RollupEngine;
+  ctx: TenantCtx;
+  dataSource: DataSource;
+  searchType?: SearchType;
+  builtAt: number;
+  windowOffset: number;
+  deadlineMs: number;
+}): Promise<{
+  done: boolean;
+  nextWindowOffset: number;
+  windowsTotal: number;
+  windowsBuilt: number;
+  rowsWritten: number;
+}>;
 /**
  * Aggregates the per-URL Indexing API metadata entity store (populated by
  * `gscdump entities indexing snapshot`) into daily counts of `URL_UPDATED`
@@ -449,4 +477,4 @@ declare const DEFAULT_ROLLUPS: readonly RollupDef[];
  * (CLI: `gscdump rollups --with-canonical`).
  */
 declare const CANONICAL_ROLLUPS: readonly RollupDef[];
-export { CANONICAL_ROLLUPS, DAILY_MAX_WINDOW_DAYS, DEFAULT_ROLLUPS, ParquetRollupPointer, ROLLUP_PAGE_ROWS, ROLLUP_PAGE_ROWS_DAILY, ROLLUP_PAGE_ROWS_WIDE, RebuildDailyFromHourlyOptions, RebuildRollupResult, RebuildRollupsOptions, RollupBucket, RollupCtx, RollupDef, RollupEngine, RollupEnvelope, WINDOW_BYTE_BUDGET, dailyTotalsRollup, indexPercentRollup, indexingHealthRollup, indexingMetadataRollup, partitionDaySpan, partitionsInRange, planRollupWindows, queryCanonicalDailyRollup, queryCanonicalVariantsRollup, readLatestRollup, rebuildDailyFromHourly, rebuildRollups, rollupKey, rollupParquetKey, runWindowed, sitemapChanges28dRollup, sitemapHealthRollup, topCountries28dRollup, topKeywords28dParquetRollup, topKeywords28dRollup, topPages28dRollup, weeklyTotalsRollup };
+export { CANONICAL_ROLLUPS, DAILY_MAX_WINDOW_DAYS, DEFAULT_ROLLUPS, ParquetRollupPointer, ROLLUP_PAGE_ROWS, ROLLUP_PAGE_ROWS_DAILY, ROLLUP_PAGE_ROWS_WIDE, RebuildDailyFromHourlyOptions, RebuildRollupResult, RebuildRollupsOptions, RollupBucket, RollupCtx, RollupDef, RollupEngine, RollupEnvelope, WINDOW_BYTE_BUDGET, dailyTotalsRollup, indexPercentRollup, indexingHealthRollup, indexingMetadataRollup, partitionDaySpan, partitionsInRange, planRollupWindows, queryCanonicalDailyRollup, queryCanonicalVariantsRollup, readLatestRollup, rebuildCanonicalDailyResumable, rebuildDailyFromHourly, rebuildRollups, rollupKey, rollupParquetKey, runWindowed, sitemapChanges28dRollup, sitemapHealthRollup, topCountries28dRollup, topKeywords28dParquetRollup, topKeywords28dRollup, topPages28dRollup, weeklyTotalsRollup };

package/dist/rollups.mjs

@@ -1,6 +1,6 @@
 import "./_chunks/layout.mjs";
 import { engineErrors } from "./errors.mjs";
-import { encodeRowsToParquetFlex } from "./adapters/hyparquet.mjs";
+import { decodeParquetToRows, encodeRowsToParquetFlex } from "./adapters/hyparquet.mjs";
 import { createIndexingMetadataStore, createQueryDimStore, createSitemapStore, inspectionParquetKey, sitemapUrlsIndexPrefix } from "./_chunks/entities.mjs";
 import { MS_PER_DAY } from "gscdump";
 function rollupPrefix(ctx, searchType) {
@@ -713,37 +713,135 @@ const queryCanonicalDailyRollup = {
 				pageRows: ROLLUP_PAGE_ROWS_DAILY
 			},
 			maxWindowDays: 7,
-			sqlFor: useDim ? (w) => `
-          SELECT
-            ${canonExpr} AS query_canonical,
-            CAST(q.date AS VARCHAR) AS date,
-            SUM(q.clicks)::BIGINT AS clicks,
-            SUM(q.impressions)::BIGINT AS impressions,
-            SUM(q.sum_position)::DOUBLE AS sum_position
-          FROM read_parquet({{FILES}}, union_by_name = true) q
-          LEFT JOIN read_parquet({{QUERY_DIM}}, union_by_name = true) qd ON q.query = qd.query
-          WHERE q.date >= '${w.start}' AND q.date <= '${w.end}'
-          GROUP BY ${canonExpr}, q.date
-        ` : (w) => `
-          SELECT
-            ${canonExpr} AS query_canonical,
-            CAST(date AS VARCHAR) AS date,
-            SUM(clicks)::BIGINT AS clicks,
-            SUM(impressions)::BIGINT AS impressions,
-            SUM(sum_position)::DOUBLE AS sum_position
-          FROM read_parquet({{FILES}}, union_by_name = true)
-          WHERE date >= '${w.start}' AND date <= '${w.end}'
-          GROUP BY ${canonExpr}, date
-        `
-		})).map((r) => ({
-			query_canonical: String(r.query_canonical),
-			date: String(r.date),
-			clicks: BigInt(r.clicks),
-			impressions: BigInt(r.impressions),
-			sum_position: Number(r.sum_position)
-		}));
+			sqlFor: dailyWindowSqlFor(useDim, canonExpr)
+		})).map(mapDailyRow);
 	}
 };
+function dailyWindowSqlFor(useDim, canonExpr) {
+	return useDim ? (w) => `
+        SELECT
+          ${canonExpr} AS query_canonical,
+          CAST(q.date AS VARCHAR) AS date,
+          SUM(q.clicks)::BIGINT AS clicks,
+          SUM(q.impressions)::BIGINT AS impressions,
+          SUM(q.sum_position)::DOUBLE AS sum_position
+        FROM read_parquet({{FILES}}, union_by_name = true) q
+        LEFT JOIN read_parquet({{QUERY_DIM}}, union_by_name = true) qd ON q.query = qd.query
+        WHERE q.date >= '${w.start}' AND q.date <= '${w.end}'
+        GROUP BY ${canonExpr}, q.date
+      ` : (w) => `
+        SELECT
+          ${canonExpr} AS query_canonical,
+          CAST(date AS VARCHAR) AS date,
+          SUM(clicks)::BIGINT AS clicks,
+          SUM(impressions)::BIGINT AS impressions,
+          SUM(sum_position)::DOUBLE AS sum_position
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= '${w.start}' AND date <= '${w.end}'
+        GROUP BY ${canonExpr}, date
+      `;
+}
+function mapDailyRow(r) {
+	return {
+		query_canonical: String(r.query_canonical),
+		date: String(r.date),
+		clicks: BigInt(r.clicks),
+		impressions: BigInt(r.impressions),
+		sum_position: Number(r.sum_position)
+	};
+}
+const CANONICAL_DAILY_STAGING_STEM = "query_canonical_daily__staging";
+async function rebuildCanonicalDailyResumable(opts) {
+	const { engine, ctx, dataSource, searchType, builtAt, windowOffset, deadlineMs } = opts;
+	const sType = searchType !== void 0 ? { searchType } : {};
+	const windows = planRollupWindows((await engine.listPartitions({
+		ctx,
+		table: "queries",
+		...sType
+	})).map((p) => ({
+		partition: p.partition,
+		bytes: p.bytes
+	})), void 0, 7);
+	const windowsTotal = windows.length;
+	const dimStore = createQueryDimStore({ dataSource });
+	const useDim = await dimStore.loadMeta(ctx) !== null;
+	const canonExpr = useDim ? `COALESCE(qd.query_canonical, NULLIF(q.query_canonical, ''), q.query)` : `COALESCE(NULLIF(query_canonical, ''), query)`;
+	const extraFileSets = useDim ? { QUERY_DIM: {
+		table: "queries",
+		keys: [dimStore.parquetKey(ctx)]
+	} } : void 0;
+	const sqlFor = dailyWindowSqlFor(useDim, canonExpr);
+	const cols = queryCanonicalDailyRollup.parquetColumns;
+	const sortKey = queryCanonicalDailyRollup.parquetSortKey;
+	const batchRows = [];
+	let i = windowOffset;
+	for (; i < windowsTotal; i++) {
+		const w = windows[i];
+		const winRows = await runPagedQuery({
+			engine,
+			ctx,
+			table: "queries",
+			...sType,
+			fileSets: {
+				FILES: {
+					table: "queries",
+					partitions: w.partitions
+				},
+				...extraFileSets
+			},
+			coreSql: sqlFor(w),
+			orderBy: "date, query_canonical",
+			pageRows: ROLLUP_PAGE_ROWS_DAILY
+		});
+		for (const r of winRows) batchRows.push(mapDailyRow(r));
+		if (Date.now() > deadlineMs) {
+			i++;
+			break;
+		}
+	}
+	const nextWindowOffset = i;
+	const stagingKey = rollupParquetKey(ctx, `${CANONICAL_DAILY_STAGING_STEM}__w${windowOffset}`, builtAt, searchType);
+	await dataSource.write(stagingKey, encodeRowsToParquetFlex(batchRows, {
+		columns: cols,
+		sortKey
+	}));
+	if (nextWindowOffset < windowsTotal) return {
+		done: false,
+		nextWindowOffset,
+		windowsTotal,
+		windowsBuilt: nextWindowOffset - windowOffset,
+		rowsWritten: batchRows.length
+	};
+	const stagingPrefix = rollupParquetKey(ctx, `${CANONICAL_DAILY_STAGING_STEM}__`, builtAt, searchType).replace(/__v\d+\.parquet$/, "");
+	const stagingKeys = (await dataSource.list(stagingPrefix.replace(/[^/]*$/, ""))).filter((k) => k.includes(`${CANONICAL_DAILY_STAGING_STEM}__w`) && k.includes(`__v${builtAt}.parquet`));
+	const merged = [];
+	for (const k of stagingKeys) merged.push(...await decodeParquetToRows(await dataSource.read(k), { columns: cols.map((c) => c.name) }));
+	const parquetKey = rollupParquetKey(ctx, CANONICAL_DAILY_ROLLUP_FINAL_ID, builtAt, searchType);
+	await dataSource.write(parquetKey, encodeRowsToParquetFlex(merged, {
+		columns: cols,
+		sortKey
+	}));
+	const envelope = {
+		version: 1,
+		id: CANONICAL_DAILY_ROLLUP_FINAL_ID,
+		builtAt,
+		windowDays: queryCanonicalDailyRollup.windowDays,
+		payload: {
+			parquetKey,
+			rowCount: merged.length
+		}
+	};
+	await dataSource.write(rollupKey(ctx, CANONICAL_DAILY_ROLLUP_FINAL_ID, builtAt, searchType), new TextEncoder().encode(JSON.stringify(envelope)));
+	await dataSource.delete(stagingKeys);
+	return {
+		done: true,
+		nextWindowOffset,
+		windowsTotal,
+		windowsBuilt: nextWindowOffset - windowOffset,
+		rowsWritten: merged.length
+	};
+}
+const CANONICAL_DAILY_ROLLUP_FINAL_ID = "query_canonical_daily";
 const indexingMetadataRollup = {
 	id: "indexing_metadata",
 	windowDays: null,
@@ -1056,4 +1154,4 @@ const DEFAULT_ROLLUPS = [
 	sitemapChanges28dRollup
 ];
 const CANONICAL_ROLLUPS = [queryCanonicalVariantsRollup, queryCanonicalDailyRollup];
-export { CANONICAL_ROLLUPS, DAILY_MAX_WINDOW_DAYS, DEFAULT_ROLLUPS, ROLLUP_PAGE_ROWS, ROLLUP_PAGE_ROWS_DAILY, ROLLUP_PAGE_ROWS_WIDE, WINDOW_BYTE_BUDGET, dailyTotalsRollup, indexPercentRollup, indexingHealthRollup, indexingMetadataRollup, partitionDaySpan, partitionsInRange, planRollupWindows, queryCanonicalDailyRollup, queryCanonicalVariantsRollup, readLatestRollup, rebuildDailyFromHourly, rebuildRollups, rollupKey, rollupParquetKey, runWindowed, sitemapChanges28dRollup, sitemapHealthRollup, topCountries28dRollup, topKeywords28dParquetRollup, topKeywords28dRollup, topPages28dRollup, weeklyTotalsRollup };
+export { CANONICAL_ROLLUPS, DAILY_MAX_WINDOW_DAYS, DEFAULT_ROLLUPS, ROLLUP_PAGE_ROWS, ROLLUP_PAGE_ROWS_DAILY, ROLLUP_PAGE_ROWS_WIDE, WINDOW_BYTE_BUDGET, dailyTotalsRollup, indexPercentRollup, indexingHealthRollup, indexingMetadataRollup, partitionDaySpan, partitionsInRange, planRollupWindows, queryCanonicalDailyRollup, queryCanonicalVariantsRollup, readLatestRollup, rebuildCanonicalDailyResumable, rebuildDailyFromHourly, rebuildRollups, rollupKey, rollupParquetKey, runWindowed, sitemapChanges28dRollup, sitemapHealthRollup, topCountries28dRollup, topKeywords28dParquetRollup, topKeywords28dRollup, topPages28dRollup, weeklyTotalsRollup };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine",
   "type": "module",
-  "version": "0.31.8",
+  "version": "0.31.9",
   "description": "Append-only Parquet/DuckDB storage engine + planner + adapters for the gscdump pipeline. Node + edge runtimes; opt-in heavy peers.",
   "author": {
     "name": "Harlan Wilton",
@@ -181,8 +181,8 @@
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
     "proper-lockfile": "^4.1.2",
-    "@gscdump/contracts": "0.31.8",
-    "gscdump": "0.31.8"
+    "gscdump": "0.31.9",
+    "@gscdump/contracts": "0.31.9"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",