@gscdump/analysis 1.4.0 → 1.4.2

package/dist/analyzers/position-volatility.mjs

@@ -0,0 +1,143 @@
+import { rowString } from "../analyzer/row-values.mjs";
+import { defineAnalyzer } from "@gscdump/engine/analyzer";
+import { periodOf } from "@gscdump/engine/period";
+import { enumeratePartitions } from "@gscdump/engine/planner";
+import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
+import { num } from "@gscdump/engine/analysis-types";
+const positionVolatilityAnalyzer = defineAnalyzer({
+	id: "position-volatility",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		const topN = params.topN ?? 30;
+		const minDayImpressions = params.minImpressions ?? 10;
+		const minDays = params.minWeeksWithData ?? 7;
+		return {
+			sql: `
+    WITH query_day AS (
+      SELECT
+        url AS page,
+        query,
+        -- Normalize at the source CTE: union_by_name=true can coerce date to
+        -- VARCHAR across parquets with mixed schemas, which makes downstream
+        -- strftime(date, ...) binder-error.
+        CAST(date AS DATE) AS date,
+        ${METRIC_EXPR.impressions} AS q_impressions,
+        ${METRIC_EXPR.position} AS q_position
+      FROM read_parquet({{FILES}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+        AND query IS NOT NULL AND query <> ''
+        AND url IS NOT NULL AND url <> ''
+      GROUP BY url, query, date
+      HAVING SUM(impressions) >= 1
+    ),
+    daily AS (
+      SELECT
+        page, date,
+        COUNT(*) AS query_count,
+        SUM(q_impressions) AS day_impressions,
+        SUM(q_position * q_impressions) / NULLIF(SUM(q_impressions), 0) AS avg_position,
+        COALESCE(STDDEV_POP(q_position), 0.0) AS pos_stddev,
+        MIN(q_position) AS best_position,
+        MAX(q_position) AS worst_position
+      FROM query_day
+      GROUP BY page, date
+      HAVING SUM(q_impressions) >= ?
+    ),
+    with_shift AS (
+      SELECT *,
+        LAG(avg_position) OVER (PARTITION BY page ORDER BY date) AS prev_position,
+        COALESCE(
+          ABS(avg_position - LAG(avg_position) OVER (PARTITION BY page ORDER BY date)),
+          0.0
+        ) AS dod_shift
+      FROM daily
+    ),
+    scored AS (
+      SELECT *,
+        pos_stddev + dod_shift AS volatility
+      FROM with_shift
+    ),
+    top_pages AS (
+      SELECT page,
+        SUM(day_impressions) AS total_impressions,
+        AVG(volatility) AS avg_volatility,
+        MAX(volatility) AS peak_volatility,
+        COUNT(*) AS days_with_data
+      FROM scored
+      GROUP BY page
+      HAVING COUNT(*) >= ?
+      ORDER BY avg_volatility DESC
+      LIMIT ${Number(topN)}
+    )
+    SELECT
+      s.page,
+      strftime(s.date, '%Y-%m-%d') AS date,
+      s.query_count AS queryCount,
+      s.day_impressions AS dayImpressions,
+      s.avg_position AS avgPosition,
+      s.pos_stddev AS posStddev,
+      s.best_position AS bestPosition,
+      s.worst_position AS worstPosition,
+      s.dod_shift AS dodShift,
+      s.volatility AS volatility,
+      t.avg_volatility AS pageAvgVolatility,
+      t.peak_volatility AS pagePeakVolatility,
+      t.total_impressions AS pageTotalImpressions
+    FROM scored s
+    JOIN top_pages t USING (page)
+    ORDER BY t.avg_volatility DESC, s.date ASC
+  `,
+			params: [
+				startDate,
+				endDate,
+				minDayImpressions,
+				minDays
+			],
+			current: {
+				table: "page_queries",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const arr = Array.isArray(rows) ? rows : [];
+		const byPage = /* @__PURE__ */ new Map();
+		const allDates = /* @__PURE__ */ new Set();
+		for (const r of arr) {
+			const page = rowString(r.page);
+			const date = rowString(r.date);
+			allDates.add(date);
+			const entry = byPage.get(page) ?? {
+				page,
+				avgVolatility: num(r.pageAvgVolatility),
+				peakVolatility: num(r.pagePeakVolatility),
+				totalImpressions: num(r.pageTotalImpressions),
+				days: []
+			};
+			entry.days.push({
+				date,
+				queryCount: num(r.queryCount),
+				dayImpressions: num(r.dayImpressions),
+				avgPosition: num(r.avgPosition),
+				posStddev: num(r.posStddev),
+				bestPosition: num(r.bestPosition),
+				worstPosition: num(r.worstPosition),
+				dodShift: num(r.dodShift),
+				volatility: num(r.volatility)
+			});
+			byPage.set(page, entry);
+		}
+		const pages = [...byPage.values()].sort((a, b) => b.avgVolatility - a.avgVolatility);
+		const dates = [...allDates].sort();
+		const maxVolatility = pages.reduce((m, p) => Math.max(m, p.peakVolatility), 0);
+		return {
+			results: pages,
+			meta: {
+				total: pages.length,
+				dates,
+				maxVolatility
+			}
+		};
+	}
+});
+export { positionVolatilityAnalyzer };

package/dist/analyzers/query-migration.mjs

@@ -0,0 +1,178 @@
+import { parseJsonRows, rowString } from "../analyzer/row-values.mjs";
+import { defineAnalyzer } from "@gscdump/engine/analyzer";
+import { periodOf } from "@gscdump/engine/period";
+import { enumeratePartitions } from "@gscdump/engine/planner";
+import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
+import { num } from "@gscdump/engine/analysis-types";
+import { MS_PER_DAY, toIsoDate } from "gscdump/dates";
+const queryMigrationAnalyzer = defineAnalyzer({
+	id: "query-migration",
+	buildSql(params) {
+		const cur = periodOf(params);
+		let prevStart = params.prevStartDate;
+		let prevEnd = params.prevEndDate;
+		if (prevStart == null || prevEnd == null) {
+			const curStartMs = new Date(cur.startDate).getTime();
+			const span = new Date(cur.endDate).getTime() - curStartMs;
+			prevEnd = toIsoDate(new Date(curStartMs - MS_PER_DAY));
+			prevStart = toIsoDate(new Date(curStartMs - MS_PER_DAY - span));
+		}
+		const minImpressions = params.minImpressions ?? 20;
+		const limit = params.limit ?? 200;
+		const maxLevenshtein = 2;
+		return {
+			sql: `
+    WITH cur AS (
+      SELECT query, url AS page,
+        ${METRIC_EXPR.impressions} AS impressions,
+        ${METRIC_EXPR.clicks} AS clicks,
+        ${METRIC_EXPR.position} AS position
+      FROM read_parquet({{FILES}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+        AND query IS NOT NULL AND query <> ''
+        AND url IS NOT NULL AND url <> ''
+      GROUP BY query, url
+      HAVING SUM(impressions) >= ?
+    ),
+    prev AS (
+      SELECT query, url AS page,
+        ${METRIC_EXPR.impressions} AS impressions,
+        ${METRIC_EXPR.clicks} AS clicks,
+        ${METRIC_EXPR.position} AS position
+      FROM read_parquet({{FILES_PREV}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+        AND query IS NOT NULL AND query <> ''
+        AND url IS NOT NULL AND url <> ''
+      GROUP BY query, url
+      HAVING SUM(impressions) >= ?
+    ),
+    lost AS (
+      SELECT p.page AS source_page, p.query AS source_query, p.impressions AS source_impressions
+      FROM prev p
+      LEFT JOIN cur c ON p.page = c.page AND p.query = c.query
+      WHERE c.query IS NULL
+    ),
+    gained AS (
+      SELECT c.page AS target_page, c.query AS target_query, c.impressions AS target_impressions
+      FROM cur c
+      LEFT JOIN prev p ON p.page = c.page AND p.query = c.query
+      WHERE p.query IS NULL
+    ),
+    matched AS (
+      SELECT
+        l.source_page, l.source_query, l.source_impressions,
+        g.target_page, g.target_query, g.target_impressions,
+        CASE
+          WHEN l.source_query = g.target_query THEN 'exact'
+          ELSE 'fuzzy'
+        END AS match_type,
+        LEAST(l.source_impressions, g.target_impressions) AS absorbed_impressions
+      FROM lost l
+      JOIN gained g
+        ON l.source_page <> g.target_page
+        AND ABS(LENGTH(l.source_query) - LENGTH(g.target_query)) <= ${maxLevenshtein}
+        AND (
+          l.source_query = g.target_query
+          OR levenshtein(l.source_query, g.target_query) <= ${maxLevenshtein}
+        )
+    ),
+    edges AS (
+      SELECT
+        source_page, target_page,
+        SUM(absorbed_impressions) AS weight,
+        COUNT(*) AS query_count,
+        SUM(CASE WHEN match_type = 'exact' THEN 1 ELSE 0 END) AS exact_count,
+        to_json(list({
+          'sourceQuery': source_query,
+          'targetQuery': target_query,
+          'absorbed': absorbed_impressions,
+          'matchType': match_type
+        } ORDER BY absorbed_impressions DESC)) AS examplesJson
+      FROM matched
+      GROUP BY source_page, target_page
+    )
+    SELECT *
+    FROM edges
+    ORDER BY weight DESC
+    LIMIT ${Number(limit)}
+  `,
+			params: [
+				cur.startDate,
+				cur.endDate,
+				minImpressions,
+				prevStart,
+				prevEnd,
+				minImpressions
+			],
+			current: {
+				table: "page_queries",
+				partitions: enumeratePartitions(cur.startDate, cur.endDate)
+			},
+			previous: {
+				table: "page_queries",
+				partitions: enumeratePartitions(prevStart, prevEnd)
+			}
+		};
+	},
+	reduceSql(rows, params) {
+		const arr = Array.isArray(rows) ? rows : [];
+		const cur = periodOf(params);
+		let prevStart = params.prevStartDate;
+		let prevEnd = params.prevEndDate;
+		if (prevStart == null || prevEnd == null) {
+			const curStartMs = new Date(cur.startDate).getTime();
+			const span = new Date(cur.endDate).getTime() - curStartMs;
+			prevEnd = toIsoDate(new Date(curStartMs - MS_PER_DAY));
+			prevStart = toIsoDate(new Date(curStartMs - MS_PER_DAY - span));
+		}
+		const edges = arr.map((r) => ({
+			sourcePage: rowString(r.source_page),
+			targetPage: rowString(r.target_page),
+			weight: num(r.weight),
+			queryCount: num(r.query_count),
+			exactCount: num(r.exact_count),
+			fuzzyCount: num(r.query_count) - num(r.exact_count),
+			examples: parseJsonRows(r.examplesJson).slice(0, 8).map((e) => ({
+				sourceQuery: rowString(e.sourceQuery),
+				targetQuery: rowString(e.targetQuery),
+				absorbed: num(e.absorbed),
+				matchType: rowString(e.matchType)
+			}))
+		}));
+		const nodeAgg = /* @__PURE__ */ new Map();
+		for (const e of edges) {
+			const src = nodeAgg.get(e.sourcePage) ?? {
+				url: e.sourcePage,
+				outgoing: 0,
+				incoming: 0
+			};
+			src.outgoing += e.weight;
+			nodeAgg.set(e.sourcePage, src);
+			const tgt = nodeAgg.get(e.targetPage) ?? {
+				url: e.targetPage,
+				outgoing: 0,
+				incoming: 0
+			};
+			tgt.incoming += e.weight;
+			nodeAgg.set(e.targetPage, tgt);
+		}
+		const nodes = [...nodeAgg.values()];
+		const totalAbsorbed = edges.reduce((s, e) => s + e.weight, 0);
+		return {
+			results: edges,
+			meta: {
+				total: edges.length,
+				totalAbsorbed,
+				period: {
+					current: cur,
+					previous: {
+						startDate: prevStart,
+						endDate: prevEnd
+					}
+				},
+				nodes
+			}
+		};
+	}
+});
+export { queryMigrationAnalyzer };

package/dist/analyzers/seasonality.d.mts

@@ -0,0 +1,28 @@
+import { DateRow } from "../types.mjs";
+type SeasonalityMetric = 'clicks' | 'impressions';
+interface SeasonalityOptions {
+  /** Metric to analyze for seasonality. Default: clicks */
+  metric?: SeasonalityMetric;
+}
+interface MonthlyData {
+  month: string;
+  value: number;
+  vsAverage: number;
+  isPeak: boolean;
+  isTrough: boolean;
+}
+interface SeasonalityResult {
+  hasSeasonality: boolean;
+  /** Coefficient of variation: std dev / mean. Higher = more seasonal. */
+  strength: number;
+  peakMonths: string[];
+  troughMonths: string[];
+  monthlyBreakdown: MonthlyData[];
+  insufficientData: boolean;
+}
+/**
+ * Pure helper: detects seasonality patterns by analyzing monthly traffic
+ * variation. Re-exported from `@gscdump/analysis` for portable callers.
+ */
+declare function analyzeSeasonality(dates: DateRow[], options?: SeasonalityOptions): SeasonalityResult;
+export { MonthlyData, SeasonalityMetric, SeasonalityOptions, SeasonalityResult, analyzeSeasonality };

package/dist/analyzers/seasonality.mjs

@@ -0,0 +1,136 @@
+import { rowBoolean, rowString } from "../analyzer/row-values.mjs";
+import { datesQueryState } from "../analyzer/adapt-rows.mjs";
+import { defineAnalyzer } from "@gscdump/engine/analyzer";
+import { periodOf } from "@gscdump/engine/period";
+import { enumeratePartitions } from "@gscdump/engine/planner";
+import { num } from "@gscdump/engine/analysis-types";
+function calculateCV(values) {
+	if (values.length === 0) return 0;
+	const mean = values.reduce((a, b) => a + b, 0) / values.length;
+	if (mean === 0) return 0;
+	const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+	return Math.min(Math.sqrt(variance) / mean, 1);
+}
+function analyzeSeasonality(dates, options = {}) {
+	const { metric = "clicks" } = options;
+	if (dates.length === 0) return {
+		hasSeasonality: false,
+		strength: 0,
+		peakMonths: [],
+		troughMonths: [],
+		monthlyBreakdown: [],
+		insufficientData: true
+	};
+	const monthlyMap = /* @__PURE__ */ new Map();
+	for (const row of dates) {
+		const month = row.date.substring(0, 7);
+		const value = metric === "clicks" ? row.clicks : row.impressions;
+		monthlyMap.set(month, (monthlyMap.get(month) || 0) + value);
+	}
+	const months = Array.from(monthlyMap.keys()).sort();
+	const values = months.map((m) => monthlyMap.get(m) || 0);
+	const insufficientData = months.length < 12;
+	const totalValue = values.reduce((a, b) => a + b, 0);
+	const avgValue = values.length > 0 ? totalValue / values.length : 0;
+	const monthlyBreakdown = months.map((month, i) => {
+		const value = values[i] ?? 0;
+		const vsAverage = avgValue > 0 ? value / avgValue : 0;
+		return {
+			month,
+			value,
+			vsAverage,
+			isPeak: vsAverage > 1.5,
+			isTrough: vsAverage < .5
+		};
+	});
+	const peakMonths = [...new Set(monthlyBreakdown.filter((m) => m.isPeak).map((m) => m.month.substring(5, 7)))];
+	const troughMonths = [...new Set(monthlyBreakdown.filter((m) => m.isTrough).map((m) => m.month.substring(5, 7)))];
+	const strength = calculateCV(values);
+	return {
+		hasSeasonality: peakMonths.length > 0 || troughMonths.length > 0 || strength > .3,
+		strength,
+		peakMonths,
+		troughMonths,
+		monthlyBreakdown,
+		insufficientData
+	};
+}
+const seasonalityAnalyzer = defineAnalyzer({
+	id: "seasonality",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		return {
+			sql: `
+      WITH monthly AS (
+        SELECT
+          strftime(CAST(date AS DATE), '%Y-%m') AS month,
+          CAST(SUM(${params.metric === "impressions" ? "impressions" : "clicks"}) AS DOUBLE) AS value
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY month
+      ),
+      stats AS (
+        SELECT
+          AVG(value) AS avg_val,
+          COALESCE(STDDEV_POP(value), 0.0) AS std_val,
+          CAST(COUNT(*) AS DOUBLE) AS month_count
+        FROM monthly
+      )
+      SELECT
+        m.month AS month,
+        m.value AS value,
+        CASE WHEN s.avg_val > 0 THEN m.value / s.avg_val ELSE 0.0 END AS vsAverage,
+        (s.avg_val > 0 AND m.value / s.avg_val > 1.5) AS isPeak,
+        (s.avg_val > 0 AND m.value / s.avg_val < 0.5) AS isTrough,
+        CASE WHEN s.avg_val > 0 THEN LEAST(s.std_val / s.avg_val, 1.0) ELSE 0.0 END AS strength,
+        s.month_count AS monthCount
+      FROM monthly m, stats s
+      ORDER BY m.month
+    `,
+			params: [startDate, endDate],
+			current: {
+				table: "pages",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const arr = Array.isArray(rows) ? rows : [];
+		const breakdown = arr.map((r) => ({
+			month: rowString(r.month),
+			value: num(r.value),
+			vsAverage: num(r.vsAverage),
+			isPeak: rowBoolean(r.isPeak),
+			isTrough: rowBoolean(r.isTrough)
+		}));
+		const first = arr[0];
+		const strength = first ? num(first.strength) : 0;
+		const monthCount = first ? num(first.monthCount) : 0;
+		const peakMonths = [...new Set(breakdown.filter((m) => m.isPeak).map((m) => m.month.substring(5, 7)))];
+		const troughMonths = [...new Set(breakdown.filter((m) => m.isTrough).map((m) => m.month.substring(5, 7)))];
+		const hasSeasonality = peakMonths.length > 0 || troughMonths.length > 0 || strength > .3;
+		const insufficientData = monthCount < 12;
+		return {
+			results: breakdown,
+			meta: {
+				total: breakdown.length,
+				hasSeasonality,
+				strength,
+				peakMonths,
+				troughMonths,
+				insufficientData
+			}
+		};
+	},
+	buildRows(params) {
+		return { dates: datesQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		const result = analyzeSeasonality(Array.isArray(rows) ? rows : [], { metric: params.metric });
+		return {
+			results: result.monthlyBreakdown,
+			meta: { strength: result.strength }
+		};
+	}
+});
+export { analyzeSeasonality, seasonalityAnalyzer };

package/dist/analyzers/stl-decompose.mjs

@@ -0,0 +1,187 @@
+import { parseJsonRows, rowBoolean, rowString } from "../analyzer/row-values.mjs";
+import { defineAnalyzer } from "@gscdump/engine/analyzer";
+import { defaultEndDate } from "@gscdump/engine/period";
+import { enumeratePartitions } from "@gscdump/engine/planner";
+import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
+import { num } from "@gscdump/engine/analysis-types";
+import { daysAgoUtc } from "gscdump/dates";
+const stlDecomposeAnalyzer = defineAnalyzer({
+	id: "stl-decompose",
+	buildSql(params) {
+		const endDate = params.endDate ?? defaultEndDate();
+		const startDate = params.startDate ?? daysAgoUtc(93);
+		const minImpressions = params.minImpressions ?? 100;
+		const minDays = 21;
+		const metric = params.metric === "clicks" ? "clicks" : "impressions";
+		const limit = params.limit ?? 100;
+		return {
+			sql: `
+    WITH daily AS (
+      SELECT
+        query,
+        url AS page,
+        -- Normalize at the source CTE: union_by_name=true can coerce date to
+        -- VARCHAR across parquets with mixed schemas, which makes downstream
+        -- strftime(date, ...) binder-error.
+        CAST(date AS DATE) AS date,
+        ${METRIC_EXPR.clicks} AS clicks,
+        ${METRIC_EXPR.impressions} AS impressions,
+        CAST(SUM(${metric}) AS DOUBLE) AS observed
+      FROM read_parquet({{FILES}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+        AND query IS NOT NULL AND query <> ''
+        AND url IS NOT NULL AND url <> ''
+      GROUP BY query, url, date
+    ),
+    entity_stats AS (
+      SELECT query, page,
+        COUNT(*) AS days,
+        SUM(impressions) AS total_impressions
+      FROM daily
+      GROUP BY query, page
+      HAVING COUNT(*) >= ${Number(minDays)}
+        AND SUM(impressions) >= ?
+    ),
+    filtered AS (
+      SELECT d.*
+      FROM daily d
+      JOIN entity_stats e USING (query, page)
+    ),
+    trended AS (
+      SELECT *,
+        CASE
+          WHEN COUNT(*) OVER w = 7
+            THEN AVG(observed) OVER w
+          ELSE NULL
+        END AS trend
+      FROM filtered
+      WINDOW w AS (
+        PARTITION BY query, page
+        ORDER BY date
+        ROWS BETWEEN 3 PRECEDING AND 3 FOLLOWING
+      )
+    ),
+    detrended AS (
+      SELECT *,
+        observed - trend AS detrended,
+        dayofweek(date) AS dow
+      FROM trended
+    ),
+    seasonal_raw AS (
+      SELECT *,
+        AVG(detrended) OVER (PARTITION BY query, page, dow) AS seasonal_dow
+      FROM detrended
+    ),
+    seasonal_centered AS (
+      SELECT *,
+        seasonal_dow - AVG(seasonal_dow) OVER (PARTITION BY query, page) AS seasonal
+      FROM seasonal_raw
+    ),
+    residualed AS (
+      SELECT *,
+        CASE
+          WHEN trend IS NULL OR seasonal IS NULL THEN NULL
+          ELSE observed - trend - seasonal
+        END AS residual
+      FROM seasonal_centered
+    ),
+    scored AS (
+      SELECT *,
+        STDDEV_POP(residual) OVER (PARTITION BY query, page) AS resid_std,
+        CASE
+          WHEN residual IS NOT NULL
+            AND STDDEV_POP(residual) OVER (PARTITION BY query, page) > 0
+            AND ABS(residual) > 2.0 * STDDEV_POP(residual) OVER (PARTITION BY query, page)
+          THEN true ELSE false
+        END AS anomaly
+      FROM residualed
+    ),
+    per_entity AS (
+      SELECT query, page,
+        COUNT(*) AS days,
+        SUM(impressions) AS total_impressions,
+        VAR_POP(detrended) AS var_detrended,
+        VAR_POP(seasonal) AS var_seasonal,
+        VAR_POP(residual) AS var_residual,
+        COUNT(*) FILTER (WHERE anomaly) AS residual_anomalies,
+        REGR_SLOPE(observed, epoch(date) / 86400.0) AS trend_slope
+      FROM scored
+      GROUP BY query, page
+    ),
+    series AS (
+      SELECT query, page,
+        to_json(list({
+          'date': strftime(date, '%Y-%m-%d'),
+          'observed': observed,
+          'trend': trend,
+          'seasonal': seasonal,
+          'residual': residual,
+          'anomaly': anomaly
+        } ORDER BY date)) AS seriesJson
+      FROM scored
+      GROUP BY query, page
+    )
+    SELECT
+      e.query AS keyword,
+      e.page,
+      CAST(e.total_impressions AS DOUBLE) AS totalImpressions,
+      CAST(e.days AS DOUBLE) AS days,
+      CASE
+        WHEN e.var_detrended IS NULL OR e.var_detrended = 0 THEN 0.0
+        ELSE LEAST(e.var_seasonal / NULLIF(e.var_detrended, 0), 1.0)
+      END AS seasonalStrength,
+      CASE
+        WHEN e.var_detrended IS NULL OR e.var_detrended = 0 THEN 0.0
+        ELSE GREATEST(0.0, 1.0 - e.var_residual / NULLIF(e.var_detrended, 0))
+      END AS trendStrength,
+      CAST(e.residual_anomalies AS DOUBLE) AS residualAnomalies,
+      COALESCE(e.trend_slope, 0.0) AS trendSlope,
+      s.seriesJson
+    FROM per_entity e
+    LEFT JOIN series s USING (query, page)
+    ORDER BY seasonalStrength DESC, ABS(COALESCE(e.trend_slope, 0.0)) DESC
+    LIMIT ${Number(limit)}
+  `,
+			params: [
+				startDate,
+				endDate,
+				minImpressions
+			],
+			current: {
+				table: "page_queries",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows, params) {
+		const arr = Array.isArray(rows) ? rows : [];
+		const metric = params.metric === "clicks" ? "clicks" : "impressions";
+		const results = arr.map((r) => ({
+			keyword: rowString(r.keyword),
+			page: rowString(r.page),
+			totalImpressions: num(r.totalImpressions),
+			days: num(r.days),
+			seasonalStrength: num(r.seasonalStrength),
+			trendStrength: num(r.trendStrength),
+			residualAnomalies: num(r.residualAnomalies),
+			trendSlope: num(r.trendSlope),
+			series: parseJsonRows(r.seriesJson).map((s) => ({
+				date: rowString(s.date),
+				observed: num(s.observed),
+				trend: s.trend == null ? null : num(s.trend),
+				seasonal: s.seasonal == null ? null : num(s.seasonal),
+				residual: s.residual == null ? null : num(s.residual),
+				anomaly: rowBoolean(s.anomaly)
+			}))
+		}));
+		return {
+			results,
+			meta: {
+				total: results.length,
+				metric,
+				avgSeasonalStrength: results.length > 0 ? results.reduce((a, r) => a + r.seasonalStrength, 0) / results.length : 0
+			}
+		};
+	}
+});
+export { stlDecomposeAnalyzer };