@gscdump/engine 1.3.2 → 1.4.1

package/dist/resolver/index.d.mts

@@ -1,372 +1,12 @@
-import { SearchType as SearchType$1, TableName as TableName$1 } from "../_chunks/storage.mjs";
-import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverAdapter, ResolverOptions } from "../_chunks/types.mjs";
-import { LogicalDataset, LogicalDataset as LogicalDataset$1, PlannerCapabilities, UnresolvableDatasetError, inferDataset as inferLogicalDataset, isDatasetResolvable } from "gscdump/query/plan";
-import { SQL } from "drizzle-orm";
-import { BuilderState, Dimension, FilterInput, InternalFilter, Metric } from "gscdump/query";
-import { Grain, TableName } from "@gscdump/contracts";
-type DimensionSurface = 'api' | 'stored' | 'derived';
-interface DimensionBinding {
-  column: string;
-  surfaces: readonly DimensionSurface[];
-}
-interface LogicalDatasetDefinition {
-  dimensions: Partial<Record<Dimension, DimensionBinding>>;
-}
-declare const DIMENSION_SURFACES: Record<Dimension, readonly DimensionSurface[]>;
-declare const LOGICAL_DATASETS: Record<LogicalDataset, LogicalDatasetDefinition>;
-declare function dimensionColumn(dim: Dimension, dataset: LogicalDataset): string;
-declare function supportsDimensionOnSurface(dim: Dimension, surface: DimensionSurface): boolean;
-declare function assertDimensionsSupported(dimensions: readonly Dimension[], surface: DimensionSurface, context: string): void;
-interface SqlFragmentsConfig<TableKey extends string> {
-  schema: Record<TableKey, unknown>;
-  datasetToTableKey: Record<keyof typeof LOGICAL_DATASETS, TableKey>;
-  metricCast: 'REAL' | 'DOUBLE';
-  regexPredicate: (expr: SQL, pattern: string, negate: boolean) => SQL;
-  tableLabel: string;
-  includeSiteId: boolean;
-  includeSearchType?: boolean;
-  urlToPathExpr?: (col: string) => string;
-  /**
-   * Override the FROM-clause table reference. Default emits the bound drizzle
-   * table (e.g. `"pages"`). Parquet/R2 adapter overrides this to emit
-   * `read_parquet({{FILES}}, ...) AS "${tk}"` so the runSQL pipeline can swap
-   * in an object-key list while column refs (`"pages"."url"`) still resolve
-   * against the alias.
-   */
-  tableRef?: (tableKey: TableKey) => SQL;
-  /**
-   * Where `queryCanonical` comes from when compiling fact-table reads.
-   *
-   * - `queryDim` (default): LEFT JOIN a query dimension relation and derive
-   *   `COALESCE(query_dim.query_canonical, fact.query)`.
-   * - `column`: read a `query_canonical` column from the primary relation. This
-   *   is reserved for derived canonical rollup relations, not fact tables.
-   */
-  queryCanonicalSource?: 'queryDim' | 'column';
-  /** Relation used for the query-dimension join when `queryCanonicalSource=queryDim`. */
-  queryDimTableRef?: () => SQL;
-  /** When true, also joins query_dim on site_id (SQLite/D1 dimension table). */
-  queryDimSiteScoped?: boolean;
-}
-interface SqlFragments<TableKey extends string> {
-  METRIC_NAMES: Metric[];
-  DIM_COLUMN_MAP: Record<TableKey, Record<string, string>>;
-  isMetricDimension: (dim: string) => dim is Metric;
-  tableKeyForDataset: (dataset: LogicalDataset$1) => TableKey;
-  dimColumn: (dim: Dimension, table: TableKey) => string;
-  inferTable: (dimensions: Dimension[], filterDims?: Dimension[]) => TableKey;
-  urlToPathExpr: (col: string) => string;
-  colRef: (tableKey: TableKey, colName: string) => SQL;
-  tableRef: (tableKey: TableKey) => SQL;
-  fromSql: (tableKey: TableKey, options?: {
-    queryCanonical?: boolean;
-  }) => SQL;
-  dateColRef: (tableKey: TableKey) => SQL;
-  siteIdColRef?: (tableKey: TableKey) => SQL;
-  searchTypeColRef?: (tableKey: TableKey) => SQL;
-  dimExprSql: (dim: Dimension, tableKey: TableKey) => SQL;
-  metricSql: (metric: Metric, tableKey: TableKey) => SQL;
-  havingPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
-  prefilterPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
-  dimensionPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
-  topLevelPredicate: (filters: InternalFilter[], tableKey: TableKey) => SQL | undefined;
-}
-declare function createSqlFragments<TableKey extends string>(config: SqlFragmentsConfig<TableKey>): SqlFragments<TableKey>;
-interface CreateResolverAdapterConfig<TableKey extends string> extends SqlFragmentsConfig<TableKey> {
-  compile: (query: SQL) => {
-    sql: string;
-    params: unknown[];
-  };
-  capabilities: PlannerCapabilities;
-}
-declare function createResolverAdapter<TableKey extends string>(config: CreateResolverAdapterConfig<TableKey>): ResolverAdapter<TableKey>;
-/** State-level convenience: build the plan then gate. */
-declare function canonicalRollupCovers(state: BuilderState, capabilities: PlannerCapabilities): boolean;
-declare function resolveToSQLOptimized<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQLOptimized;
-declare function resolveToSQL<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQL;
-declare function buildTotalsSql<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): {
-  sql: string;
-  params: unknown[];
-};
-declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter): ResolvedComparisonSQL;
-declare function buildExtrasQueries<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ExtraQuery[];
-declare function mergeExtras(rows: Record<string, unknown>[], extrasResults: {
-  key: string;
-  results: Record<string, unknown>[];
-}[]): Record<string, unknown>[];
-interface RunQueryCtx {
-  userId: string;
-  siteId: string;
-  table: TableName$1;
-  searchType?: SearchType$1;
-  /**
-   * Temporal granularity. `'day'` (default) drives `enumeratePartitions` to
-   * emit `daily/{date}` only; hourly partitions are skipped by construction.
-   * `'hour'` is reserved for hourly read paths and must use the dedicated
-   * hourly query surface (callers pass `partitions: [hourly/{date}]`
-   * directly through `runSQL`).
-   */
-  grain?: Grain;
-}
-interface RunSQLFn {
-  (opts: {
-    ctx: {
-      userId: string;
-      siteId: string;
-    };
-    table: TableName$1;
-    fileSets: Record<string, {
-      table: TableName$1;
-      partitions?: string[];
-      keys?: string[];
-    }>;
-    sql: string;
-    params: unknown[];
-    searchType?: SearchType$1;
-  }): Promise<{
-    rows: Array<Record<string, unknown>>;
-  }>;
-}
-interface CanonicalQueryDimSource {
-  /** Object keys for the versioned query_dim parquet. */
-  keys: string[];
-  normalizerVersion: number;
-  intentVersion?: number;
-  builtAt?: number;
-}
-interface PrimaryColumnarSource {
-  /** Pre-resolved compacted/Iceberg parquet object keys for the requested fact table. */
-  keys: string[];
-  /** Oldest covered date (`YYYY-MM-DD`). Omit to assert the source covers all older dates. */
-  coversFrom?: string;
-  /** Newest covered date (`YYYY-MM-DD`). Omit to assert the source covers the current tail. */
-  coversThrough?: string;
-}
-/**
- * Optional overlay that serves a resolver extra (e.g. canonical-variant
- * grouping, keyed `'canonicalExtras'`) from a precomputed source — typically a
- * materialised rollup — instead of the live window-function SQL. Return the
- * rows in the exact shape the live extra produces (`mergeExtras` consumes
- * either source unchanged), or `null` to decline so the caller falls back to
- * the live query. Pure seam: storage/tenant routing lives in the host's
- * implementation, not here. See ADR-0017.
- */
-interface ResolveExtraFn {
-  (opts: {
-    key: string;
-    state: BuilderState;
-    ctx: RunQueryCtx;
-    dateRange: {
-      startDate: string;
-      endDate: string;
-    };
-  }): Promise<Array<Record<string, unknown>> | null>;
-}
-interface RunOptimizedQueryOptions {
-  /** Overlay tried per extra before the live SQL; absent → today's live path. */
-  resolveExtra?: ResolveExtraFn;
-  /**
-   * Versioned query dimension backing canonical reads over fact rows. Required
-   * whenever a query groups or filters by `queryCanonical`; a canonical rollup
-   * source may carry the same metadata/key set via `canonicalSource.queryDim`.
-   */
-  queryDim?: CanonicalQueryDimSource;
-  /**
-   * Primary fact-file source for consumer reads. Callers pass compacted or
-   * Iceberg data-file keys with explicit coverage metadata; raw daily
-   * partitions are only used when `primarySourceFallback: 'raw'` is set.
-   */
-  primarySource?: PrimaryColumnarSource;
-  /**
-   * Explicit compatibility escape hatch for raw daily shards. Default is
-   * strict: missing/empty/stale primary coverage fails with
-   * `QuerySourceCoverageError`.
-   */
-  primarySourceFallback?: 'raw';
-  /**
-   * Opt-in canonical-primary performance (ADR-0018 Gap 2): object keys of the
-   * `query_canonical_daily` rollup parquet(s). When supplied AND the query is
-   * coverable (`canonicalRollupCovers`) AND the window is within the rollup's
-   * coverage, the MAIN query reads these
-   * pre-summed `(query_canonical × date)` rows instead of re-aggregating raw
-   * partitions. Variant extras still need fact-grain rows, so they read
-   * `primarySource` when present and raw partitions only via
-   * `primarySourceFallback: 'raw'`.
-   *
-   * `coversThrough` (ISO `YYYY-MM-DD`, the rollup's newest covered date) gates
-   * staleness: the source is used only when `dateRange.endDate <= coversThrough`,
-   * else strict mode fails so the recent tail is never silently undercounted.
-   * Omit to assert full coverage (use with care).
-   */
-  canonicalSource?: {
-    keys: string[];
-    coversThrough?: string;
-    queryDim?: CanonicalQueryDimSource;
-  };
-  /** Optional version gates for the query dimension backing `canonicalSource`. */
-  canonicalRequirements?: {
-    normalizerVersion?: number;
-    intentVersion?: number;
-  };
-}
-type QuerySourceKind = 'canonical-rollup' | 'primary-columnar' | 'raw-partitions';
-type QuerySourceFallbackKind = 'primary-source-missing' | 'primary-source-empty' | 'primary-source-missing-coverage' | 'primary-source-stale-coverage' | 'canonical-source-missing' | 'canonical-source-empty' | 'canonical-source-not-coverable' | 'canonical-source-stale-coverage' | 'query-dim-missing' | 'query-dim-empty' | 'query-dim-stale-version';
-interface QuerySourceFallback {
-  kind: QuerySourceFallbackKind;
-  message: string;
-}
-interface QuerySourceDecision {
-  kind: QuerySourceKind;
-  fallback?: QuerySourceFallback;
-  fallbacks?: QuerySourceFallback[];
-}
-declare class QuerySourceCoverageError extends Error {
-  readonly fallback: QuerySourceFallback;
-  name: string;
-  constructor(fallback: QuerySourceFallback);
-}
-interface OptimizedQueryResult {
-  rows: Array<Record<string, unknown>>;
-  totalCount: number;
-  totals: {
-    clicks: number;
-    impressions: number;
-    ctr: number;
-    position: number;
-  };
-  extras: Array<{
-    key: string;
-    rows: Array<Record<string, unknown>>;
-  }>;
-  source: QuerySourceDecision;
-  extraSource?: QuerySourceDecision;
-}
-interface ComparisonQueryResult {
-  rows: Array<Record<string, unknown>>;
-  totalCount: number;
-  totals: Record<string, unknown>;
-  source: QuerySourceDecision;
-}
-declare function runOptimizedQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, state: BuilderState, dateRange: {
-  startDate: string;
-  endDate: string;
-}, options?: RunOptimizedQueryOptions): Promise<OptimizedQueryResult>;
-declare function runComparisonQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, current: BuilderState, previous: BuilderState, windows: {
-  current: {
-    startDate: string;
-    endDate: string;
-  };
-  previous: {
-    startDate: string;
-    endDate: string;
-  };
-}, filter?: ComparisonFilter, options?: RunOptimizedQueryOptions): Promise<ComparisonQueryResult>;
-/**
- * Host-supplied reader: return the materialised rollup's rows for an
- * `(id, tenant, slice)`, in the exact shape the live extra produces, or `null`
- * when no rollup exists (first sync, never built, stale) so the overlay
- * declines and the resolver falls back to the live query. Typically wired with
- * `readLatestRollup` + a `read_parquet` of the pointer.
- *
- * `dateRange` is the request window. `query_canonical_variants` is full-history
- * (its grouping/variant metrics span all dates), but `buildExtrasQueries`
- * windows the live `canonicalExtras` to the requested range — so for a narrow
- * window the reader MUST decline (return `null`) rather than attach
- * out-of-window variantCount/canonicalName/variants. A common rule: serve only
- * when the request window covers full history.
- */
-interface RollupRowsReader {
-  (opts: {
-    id: string;
-    ctx: {
-      userId: string;
-      siteId: string;
-    };
-    searchType?: SearchType$1;
-    dateRange: {
-      startDate: string;
-      endDate: string;
-    };
-  }): Promise<Array<Record<string, unknown>> | null>;
-}
-/**
- * Build a {@link ResolveExtraFn} that serves resolver extras from materialised
- * rollups when one is mapped for the extra's key, else returns `null` to fall
- * back to the live SQL. Pure wiring around the host's `readRollupRows`.
- */
-declare function createRollupExtrasOverlay(readRollupRows: RollupRowsReader): ResolveExtraFn;
-declare function getInternalFilters(filter: FilterInput | undefined): InternalFilter[];
-declare function getDimensionFilters(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): InternalFilter[];
-declare function getFilterDimensions(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): Dimension[];
-declare function metricValue(row: Record<string, unknown>, metric: string): number;
-declare function dimensionValue(row: Record<string, unknown>, dimension: string): string;
-declare function matchesDimensionFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
-declare function matchesMetricFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
-declare function matchesTopLevelPage(row: Record<string, unknown>): boolean;
-type PgTableKey = TableName;
-declare const pgResolverAdapter: ResolverAdapter<PgTableKey>;
-/**
- * Parquet-aware variant of {@link pgResolverAdapter}. Identical SQL output
- * except FROM clauses emit `read_parquet({{FILES}}, union_by_name = true) AS
- * "${tk}"`. The runSQL pipeline substitutes `{{FILES}}` with R2 object keys
- * resolved from the manifest. The `AS "${tk}"` alias is mandatory — drizzle
- * compiles `colRef` to table-qualified `"pages"."url"`, which would not
- * resolve against an unaliased FROM.
- *
- * Single-use: build a fresh adapter per query. Cheap (no I/O) and avoids
- * accidental adapter caching that would lock in a stale `{{FILES}}` set.
- */
-interface ResolverAdapterOptions {
-  /**
-   * `queryDim` reads canonical from a joined query dimension. `column` is only
-   * for derived canonical rollup relations whose primary relation already
-   * carries a null-free `query_canonical` output column.
-   */
-  queryCanonicalSource?: 'queryDim' | 'column';
-}
-interface R2SqlResolverAdapterOptions extends ResolverAdapterOptions {
-  /**
-   * R2 SQL string partition equality can undercount on identity partitions;
-   * string-encoded catalogs use CONCAT(col, '') in partition predicates. Int
-   * catalogs do not need the workaround and keep bare equality for pruning.
-   */
-  partitionKeyEncoding?: 'string' | 'int';
-}
-declare function createParquetResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
-/**
- * Multi-tenant pg-flavored adapter for the Iceberg / R2 SQL read path.
- * Identical SQL output to `pgResolverAdapter` except WHERE clauses inject
- * `site_id = ?` AND `search_type = ?` automatically when those scopes are
- * passed to `resolveToSQL`. Required for the Iceberg fact tables which are
- * shared across tenants — querying without these predicates would leak
- * cross-tenant data. Single-use: the adapter has no `tableRef` override,
- * so callers must rewrite bare table names to their qualified form (e.g.
- * `${namespace}.pages`) before sending to R2 SQL.
- */
-declare function createIcebergResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
-/**
- * R2 SQL adapter for the Iceberg fact tables.
- *
- * It shares the multi-tenant Iceberg schema with `createIcebergResolverAdapter`
- * but models R2 SQL's narrower execution surface: no window-total plans and no
- * comparison joins. Int-partition catalogs are the default and emit bare
- * equality predicates for pruning. Legacy string-partition catalogs must pass
- * `partitionKeyEncoding: 'string'` to emit `CONCAT(partition_col, '') = ?`,
- * working around R2 SQL's partition-string equality undercount while preserving
- * bound params.
- */
-declare function createR2SqlResolverAdapter(options?: R2SqlResolverAdapterOptions): ResolverAdapter<PgTableKey>;
-interface AssertSchemaInSyncOptions {
-  /** Label used in the thrown error (e.g. 'browser', 'sqlite'). */
-  label: string;
-  /** Drizzle schema keyed by table name. For sqlite, strip the `gsc_` prefix before passing. */
-  schema: Record<string, unknown>;
-  /**
-   * Map drizzle table key → canonical `TableName`. For browser this is identity;
-   * for sqlite this strips the `gsc_` prefix.
-   */
-  tableKeyToName: (key: string) => TableName;
-  mode: 'exact' | 'superset';
-}
-declare function assertSchemaInSync(options: AssertSchemaInSyncOptions): void;
+import { ComparisonFilter, 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";
+import { canonicalRollupCovers } from "./canonical-source.mjs";
+import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "./compile.mjs";
+import { CanonicalQueryDimSource, ComparisonQueryResult, OptimizedQueryResult, PrimaryColumnarSource, QuerySourceCoverageError, QuerySourceDecision, QuerySourceFallback, QuerySourceFallbackKind, QuerySourceKind, ResolveExtraFn, RunOptimizedQueryOptions, RunQueryCtx, RunSQLFn, runComparisonQuery, runOptimizedQuery } from "./run-query.mjs";
+import { RollupRowsReader, createRollupExtrasOverlay } from "./extras-overlay.mjs";
+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 };

