@gscdump/engine 5.6.0 → 5.7.1

package/dist/analysis-types.d.mts

@@ -1,3 +1,4 @@
+import { ComparisonOrderBy } from "./resolver/types.mjs";
 import { BuilderState, SearchType } from "gscdump/query";
 export type AnalysisTool = 'striking-distance' | 'opportunity' | 'movers' | 'decay' | 'zero-click' | 'brand' | 'cannibalization' | 'clustering' | 'concentration' | 'seasonality' | 'trends' | 'ctr-anomaly' | 'position-volatility' | 'long-tail' | 'intent-atlas' | 'query-migration' | 'bayesian-ctr' | 'stl-decompose' | 'change-point' | 'bipartite-pagerank' | 'survival' | 'position-distribution' | 'ctr-curve' | 'dark-traffic' | 'content-velocity' | 'keyword-breadth' | 'device-gap' | 'data-query' | 'data-detail' | 'trajectory';
 export interface AnalysisParams {
@@ -55,6 +56,8 @@ export interface AnalysisParams {
   qc?: BuilderState;
   /** data-query comparison filter applied to joined current/previous rows. */
   comparisonFilter?: 'new' | 'lost' | 'improving' | 'declining';
+  /** data-query comparison order applied to the joined rows before the row cap. */
+  comparisonOrderBy?: ComparisonOrderBy;
   /** GSC slice the analysis is scoped to. Undefined = analyzer runs cross-type (today's behaviour for web-only sites). */
   searchType?: SearchType;
 }

package/dist/analyzer/types.d.mts

@@ -1,6 +1,6 @@
 import { Row } from "../storage.mjs";
-import { AnalysisParams } from "../analysis-types.mjs";
 import { ResolverAdapter } from "../resolver/types.mjs";
+import { AnalysisParams } from "../analysis-types.mjs";
 import { FileSet, SourceCapabilities } from "../source/source-types.mjs";
 import { BuilderState } from "gscdump/query";
 /**

package/dist/resolver/compile.d.mts

@@ -1,4 +1,4 @@
-import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverOptions } from "./types.mjs";
+import { ComparisonFilter, ComparisonOrderBy, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverOptions } from "./types.mjs";
 import { BuilderState } from "gscdump/query";
 export declare function resolveToSQLOptimized<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQLOptimized;
 export declare function resolveToSQL<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQL;
@@ -6,7 +6,7 @@ export declare function buildTotalsSql<TK extends string>(state: BuilderState, o
   sql: string;
   params: unknown[];
 };
-export declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter): ResolvedComparisonSQL;
+export declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter, comparisonOrderBy?: ComparisonOrderBy): ResolvedComparisonSQL;
 /**
  * Enrich Canonical Query groups with their raw variants.
  * Supply selected keys to limit aggregation to the current page.

package/dist/resolver/compile.mjs

@@ -35,6 +35,14 @@ function orderByClause(state, prefix = "", columnOverride) {
 	}
 	return sql.raw(`ORDER BY ${prefix}clicks DESC`);
 }
+function changeOrderClause(order) {
+	if (order.column !== "clicksChange") throw new Error(`[resolver] unknown comparison order column: ${JSON.stringify(order.column)}`);
+	if (order.dir !== "asc" && order.dir !== "desc") throw new Error(`[resolver] unknown comparison order direction: ${JSON.stringify(order.dir)}`);
+	return {
+		column: sql.raw("CAST(COALESCE(c.clicks, 0) AS DOUBLE) - CAST(COALESCE(p.clicks, 0) AS DOUBLE) as \"clicksChange\""),
+		orderBy: sql.raw(`ORDER BY clicksChange ${order.dir.toUpperCase()}`)
+	};
+}
 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;
@@ -239,7 +247,7 @@ function buildTotalsSql(state, options) {
 	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) {
+function resolveComparisonSQL(current, previous, options, comparisonFilter, comparisonOrderBy) {
 	const { adapter, siteId, searchType } = options;
 	const comparisonPlan = buildComparisonPlan(current, previous, adapter.capabilities);
 	const currentScope = buildScope(current, options);
@@ -271,7 +279,8 @@ function resolveComparisonSQL(current, previous, options, comparisonFilter) {
 	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 changeOrder = comparisonOrderBy ? changeOrderClause(comparisonOrderBy) : void 0;
+	const orderSql = changeOrder?.orderBy ?? orderByClause(current, "");
 	const limitSql = limitOffsetClause(current);
 	const outerCurrentCols = [];
 	for (const d of groupByDims) {
@@ -282,6 +291,7 @@ function resolveComparisonSQL(current, previous, options, comparisonFilter) {
 	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\""));
+	if (changeOrder) outerCurrentCols.push(changeOrder.column);
 	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}`);

package/dist/resolver/index.d.mts

@@ -1,4 +1,4 @@
-import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverAdapter, ResolverOptions } from "./types.mjs";
+import { ComparisonFilter, ComparisonOrderBy, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverAdapter, ResolverOptions } from "./types.mjs";
 import { DIMENSION_SURFACES, DimensionBinding, DimensionSurface, LOGICAL_DATASETS, LogicalDataset, LogicalDatasetDefinition, UnresolvableDatasetError, assertDimensionsSupported, dimensionColumn, inferLogicalDataset, isDatasetResolvable, supportsDimensionOnSurface } from "./datasets.mjs";
 import { SqlFragments, SqlFragmentsConfig, createSqlFragments } from "./fragments.mjs";
 import { CreateResolverAdapterConfig, createResolverAdapter } from "./adapter.mjs";
@@ -9,4 +9,4 @@ import { RollupRowsReader, createRollupExtrasOverlay } from "./extras-overlay.mj
 import { dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue } from "./filter-utils.mjs";
 import { PgTableKey, R2SqlResolverAdapterOptions, ResolverAdapterOptions, createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter } from "./pg-adapter.mjs";
 import { AssertSchemaInSyncOptions, assertSchemaInSync } from "./schema-drift.mjs";
-export { type AssertSchemaInSyncOptions, type CanonicalQueryDimSource, type ComparisonFilter, type ComparisonQueryResult, type CreateResolverAdapterConfig, DIMENSION_SURFACES, type DimensionBinding, type DimensionSurface, type ExtraQuery, LOGICAL_DATASETS, type LogicalDataset, type LogicalDatasetDefinition, type OptimizedQueryResult, type PgTableKey, type PrimaryColumnarSource, QuerySourceCoverageError, type QuerySourceDecision, type QuerySourceFallback, type QuerySourceFallbackKind, type QuerySourceKind, type R2SqlResolverAdapterOptions, type ResolveExtraFn, type ResolvedComparisonSQL, type ResolvedSQL, type ResolvedSQLOptimized, type ResolverAdapter, type ResolverAdapterOptions, type ResolverOptions, type RollupRowsReader, type RunOptimizedQueryOptions, type RunQueryCtx, type RunSQLFn, type SqlFragments, type SqlFragmentsConfig, UnresolvableDatasetError, assertDimensionsSupported, assertSchemaInSync, buildExtrasQueries, buildTotalsSql, canonicalRollupCovers, createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, createResolverAdapter, createRollupExtrasOverlay, createSqlFragments, dimensionColumn, dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, inferLogicalDataset, isDatasetResolvable, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, mergeExtras, metricValue, pgResolverAdapter, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized, runComparisonQuery, runOptimizedQuery, supportsDimensionOnSurface };
+export { type AssertSchemaInSyncOptions, type CanonicalQueryDimSource, type ComparisonFilter, type ComparisonOrderBy, type ComparisonQueryResult, type CreateResolverAdapterConfig, DIMENSION_SURFACES, type DimensionBinding, type DimensionSurface, type ExtraQuery, LOGICAL_DATASETS, type LogicalDataset, type LogicalDatasetDefinition, type OptimizedQueryResult, type PgTableKey, type PrimaryColumnarSource, QuerySourceCoverageError, type QuerySourceDecision, type QuerySourceFallback, type QuerySourceFallbackKind, type QuerySourceKind, type R2SqlResolverAdapterOptions, type ResolveExtraFn, type ResolvedComparisonSQL, type ResolvedSQL, type ResolvedSQLOptimized, type ResolverAdapter, type ResolverAdapterOptions, type ResolverOptions, type RollupRowsReader, type RunOptimizedQueryOptions, type RunQueryCtx, type RunSQLFn, type SqlFragments, type SqlFragmentsConfig, UnresolvableDatasetError, assertDimensionsSupported, assertSchemaInSync, buildExtrasQueries, buildTotalsSql, canonicalRollupCovers, createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, createResolverAdapter, createRollupExtrasOverlay, createSqlFragments, dimensionColumn, dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, inferLogicalDataset, isDatasetResolvable, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, mergeExtras, metricValue, pgResolverAdapter, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized, runComparisonQuery, runOptimizedQuery, supportsDimensionOnSurface };

package/dist/resolver/types.d.mts

@@ -29,6 +29,15 @@ export interface ResolverAdapter<TableKey extends string = string> {
   };
 }
 export type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
+/**
+ * Order for a comparison read, applied to the joined rows before the row cap.
+ * `clicksChange` is current clicks minus previous clicks, so `asc` puts the
+ * biggest losers first and `desc` the biggest gainers.
+ */
+export interface ComparisonOrderBy {
+  column: 'clicksChange';
+  dir: 'asc' | 'desc';
+}
 export interface ResolverOptions<TableKey extends string = string> {
   adapter: ResolverAdapter<TableKey>;
   /** Optional site scope. Required for multi-tenant D1; omitted for parquet. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine",
   "type": "module",
-  "version": "5.6.0",
+  "version": "5.7.1",
   "description": "Append-only Parquet/DuckDB storage engine + planner + adapters for the gscdump pipeline. Node + edge runtimes; opt-in heavy peers.",
   "author": {
     "name": "Harlan Wilton",
@@ -189,10 +189,10 @@
     }
   },
   "dependencies": {
-    "@gscdump/contracts": "^5.6.0",
-    "@gscdump/lakehouse": "^5.6.0",
+    "@gscdump/contracts": "^5.7.1",
+    "@gscdump/lakehouse": "^5.7.1",
     "drizzle-orm": "1.0.0-rc.4",
-    "gscdump": "^5.6.0",
+    "gscdump": "^5.7.1",
     "pathe": "^2.0.3",
     "proper-lockfile": "^4.1.2"
   },