@gscdump/analysis 1.4.0 → 1.4.1

package/dist/analyzers/cannibalization.mjs

@@ -0,0 +1,267 @@
+import { parseJsonRows, rowString } from "../analyzer/row-values.mjs";
+import { queriesQueryState } from "../analyzer/adapt-rows.mjs";
+import { createSorter } from "../types.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 sortRowResults = createSorter((item, metric) => {
+	switch (metric) {
+		case "clicks": return item.totalClicks;
+		case "impressions": return item.totalImpressions;
+		case "positionSpread": return item.positionSpread;
+		case "pageCount": return item.pages.length;
+	}
+}, "clicks");
+function analyzeCannibalization(rows, options = {}) {
+	const { minImpressions = 10, maxPositionSpread = 10, minPages = 2, sortBy = "clicks", sortOrder = "desc" } = options;
+	const queryMap = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		if (row.impressions < minImpressions) continue;
+		const pages = queryMap.get(row.query) || [];
+		pages.push({
+			page: row.page,
+			clicks: row.clicks,
+			impressions: row.impressions,
+			ctr: row.ctr,
+			position: row.position
+		});
+		queryMap.set(row.query, pages);
+	}
+	const results = [];
+	for (const [query, pages] of queryMap) {
+		if (pages.length < minPages) continue;
+		let minPosition = Number.POSITIVE_INFINITY;
+		let maxPosition = Number.NEGATIVE_INFINITY;
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		for (const page of pages) {
+			minPosition = Math.min(minPosition, page.position);
+			maxPosition = Math.max(maxPosition, page.position);
+			totalClicks += page.clicks;
+			totalImpressions += page.impressions;
+		}
+		const positionSpread = maxPosition - minPosition;
+		if (positionSpread > maxPositionSpread) continue;
+		pages.sort((a, b) => b.clicks - a.clicks);
+		results.push({
+			query,
+			pages,
+			totalClicks,
+			totalImpressions,
+			positionSpread
+		});
+	}
+	return sortRowResults(results, sortBy, sortOrder);
+}
+const cannibalizationAnalyzer = defineAnalyzer({
+	id: "cannibalization",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		const minImpressions = params.minImpressions ?? 50;
+		const minCompetitors = 2;
+		const minQueryImpressions = (params.minImpressions ?? 50) * 2;
+		const limit = params.limit ?? 200;
+		return {
+			sql: `
+      WITH agg AS (
+        SELECT
+          query,
+          url,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions,
+          ${METRIC_EXPR.ctr} AS ctr,
+          ${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) >= ?
+      ),
+      query_totals AS (
+        SELECT
+          query,
+          SUM(impressions) AS total_impressions,
+          SUM(clicks) AS total_clicks,
+          COUNT(*) AS competitor_count
+        FROM agg
+        GROUP BY query
+        HAVING COUNT(*) >= ? AND SUM(impressions) >= ?
+      ),
+      ranked AS (
+        SELECT
+          a.query,
+          a.url,
+          a.clicks,
+          a.impressions,
+          a.ctr,
+          a.position,
+          a.impressions / NULLIF(t.total_impressions, 0) AS share,
+          ROW_NUMBER() OVER (
+            PARTITION BY a.query
+            ORDER BY a.impressions DESC, a.clicks DESC, a.url ASC
+          ) AS rnk
+        FROM agg a
+        JOIN query_totals t USING (query)
+      ),
+      leader AS (
+        SELECT query, url AS leader_url, ctr AS leader_ctr, position AS leader_position
+        FROM ranked WHERE rnk = 1
+      ),
+      events AS (
+        SELECT
+          r.query,
+          any_value(l.leader_url) AS leader_url,
+          any_value(l.leader_ctr) AS leader_ctr,
+          any_value(l.leader_position) AS leader_position,
+          SUM(POWER(r.share * 100.0, 2)) AS hhi,
+          SUM(CASE
+            WHEN r.rnk > 1 AND l.leader_ctr > r.ctr
+              THEN (l.leader_ctr - r.ctr) * r.impressions
+            ELSE 0.0
+          END) AS stolen_clicks,
+          to_json(list({
+            'url': r.url,
+            'clicks': r.clicks,
+            'impressions': r.impressions,
+            'ctr': r.ctr,
+            'position': r.position,
+            'share': r.share,
+            'rank': r.rnk
+          } ORDER BY r.rnk)) AS competitors
+        FROM ranked r
+        JOIN leader l USING (query)
+        GROUP BY r.query
+      )
+      SELECT
+        e.query AS keyword,
+        t.total_impressions AS totalImpressions,
+        t.total_clicks AS totalClicks,
+        t.competitor_count AS competitorCount,
+        e.leader_url AS leaderUrl,
+        e.leader_ctr AS leaderCtr,
+        e.leader_position AS leaderPosition,
+        e.hhi AS hhi,
+        GREATEST(0.0, 1.0 - e.hhi / 10000.0) AS fragmentation,
+        e.stolen_clicks AS stolenClicks,
+        e.competitors AS competitors,
+        CAST(ROUND(LEAST(100.0,
+          100.0 * POWER(
+            GREATEST(1.0 - e.hhi / 10000.0, 0.0)
+              * LEAST(e.stolen_clicks / GREATEST(t.total_clicks + e.stolen_clicks, 1.0), 1.0)
+              * LEAST(LOG10(GREATEST(t.total_impressions, 10.0)) / 5.0, 1.0),
+            1.0 / 3.0
+          )
+        )) AS DOUBLE) AS severity
+      FROM events e
+      JOIN query_totals t USING (query)
+      ORDER BY severity DESC, stolenClicks DESC
+      LIMIT ${Number(limit)}
+    `,
+			params: [
+				startDate,
+				endDate,
+				minImpressions,
+				minCompetitors,
+				minQueryImpressions
+			],
+			current: {
+				table: "page_queries",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const events = (Array.isArray(rows) ? rows : []).map((r) => ({
+			keyword: rowString(r.keyword),
+			totalImpressions: num(r.totalImpressions),
+			totalClicks: num(r.totalClicks),
+			competitorCount: num(r.competitorCount),
+			leaderUrl: rowString(r.leaderUrl),
+			leaderCtr: num(r.leaderCtr),
+			leaderPosition: num(r.leaderPosition),
+			hhi: num(r.hhi),
+			fragmentation: num(r.fragmentation),
+			stolenClicks: num(r.stolenClicks),
+			severity: num(r.severity),
+			competitors: parseJsonRows(r.competitors).map((c) => ({
+				url: rowString(c.url),
+				clicks: num(c.clicks),
+				impressions: num(c.impressions),
+				ctr: num(c.ctr),
+				position: num(c.position),
+				share: num(c.share),
+				rank: num(c.rank)
+			}))
+		}));
+		const nodeAgg = /* @__PURE__ */ new Map();
+		const edgeAgg = /* @__PURE__ */ new Map();
+		for (const ev of events) {
+			for (const c of ev.competitors) {
+				const n = nodeAgg.get(c.url) ?? {
+					impressions: 0,
+					clicks: 0,
+					queries: /* @__PURE__ */ new Set()
+				};
+				n.impressions += c.impressions;
+				n.clicks += c.clicks;
+				n.queries.add(ev.keyword);
+				nodeAgg.set(c.url, n);
+			}
+			for (let i = 0; i < ev.competitors.length; i++) for (let j = i + 1; j < ev.competitors.length; j++) {
+				const a = ev.competitors[i];
+				const b = ev.competitors[j];
+				const [src, tgt] = a.url < b.url ? [a.url, b.url] : [b.url, a.url];
+				const key = `${src}
${tgt}`;
+				const weight = Math.min(a.impressions, b.impressions);
+				const edge = edgeAgg.get(key) ?? {
+					source: src,
+					target: tgt,
+					weight: 0,
+					queries: 0
+				};
+				edge.weight += weight;
+				edge.queries += 1;
+				edgeAgg.set(key, edge);
+			}
+		}
+		const nodes = [...nodeAgg.entries()].map(([url, n]) => ({
+			url,
+			impressions: n.impressions,
+			clicks: n.clicks,
+			queryCount: n.queries.size
+		}));
+		const edges = [...edgeAgg.values()];
+		const avgFragmentation = events.length > 0 ? events.reduce((s, e) => s + e.fragmentation, 0) / events.length : 0;
+		const totalStolenClicks = events.reduce((s, e) => s + e.stolenClicks, 0);
+		return {
+			results: events,
+			meta: {
+				total: events.length,
+				totalStolenClicks,
+				avgFragmentation,
+				graph: {
+					nodes,
+					edges
+				}
+			}
+		};
+	},
+	buildRows(params) {
+		return { rows: queriesQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		const results = analyzeCannibalization(Array.isArray(rows) ? rows : [], {
+			minImpressions: params.minImpressions,
+			maxPositionSpread: params.maxPositionSpread,
+			minPages: params.minPages
+		});
+		return {
+			results,
+			meta: { total: results.length }
+		};
+	}
+});
+export { analyzeCannibalization, cannibalizationAnalyzer };

package/dist/analyzers/change-point.mjs

@@ -0,0 +1,197 @@
+import { parseJsonRows, rowNumber, 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 { daysAgoUtc } from "gscdump/dates";
+const changePointAnalyzer = defineAnalyzer({
+	id: "change-point",
+	buildSql(params) {
+		const endDate = params.endDate ?? defaultEndDate();
+		const startDate = params.startDate ?? daysAgoUtc(93);
+		const minDays = 21;
+		const minSide = 7;
+		const threshold = params.threshold ?? 10;
+		const minImpressions = params.minImpressions ?? 50;
+		const metric = params.metric === "clicks" || params.metric === "impressions" ? params.metric : "position";
+		const limit = params.limit ?? 100;
+		const valueExpr = metric === "position" ? METRIC_EXPR.position : `CAST(SUM(${metric}) AS DOUBLE)`;
+		const weightExpr = metric === "position" ? METRIC_EXPR.impressions : "1.0";
+		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,
+        ${valueExpr} AS value,
+        ${weightExpr} AS weight
+      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
+      HAVING SUM(impressions) >= 1
+    ),
+    entity_stats AS (
+      SELECT query, page,
+        COUNT(*) AS n_total,
+        SUM(impressions) AS total_impressions,
+        SUM(weight) AS w_total,
+        SUM(value * weight) AS sum_total,
+        SUM(value * value * weight) AS sumsq_total
+      FROM daily
+      GROUP BY query, page
+      HAVING COUNT(*) >= ${Number(minDays)}
+        AND SUM(impressions) >= ?
+    ),
+    filtered AS (
+      SELECT d.*,
+        e.n_total, e.w_total, e.sum_total, e.sumsq_total, e.total_impressions
+      FROM daily d
+      JOIN entity_stats e USING (query, page)
+    ),
+    cumulated AS (
+      SELECT *,
+        COUNT(*) OVER w AS n_left,
+        SUM(weight) OVER w AS w_left,
+        SUM(value * weight) OVER w AS sum_left,
+        SUM(value * value * weight) OVER w AS sumsq_left
+      FROM filtered
+      WINDOW w AS (
+        PARTITION BY query, page
+        ORDER BY date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+      )
+    ),
+    llr_scored AS (
+      SELECT *,
+        (n_total - n_left) AS n_right,
+        (w_total - w_left) AS w_right,
+        (sum_total - sum_left) AS sum_right,
+        (sumsq_total - sumsq_left) AS sumsq_right,
+        GREATEST(
+          (sumsq_left / NULLIF(w_left, 0))
+            - (sum_left / NULLIF(w_left, 0)) * (sum_left / NULLIF(w_left, 0)),
+          1e-9
+        ) AS var_left,
+        GREATEST(
+          ((sumsq_total - sumsq_left) / NULLIF(w_total - w_left, 0))
+            - ((sum_total - sum_left) / NULLIF(w_total - w_left, 0))
+              * ((sum_total - sum_left) / NULLIF(w_total - w_left, 0)),
+          1e-9
+        ) AS var_right,
+        GREATEST(
+          (sumsq_total / NULLIF(w_total, 0))
+            - (sum_total / NULLIF(w_total, 0)) * (sum_total / NULLIF(w_total, 0)),
+          1e-9
+        ) AS var_single
+      FROM cumulated
+    ),
+    llr AS (
+      SELECT *,
+        CASE
+          WHEN n_left >= ${Number(minSide)} AND (n_total - n_left) >= ${Number(minSide)}
+          THEN n_total * LN(var_single)
+            - n_left * LN(var_left)
+            - (n_total - n_left) * LN(var_right)
+          ELSE NULL
+        END AS llr
+      FROM llr_scored
+    ),
+    best AS (
+      SELECT query, page, n_total, total_impressions,
+        arg_max(date, llr) AS change_date,
+        MAX(llr) AS best_llr,
+        arg_max(sum_left / NULLIF(w_left, 0), llr) AS left_mean,
+        arg_max((sum_total - sum_left) / NULLIF(w_total - w_left, 0), llr) AS right_mean,
+        arg_max(sqrt(var_left), llr) AS left_std,
+        arg_max(sqrt(var_right), llr) AS right_std
+      FROM llr
+      WHERE llr IS NOT NULL
+      GROUP BY query, page, n_total, total_impressions
+      HAVING MAX(llr) > ${Number(threshold)}
+    ),
+    series AS (
+      SELECT query, page,
+        to_json(list({
+          'date': strftime(date, '%Y-%m-%d'),
+          'value': value
+        } ORDER BY date)) AS seriesJson
+      FROM daily
+      GROUP BY query, page
+    )
+    SELECT
+      b.query AS keyword,
+      b.page,
+      CAST(b.n_total AS DOUBLE) AS totalDays,
+      CAST(b.total_impressions AS DOUBLE) AS totalImpressions,
+      strftime(b.change_date, '%Y-%m-%d') AS changeDate,
+      b.best_llr AS llr,
+      b.left_mean AS leftMean,
+      b.right_mean AS rightMean,
+      (b.right_mean - b.left_mean) AS delta,
+      b.left_std AS leftStddev,
+      b.right_std AS rightStddev,
+      s.seriesJson
+    FROM best b
+    LEFT JOIN series s USING (query, page)
+    ORDER BY b.best_llr 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 threshold = params.threshold ?? 10;
+		const metric = params.metric === "clicks" || params.metric === "impressions" ? params.metric : "position";
+		const lowerIsBetter = metric === "position";
+		const results = arr.map((r) => {
+			const delta = rowNumber(r.delta);
+			const improved = lowerIsBetter ? delta < 0 : delta > 0;
+			return {
+				keyword: rowString(r.keyword),
+				page: rowString(r.page),
+				totalDays: rowNumber(r.totalDays),
+				totalImpressions: rowNumber(r.totalImpressions),
+				changeDate: rowString(r.changeDate),
+				llr: rowNumber(r.llr),
+				leftMean: rowNumber(r.leftMean),
+				rightMean: rowNumber(r.rightMean),
+				delta,
+				leftStddev: rowNumber(r.leftStddev),
+				rightStddev: rowNumber(r.rightStddev),
+				direction: improved ? "improved" : "worsened",
+				series: parseJsonRows(r.seriesJson).map((s) => ({
+					date: rowString(s.date),
+					value: rowNumber(s.value)
+				}))
+			};
+		});
+		return {
+			results,
+			meta: {
+				total: results.length,
+				metric,
+				threshold,
+				improved: results.filter((r) => r.direction === "improved").length,
+				worsened: results.filter((r) => r.direction === "worsened").length
+			}
+		};
+	}
+});
+export { changePointAnalyzer };

package/dist/analyzers/clustering.d.mts

@@ -0,0 +1,29 @@
+import { QueriesRow } from "../types.mjs";
+type ClusterType = 'prefix' | 'intent' | 'both';
+interface ClusteringOptions {
+  /** Minimum keywords for a cluster to be reported. Default: 2 */
+  minClusterSize?: number;
+  /** Minimum impressions for a keyword to be included. Default: 10 */
+  minImpressions?: number;
+  /** Clustering method. Default: 'both' */
+  clusterBy?: ClusterType;
+}
+interface KeywordCluster {
+  clusterName: string;
+  clusterType: 'prefix' | 'intent';
+  keywords: QueriesRow[];
+  totalClicks: number;
+  totalImpressions: number;
+  avgPosition: number;
+  keywordCount: number;
+}
+interface ClusteringResult {
+  clusters: KeywordCluster[];
+  unclustered: QueriesRow[];
+}
+/**
+ * Pure helper: clusters keywords by intent prefix or common word prefix.
+ * Re-exported from `@gscdump/analysis` for portable callers.
+ */
+declare function analyzeClustering(keywords: QueriesRow[], options?: ClusteringOptions): ClusteringResult;
+export { ClusterType, ClusteringOptions, ClusteringResult, KeywordCluster, analyzeClustering };

package/dist/analyzers/clustering.mjs

@@ -0,0 +1,217 @@
+import { parseJsonRows, rowString } from "../analyzer/row-values.mjs";
+import { queriesQueryState } from "../analyzer/adapt-rows.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 INTENT_PREFIXES_REGEX = "^(how to|what is|what are|why is|why do|where to|when to|best|top|vs|versus|compare|review|buy|cheap|free|near me)(\\s|$)";
+const INTENT_PREFIXES = [
+	"how to",
+	"what is",
+	"what are",
+	"why is",
+	"why do",
+	"where to",
+	"when to",
+	"best",
+	"top",
+	"vs",
+	"versus",
+	"compare",
+	"review",
+	"buy",
+	"cheap",
+	"free",
+	"near me"
+];
+const WHITESPACE_RE = /\s+/;
+function extractIntentPrefix(keyword) {
+	const lower = keyword.toLowerCase();
+	for (const prefix of INTENT_PREFIXES) if (lower.startsWith(`${prefix} `) || lower.startsWith(prefix)) return prefix;
+	return null;
+}
+function extractWordPrefix(keyword, wordCount = 2) {
+	const words = keyword.toLowerCase().split(WHITESPACE_RE).filter(Boolean);
+	if (words.length < wordCount + 1) return null;
+	return words.slice(0, wordCount).join(" ");
+}
+function analyzeClustering(keywords, options = {}) {
+	const { minClusterSize = 2, minImpressions = 10, clusterBy = "both" } = options;
+	const filtered = keywords.filter((k) => num(k.impressions) >= minImpressions);
+	const clusterMap = /* @__PURE__ */ new Map();
+	const clusteredKeywords = /* @__PURE__ */ new Set();
+	if (clusterBy === "intent" || clusterBy === "both") for (const kw of filtered) {
+		const intent = extractIntentPrefix(kw.query);
+		if (intent) {
+			const existing = clusterMap.get(intent);
+			if (existing) existing.keywords.push(kw);
+			else clusterMap.set(intent, {
+				type: "intent",
+				keywords: [kw]
+			});
+			clusteredKeywords.add(kw.query);
+		}
+	}
+	if (clusterBy === "prefix" || clusterBy === "both") {
+		const prefixMap = /* @__PURE__ */ new Map();
+		for (const kw of filtered) {
+			if (clusteredKeywords.has(kw.query)) continue;
+			const prefix = extractWordPrefix(kw.query);
+			if (prefix) {
+				const existing = prefixMap.get(prefix);
+				if (existing) existing.push(kw);
+				else prefixMap.set(prefix, [kw]);
+			}
+		}
+		for (const [prefix, kws] of prefixMap) if (kws.length >= minClusterSize) {
+			clusterMap.set(prefix, {
+				type: "prefix",
+				keywords: kws
+			});
+			for (const kw of kws) clusteredKeywords.add(kw.query);
+		}
+	}
+	const clusters = [];
+	for (const [name, data] of clusterMap) {
+		if (data.keywords.length < minClusterSize) continue;
+		let totalClicks = 0;
+		let totalImpressions = 0;
+		let weightedPositionSum = 0;
+		let positionWeight = 0;
+		let positionSum = 0;
+		for (const k of data.keywords) {
+			const impressions = num(k.impressions);
+			const position = num(k.position);
+			totalClicks += num(k.clicks);
+			totalImpressions += impressions;
+			positionSum += position;
+			if (impressions > 0) {
+				weightedPositionSum += (position - 1) * impressions;
+				positionWeight += impressions;
+			}
+		}
+		const avgPosition = positionWeight > 0 ? weightedPositionSum / positionWeight + 1 : positionSum / data.keywords.length;
+		clusters.push({
+			clusterName: name,
+			clusterType: data.type,
+			keywords: data.keywords,
+			totalClicks,
+			totalImpressions,
+			avgPosition,
+			keywordCount: data.keywords.length
+		});
+	}
+	clusters.sort((a, b) => b.totalClicks - a.totalClicks);
+	return {
+		clusters,
+		unclustered: filtered.filter((kw) => !clusteredKeywords.has(kw.query))
+	};
+}
+const clusteringAnalyzer = defineAnalyzer({
+	id: "clustering",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		const minImpressions = params.minImpressions ?? 10;
+		const minClusterSize = params.minClusterSize ?? 2;
+		const clusterBy = params.clusterBy ?? "both";
+		const doIntent = clusterBy === "intent" || clusterBy === "both";
+		const doPrefix = clusterBy === "prefix" || clusterBy === "both";
+		const intentExpr = doIntent ? `NULLIF(regexp_extract(LOWER(query), '${INTENT_PREFIXES_REGEX}', 1), '')` : `CAST(NULL AS VARCHAR)`;
+		const prefixExpr = doPrefix ? `CASE WHEN len(regexp_split_to_array(LOWER(query), '\\s+')) >= 3
+          THEN array_to_string(list_slice(regexp_split_to_array(LOWER(query), '\\s+'), 1, 2), ' ')
+          ELSE CAST(NULL AS VARCHAR) END` : `CAST(NULL AS VARCHAR)`;
+		return {
+			sql: `
+      WITH agg AS (
+        SELECT
+          query,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions,
+          ${METRIC_EXPR.ctr} AS ctr,
+          ${METRIC_EXPR.position} AS position
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY query
+        HAVING SUM(impressions) >= ?
+      ),
+      classified AS (
+        SELECT
+          query, clicks, impressions, ctr, position,
+          ${intentExpr} AS intent_prefix,
+          ${prefixExpr} AS word_prefix
+        FROM agg
+      ),
+      keyed AS (
+        SELECT
+          query, clicks, impressions, ctr, position,
+          COALESCE(intent_prefix, word_prefix) AS cluster_name,
+          CASE WHEN intent_prefix IS NOT NULL THEN 'intent' ELSE 'prefix' END AS cluster_type
+        FROM classified
+        WHERE COALESCE(intent_prefix, word_prefix) IS NOT NULL
+      )
+      SELECT
+        cluster_name AS clusterName,
+        any_value(cluster_type) AS clusterType,
+        CAST(COUNT(*) AS DOUBLE) AS keywordCount,
+        ${METRIC_EXPR.clicks} AS totalClicks,
+        ${METRIC_EXPR.impressions} AS totalImpressions,
+        SUM((position - 1) * impressions) / NULLIF(SUM(impressions), 0) + 1 AS avgPosition,
+        to_json(list({ 'query': query, 'clicks': clicks, 'impressions': impressions, 'ctr': ctr, 'position': position })) AS keywords
+      FROM keyed
+      GROUP BY cluster_name
+      HAVING COUNT(*) >= ?
+      ORDER BY totalClicks DESC
+    `,
+			params: [
+				startDate,
+				endDate,
+				minImpressions,
+				minClusterSize
+			],
+			current: {
+				table: "queries",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const clusters = (Array.isArray(rows) ? rows : []).map((r) => ({
+			clusterName: rowString(r.clusterName),
+			clusterType: rowString(r.clusterType),
+			keywordCount: num(r.keywordCount),
+			totalClicks: num(r.totalClicks),
+			totalImpressions: num(r.totalImpressions),
+			avgPosition: num(r.avgPosition),
+			keywords: parseJsonRows(r.keywords).map((k) => ({
+				query: rowString(k.query),
+				clicks: num(k.clicks),
+				impressions: num(k.impressions),
+				ctr: num(k.ctr),
+				position: num(k.position)
+			}))
+		}));
+		return {
+			results: clusters,
+			meta: {
+				total: clusters.length,
+				totalClusters: clusters.length
+			}
+		};
+	},
+	buildRows(params) {
+		return { queries: queriesQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		const result = analyzeClustering(Array.isArray(rows) ? rows : [], {
+			clusterBy: params.clusterBy,
+			minClusterSize: params.minClusterSize,
+			minImpressions: params.minImpressions
+		});
+		return {
+			results: result.clusters,
+			meta: { totalClusters: result.clusters.length }
+		};
+	}
+});
+export { analyzeClustering, clusteringAnalyzer };