package/dist/resolver/index.mjs

@@ -1,2 +1,11 @@
-import { DIMENSION_SURFACES, LOGICAL_DATASETS, QuerySourceCoverageError, 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 } from "../_chunks/resolver.mjs";
+import { DIMENSION_SURFACES, LOGICAL_DATASETS, UnresolvableDatasetError, assertDimensionsSupported, dimensionColumn, inferLogicalDataset, isDatasetResolvable, supportsDimensionOnSurface } from "./datasets.mjs";
+import { createSqlFragments } from "./fragments.mjs";
+import { createResolverAdapter } from "./adapter.mjs";
+import { canonicalRollupCovers } from "./canonical-source.mjs";
+import { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized } from "./compile.mjs";
+import { createRollupExtrasOverlay } from "./extras-overlay.mjs";
+import { dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue } from "./filter-utils.mjs";
+import { createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter } from "./pg-adapter.mjs";
+import { QuerySourceCoverageError, runComparisonQuery, runOptimizedQuery } from "./run-query.mjs";
+import { assertSchemaInSync } from "./schema-drift.mjs";
 export { DIMENSION_SURFACES, LOGICAL_DATASETS, QuerySourceCoverageError, 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/pg-adapter.d.mts

@@ -0,0 +1,56 @@
+import { ResolverAdapter } from "./types.mjs";
+import { TableName } from "@gscdump/contracts";
+type PgTableKey = TableName;
+declare const pgResolverAdapter: ResolverAdapter<PgTableKey>;
+/**
+ * Parquet-aware variant of {@link pgResolverAdapter}. Identical SQL output
+ * except FROM clauses emit `read_parquet({{FILES}}, union_by_name = true) AS
+ * "${tk}"`. The runSQL pipeline substitutes `{{FILES}}` with R2 object keys
+ * resolved from the manifest. The `AS "${tk}"` alias is mandatory — drizzle
+ * compiles `colRef` to table-qualified `"pages"."url"`, which would not
+ * resolve against an unaliased FROM.
+ *
+ * Single-use: build a fresh adapter per query. Cheap (no I/O) and avoids
+ * accidental adapter caching that would lock in a stale `{{FILES}}` set.
+ */
+interface ResolverAdapterOptions {
+  /**
+   * `queryDim` reads canonical from a joined query dimension. `column` is only
+   * for derived canonical rollup relations whose primary relation already
+   * carries a null-free `query_canonical` output column.
+   */
+  queryCanonicalSource?: 'queryDim' | 'column';
+}
+interface R2SqlResolverAdapterOptions extends ResolverAdapterOptions {
+  /**
+   * R2 SQL string partition equality can undercount on identity partitions;
+   * string-encoded catalogs use CONCAT(col, '') in partition predicates. Int
+   * catalogs do not need the workaround and keep bare equality for pruning.
+   */
+  partitionKeyEncoding?: 'string' | 'int';
+}
+declare function createParquetResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
+/**
+ * Multi-tenant pg-flavored adapter for the Iceberg / R2 SQL read path.
+ * Identical SQL output to `pgResolverAdapter` except WHERE clauses inject
+ * `site_id = ?` AND `search_type = ?` automatically when those scopes are
+ * passed to `resolveToSQL`. Required for the Iceberg fact tables which are
+ * shared across tenants — querying without these predicates would leak
+ * cross-tenant data. Single-use: the adapter has no `tableRef` override,
+ * so callers must rewrite bare table names to their qualified form (e.g.
+ * `${namespace}.pages`) before sending to R2 SQL.
+ */
+declare function createIcebergResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
+/**
+ * R2 SQL adapter for the Iceberg fact tables.
+ *
+ * It shares the multi-tenant Iceberg schema with `createIcebergResolverAdapter`
+ * but models R2 SQL's narrower execution surface: no window-total plans and no
+ * comparison joins. Int-partition catalogs are the default and emit bare
+ * equality predicates for pruning. Legacy string-partition catalogs must pass
+ * `partitionKeyEncoding: 'string'` to emit `CONCAT(partition_col, '') = ?`,
+ * working around R2 SQL's partition-string equality undercount while preserving
+ * bound params.
+ */
+declare function createR2SqlResolverAdapter(options?: R2SqlResolverAdapterOptions): ResolverAdapter<PgTableKey>;
+export { PgTableKey, R2SqlResolverAdapterOptions, ResolverAdapterOptions, createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter };

package/dist/resolver/pg-adapter.mjs

@@ -0,0 +1,110 @@
+import { drizzleSchema } from "../drizzle-schema.mjs";
+import { createResolverAdapter } from "./adapter.mjs";
+import { PgDialect, pgTable, varchar } from "drizzle-orm/pg-core";
+import { DEFAULT_PARTITION_KEY_ENCODING } from "@gscdump/lakehouse/schema";
+import { sql } from "drizzle-orm";
+const pgDialect = new PgDialect();
+function withTenantCols(tableName, baseTable) {
+	const t = pgTable(tableName, {
+		site_id: varchar("site_id").notNull(),
+		search_type: varchar("search_type").notNull()
+	});
+	return {
+		...baseTable,
+		site_id: t.site_id,
+		search_type: t.search_type
+	};
+}
+const icebergSchema = {
+	pages: withTenantCols("pages", drizzleSchema.pages),
+	queries: withTenantCols("queries", drizzleSchema.queries),
+	countries: withTenantCols("countries", drizzleSchema.countries),
+	page_queries: withTenantCols("page_queries", drizzleSchema.page_queries),
+	dates: withTenantCols("dates", drizzleSchema.dates),
+	search_appearance: withTenantCols("search_appearance", drizzleSchema.search_appearance),
+	search_appearance_pages: withTenantCols("search_appearance_pages", drizzleSchema.search_appearance_pages),
+	search_appearance_queries: withTenantCols("search_appearance_queries", drizzleSchema.search_appearance_queries),
+	search_appearance_page_queries: withTenantCols("search_appearance_page_queries", drizzleSchema.search_appearance_page_queries),
+	hourly_pages: withTenantCols("hourly_pages", drizzleSchema.hourly_pages)
+};
+function compilePg(query) {
+	const compiled = pgDialect.sqlToQuery(query);
+	return {
+		sql: compiled.sql,
+		params: compiled.params
+	};
+}
+const PG_BASE_CONFIG = {
+	schema: drizzleSchema,
+	datasetToTableKey: {
+		pages: "pages",
+		queries: "queries",
+		page_queries: "page_queries",
+		countries: "countries",
+		dates: "dates",
+		search_appearance: "search_appearance",
+		search_appearance_pages: "search_appearance_pages",
+		search_appearance_queries: "search_appearance_queries",
+		search_appearance_page_queries: "search_appearance_page_queries",
+		hourly_pages: "hourly_pages"
+	},
+	metricCast: "DOUBLE",
+	regexPredicate: (expr, pattern, negate) => negate ? sql`NOT regexp_matches(${expr}, ${pattern})` : sql`regexp_matches(${expr}, ${pattern})`,
+	urlToPathExpr: (col) => `CASE WHEN ${col} LIKE 'http%' THEN COALESCE(NULLIF(regexp_replace(${col}, '^https?://[^/]+', ''), ''), '/') ELSE ${col} END`,
+	includeSiteId: false,
+	compile: compilePg,
+	capabilities: {
+		regex: true,
+		comparisonJoin: true,
+		windowTotals: true
+	}
+};
+const pgResolverAdapter = createResolverAdapter({
+	...PG_BASE_CONFIG,
+	tableLabel: "pg-resolver-adapter"
+});
+function createParquetResolverAdapter(options = {}) {
+	return createResolverAdapter({
+		...PG_BASE_CONFIG,
+		tableLabel: "parquet-resolver-adapter",
+		queryCanonicalSource: options.queryCanonicalSource ?? "queryDim",
+		tableRef: (tk) => sql.raw(`read_parquet({{FILES}}, union_by_name = true) AS "${tk}"`),
+		queryDimTableRef: () => sql.raw("read_parquet({{QUERY_DIM}}, union_by_name = true) AS \"query_dim\"")
+	});
+}
+function createIcebergResolverAdapter(options = {}) {
+	return createResolverAdapter({
+		...PG_BASE_CONFIG,
+		schema: icebergSchema,
+		includeSiteId: true,
+		includeSearchType: true,
+		tableLabel: "iceberg-resolver-adapter",
+		queryCanonicalSource: options.queryCanonicalSource ?? "queryDim",
+		tableRef: (tk) => sql.raw(`"${tk}"`),
+		queryDimTableRef: () => sql.raw("\"query_dim\"")
+	});
+}
+function createR2SqlResolverAdapter(options = {}) {
+	const adapter = createResolverAdapter({
+		...PG_BASE_CONFIG,
+		schema: icebergSchema,
+		includeSiteId: true,
+		includeSearchType: true,
+		tableLabel: "r2-sql-resolver-adapter",
+		queryCanonicalSource: options.queryCanonicalSource ?? "queryDim",
+		capabilities: {
+			regex: false,
+			comparisonJoin: false,
+			windowTotals: false
+		},
+		tableRef: (tk) => sql.raw(`"${tk}"`),
+		queryDimTableRef: () => sql.raw("\"query_dim\"")
+	});
+	if ((options.partitionKeyEncoding ?? DEFAULT_PARTITION_KEY_ENCODING) === "int") return adapter;
+	return {
+		...adapter,
+		siteIdColRef: (tk) => sql`CONCAT(${adapter.siteIdColRef(tk)}, '')`,
+		searchTypeColRef: (tk) => sql`CONCAT(${adapter.searchTypeColRef(tk)}, '')`
+	};
+}
+export { createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter };