drizzle-cube 0.7.1 → 0.8.1

package/dist/cjs/server/query-validator.d.ts

@@ -1,9 +1,41 @@
 import { SemanticQuery, Cube } from './types/index.js';
 /**
- * Validate a query against a cubes map
- * Standalone function that can be used by both compiler and executor
+ * A member the query references that no cube provides, reported alongside the
+ * human-readable errors.
+ *
+ * The joined error string cannot be split back apart reliably — the per-field
+ * "did you mean" hints contain the same separator — so a caller that wants to
+ * react to a *specific* missing member (a dashboard dropping a column for a
+ * deleted attribute, say) needs this rather than the prose. `source` is the
+ * part that matters: dropping a projected member narrows what is displayed,
+ * whereas dropping a filter would widen the result set, so the two cannot be
+ * treated alike.
+ */
+export interface QueryValidationIssue {
+    source: 'measure' | 'dimension' | 'timeDimension' | 'filter';
+    /** The full `Cube.field` reference as the query wrote it. */
+    member: string;
+    message: string;
+}
+/**
+ * Thrown when a query fails validation during execution.
+ *
+ * Carries the structured issues alongside the joined message so a caller can
+ * react to a specific unknown member — the batch endpoint, which validates
+ * inside execution rather than ahead of it, would otherwise only have prose.
  */
-export declare function validateQueryAgainstCubes(cubes: Map<string, Cube>, query: SemanticQuery): {
+export declare class QueryValidationError extends Error {
+    readonly issues: QueryValidationIssue[];
+    constructor(message: string, issues: QueryValidationIssue[]);
+}
+export interface QueryValidationResult {
     isValid: boolean;
     errors: string[];
-};
+    /** Unknown members, when any — see {@link QueryValidationIssue}. */
+    issues: QueryValidationIssue[];
+}
+/**
+ * Validate a query against a cubes map
+ * Standalone function that can be used by both compiler and executor
+ */
+export declare function validateQueryAgainstCubes(cubes: Map<string, Cube>, query: SemanticQuery): QueryValidationResult;

package/dist/cjs/server/types/core.d.ts

@@ -57,6 +57,11 @@ export interface QueryResult {
     };
     /** Warnings about potential query issues (e.g., fan-out without dimensions) */
     warnings?: QueryWarning[];
+    /**
+     * Total rows the query would return with no limit/offset, present only when
+     * the query asked for it with `total: true`.
+     */
+    total?: number;
 }
 /**
  * Period comparison metadata for compareDateRange queries
@@ -85,6 +90,14 @@ export interface SqlResult {
 export interface ExecutionOptions {
     /** Skip the cache lookup (but still cache the result for future requests) */
     skipCache?: boolean;
+    /**
+     * Identifies the cube definitions that produced the result, as
+     * `setId:baseGeneration.setGeneration`. Appended unconditionally to the query
+     * cache key so results can never be shared between tenants whose cube sets
+     * differ, nor survive a re-registration that changed a definition.
+     * Set by SemanticLayerCompiler; callers do not supply it.
+     */
+    cubeSetKey?: string;
 }
 /**
  * Core database interface that supports all Drizzle instances

package/dist/cjs/server/types/cube.d.ts

@@ -64,6 +64,19 @@ export interface QueryContext {
      * without aggregation wrappers. Set from SemanticQuery.ungrouped.
      */
     ungrouped?: boolean;
+    /**
+     * Cast an expression to a type, in this engine's dialect (`::decimal` on
+     * Postgres, `CAST(... AS DECIMAL)` elsewhere). Strict: unparseable input
+     * fails the query on Postgres and silently yields `0` on MySQL/SQLite.
+     */
+    cast: (fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer') => SQL;
+    /**
+     * Cast an expression to a type, yielding NULL rather than failing when the
+     * input cannot be parsed. Use this over {@link QueryContext.cast} whenever
+     * the source column is free text — one dirty value should leave a row with a
+     * NULL cell, not fail the whole query.
+     */
+    tryCast: (fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer') => SQL;
 }
 /**
  * Multi-cube query context for cross-cube operations
@@ -147,7 +160,25 @@ export interface Dimension {
     sql: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
     /** Whether this is a primary key */
     primaryKey?: boolean;
-    /** Whether to show in UI */
+    /**
+     * The column this dimension's SQL correlates on, for dimensions built from a
+     * correlated subquery (see `buildAttributeDimensions`).
+     *
+     * A correlated subquery in the SELECT list is only legal under GROUP BY when
+     * the column it correlates on is itself grouped: Postgres otherwise rejects
+     * the query with "subquery uses ungrouped column … from outer query", and
+     * MySQL does the same under `only_full_group_by`. The planner cannot see
+     * inside an opaque `sql` function, so a dimension that needs this declares it
+     * and the GROUP BY builder adds the key.
+     */
+    correlatesOn?: AnyColumn;
+    /**
+     * Whether to include this dimension in generated cube metadata (`/meta`,
+     * the client field picker, AI prompts). Defaults to `true` (shown) when
+     * omitted. Setting `shown: false` hides the dimension from metadata/UI
+     * only — it remains fully usable in queries and filters, matching Cube.js
+     * semantics for `shown: false`.
+     */
     shown?: boolean;
     /** Display format */
     format?: string;
@@ -182,7 +213,13 @@ export interface Measure {
     sql?: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
     /** Display format */
     format?: string;
-    /** Whether to show in UI */
+    /**
+     * Whether to include this measure in generated cube metadata (`/meta`,
+     * the client field picker, AI prompts). Defaults to `true` (shown) when
+     * omitted. Setting `shown: false` hides the measure from metadata/UI
+     * only — it remains fully usable in queries and filters, matching Cube.js
+     * semantics for `shown: false`.
+     */
     shown?: boolean;
     /** Filters applied to this measure */
     filters?: Array<(ctx: QueryContext) => SQL>;

package/dist/cjs/server/types/query.d.ts

@@ -32,6 +32,14 @@ export interface SemanticQuery {
      * - Incompatible with compareDateRange and fillMissingDates
      */
     ungrouped?: boolean;
+    /**
+     * Return the number of rows the query would produce with no `limit` or
+     * `offset` applied, as `QueryResult.total`. Matches Cube's `total`.
+     *
+     * Costs a second round trip: the same plan is rebuilt without pagination and
+     * counted, wrapped so a grouped query counts groups rather than base rows.
+     */
+    total?: boolean;
     /**
      * Funnel analysis configuration for query-time funnel definition.
      * When specified, the query executes as a funnel analysis instead of

package/dist/cli/index.cjs

@@ -32,38 +32,139 @@ node_path = __toESM(node_path, 1);
 *
 * Provides scaffolding for custom chart plugins.
 */
+/**
+* Built-in charts the CLI can scaffold from, keyed by chart type.
+*
+* Deliberately the CLI's own table rather than something derived from
+* `chartRegistry`: the CLI ships as a standalone CJS bundle (`build:cli`) and
+* importing the registry at runtime would pull the whole chart-config graph —
+* and its i18n keys, which this plain-text listing would then have to resolve —
+* into it. The `BuiltInChartType` import is type-only, so the bundle stays clean
+* while the record stays **exhaustive**: adding a chart type fails
+* `npm run typecheck` here until it is either given an entry or explicitly
+* marked `null`, which is the decision this table exists to force.
+*
+* `null` means "not offered as a scaffolding starting point"; give it a
+* `ScaffoldableChart` to enable it.
+*/
 var BUILT_IN_CHARTS = {
-	bar: "Bar chart — compare values across categories",
-	line: "Line chart — show trends over time",
-	area: "Area chart — line chart with filled areas",
-	pie: "Pie chart — show proportions of a whole",
-	scatter: "Scatter chart — show relationships between two measures",
-	bubble: "Bubble chart — scatter with size dimension",
-	radar: "Radar chart — multi-axis comparison",
-	radialBar: "Radial bar chart — circular bar chart",
-	treemap: "Treemap — hierarchical data as nested rectangles",
-	table: "Data table — sortable tabular display",
-	activityGrid: "Activity grid — GitHub-style contribution calendar",
-	kpiNumber: "KPI number — single metric display",
-	kpiDelta: "KPI delta — metric with change indicator",
-	kpiText: "KPI text — text-based metric",
-	funnel: "Funnel chart — conversion funnel visualization",
-	sankey: "Sankey diagram — flow visualization",
-	sunburst: "Sunburst chart — hierarchical pie chart",
-	heatmap: "Heatmap — color-coded matrix",
-	boxPlot: "Box plot — statistical distribution",
-	waterfall: "Waterfall chart — cumulative values",
-	candlestick: "Candlestick chart — financial OHLC data",
-	gauge: "Gauge — meter-style value display",
-	measureProfile: "Measure profile — detailed measure analysis"
+	bar: {
+		file: "BarChart",
+		description: "Bar chart — compare values across categories"
+	},
+	line: {
+		file: "LineChart",
+		description: "Line chart — show trends over time"
+	},
+	area: {
+		file: "AreaChart",
+		description: "Area chart — line chart with filled areas"
+	},
+	pie: {
+		file: "PieChart",
+		description: "Pie chart — show proportions of a whole"
+	},
+	scatter: {
+		file: "ScatterChart",
+		description: "Scatter chart — show relationships between two measures"
+	},
+	bubble: {
+		file: "BubbleChart",
+		description: "Bubble chart — scatter with size dimension"
+	},
+	radar: {
+		file: "RadarChart",
+		description: "Radar chart — multi-axis comparison"
+	},
+	radialBar: {
+		file: "RadialBarChart",
+		description: "Radial bar chart — circular bar chart"
+	},
+	treemap: {
+		file: "TreeMapChart",
+		description: "Treemap — hierarchical data as nested rectangles"
+	},
+	table: {
+		file: "DataTable",
+		description: "Data table — sortable tabular display"
+	},
+	recordsTable: {
+		file: "RecordsTable",
+		description: "Records table — record listing with per-column formats and links"
+	},
+	activityGrid: {
+		file: "ActivityGridChart",
+		description: "Activity grid — GitHub-style contribution calendar"
+	},
+	kpiNumber: {
+		file: "KpiNumber",
+		description: "KPI number — single metric display"
+	},
+	kpiDelta: {
+		file: "KpiDelta",
+		description: "KPI delta — metric with change indicator"
+	},
+	kpiText: {
+		file: "KpiText",
+		description: "KPI text — text-based metric"
+	},
+	funnel: {
+		file: "FunnelChart",
+		description: "Funnel chart — conversion funnel visualization"
+	},
+	sankey: {
+		file: "SankeyChart",
+		description: "Sankey diagram — flow visualization"
+	},
+	sunburst: {
+		file: "SunburstChart",
+		description: "Sunburst chart — hierarchical pie chart"
+	},
+	heatmap: {
+		file: "HeatMapChart",
+		description: "Heatmap — color-coded matrix"
+	},
+	boxPlot: {
+		file: "BoxPlotChart",
+		description: "Box plot — statistical distribution"
+	},
+	waterfall: {
+		file: "WaterfallChart",
+		description: "Waterfall chart — cumulative values"
+	},
+	candlestick: {
+		file: "CandlestickChart",
+		description: "Candlestick chart — financial OHLC data"
+	},
+	gauge: {
+		file: "GaugeChart",
+		description: "Gauge — meter-style value display"
+	},
+	measureProfile: {
+		file: "MeasureProfileChart",
+		description: "Measure profile — detailed measure analysis"
+	},
+	markdown: null,
+	retentionHeatmap: null,
+	retentionCombined: null,
+	proportionBar: null
 };
+/** Resolve a `--from` argument (an arbitrary string) to a scaffoldable chart. */
+function lookupScaffold(chartType) {
+	return scaffoldableCharts().find(([type]) => type === chartType)?.[1] ?? null;
+}
+/** The subset that `charts list` / `charts init --from` actually offer. */
+function scaffoldableCharts() {
+	return Object.entries(BUILT_IN_CHARTS).filter((entry) => entry[1] !== null);
+}
 /**
 * drizzle-cube charts list
 */
 function chartsList() {
 	console.log("\nAvailable built-in chart types:\n");
-	const maxLen = Math.max(...Object.keys(BUILT_IN_CHARTS).map((k) => k.length));
-	for (const [type, desc] of Object.entries(BUILT_IN_CHARTS)) console.log(`  ${type.padEnd(maxLen + 2)} ${desc}`);
+	const charts = scaffoldableCharts();
+	const maxLen = Math.max(...charts.map(([type]) => type.length));
+	for (const [type, chart] of charts) console.log(`  ${type.padEnd(maxLen + 2)} ${chart.description}`);
 	console.log(`\nUse --from <type> with 'charts init' to copy a built-in as starting point.`);
 	console.log(`Example: npx drizzle-cube charts init --from bar\n`);
 }
@@ -93,7 +194,7 @@ function chartsInit() {
 	const fromBuiltIn = values.from;
 	const customName = values.name;
 	if (fromBuiltIn) {
-		if (!BUILT_IN_CHARTS[fromBuiltIn]) {
+		if (!lookupScaffold(fromBuiltIn)) {
 			console.error(`\nUnknown chart type: "${fromBuiltIn}"`);
 			console.error(`Run 'npx drizzle-cube charts list' to see available types.\n`);
 			process.exit(1);
@@ -144,36 +245,13 @@ Generating a template based on the ${chartType} chart instead.
 		scaffoldExample(outputDir, name);
 		return;
 	}
-	const fileName = {
-		bar: "BarChart",
-		line: "LineChart",
-		area: "AreaChart",
-		pie: "PieChart",
-		scatter: "ScatterChart",
-		bubble: "BubbleChart",
-		radar: "RadarChart",
-		radialBar: "RadialBarChart",
-		treemap: "TreeMapChart",
-		table: "DataTable",
-		activityGrid: "ActivityGridChart",
-		kpiNumber: "KpiNumber",
-		kpiDelta: "KpiDelta",
-		kpiText: "KpiText",
-		funnel: "FunnelChart",
-		sankey: "SankeyChart",
-		sunburst: "SunburstChart",
-		heatmap: "HeatMapChart",
-		boxPlot: "BoxPlotChart",
-		waterfall: "WaterfallChart",
-		candlestick: "CandlestickChart",
-		gauge: "GaugeChart",
-		measureProfile: "MeasureProfileChart"
-	}[chartType];
-	if (!fileName) {
+	const scaffold = lookupScaffold(chartType);
+	if (!scaffold) {
 		console.error(`No file mapping for chart type: ${chartType}`);
 		scaffoldExample(outputDir, name);
 		return;
 	}
+	const fileName = scaffold.file;
 	const componentSource = node_path.default.join(sourceDir, `${fileName}.tsx`);
 	const configSource = node_path.default.join(sourceDir, `${fileName}.config.ts`);
 	ensureDir(outputDir);

package/dist/client/charts/chartConfigRegistry.d.ts

@@ -7,6 +7,13 @@ import { ChartTypeConfig, ChartConfigRegistry } from './chartConfigs.js';
  * stay here in full because the server agent reads them synchronously.
  */
 export declare const chartConfigRegistry: ChartConfigRegistry;
+/**
+ * Whether a chart lists records rather than aggregates, and so needs an
+ * `ungrouped` query.
+ *
+ * Reads the eager registry so the query builders need no chart-type switch.
+ */
+export declare function isRecordGrainChart(chartType: string): boolean;
 /**
  * Register a custom chart config into the registry.
  * Used by the chart plugin system.

package/dist/client/charts/chartConfigs.d.ts

@@ -18,6 +18,13 @@ export interface AxisDropZoneConfig {
     emptyText?: string;
     /** Enable L/R axis toggle for items in this drop zone (for dual Y-axis support) */
     enableDualAxis?: boolean;
+    /**
+     * Keep this zone out of automatic chart-config inference (the agent's
+     * `inferChartConfig`). For zones whose meaning is subtractive or opt-in — the
+     * records table's hidden columns being the case in point — filling them from
+     * the query changes what renders rather than completing a partial config.
+     */
+    excludeFromInference?: boolean;
 }
 /**
  * Configuration for a single display option
@@ -28,7 +35,7 @@ export interface DisplayOptionConfig {
     /** Display label for the option */
     label: string;
     /** Type of input control to render */
-    type: 'boolean' | 'string' | 'number' | 'select' | 'color' | 'paletteColor' | 'axisFormat' | 'stringArray' | 'buttonGroup' | 'thresholdBands';
+    type: 'boolean' | 'string' | 'number' | 'select' | 'color' | 'paletteColor' | 'axisFormat' | 'stringArray' | 'buttonGroup' | 'thresholdBands' | 'columnFormats' | 'rowLink';
     /** Default value for the option */
     defaultValue?: any;
     /** Placeholder text for string/number inputs */
@@ -125,6 +132,15 @@ export interface ChartTypeConfig {
      * Omit to mean "always available".
      */
     isAvailable?: (ctx: ChartAvailabilityContext) => ChartAvailability;
+    /**
+     * This chart lists individual records rather than aggregates, so the query
+     * built for it must be `ungrouped`.
+     *
+     * Declared here rather than switched on a chart type inside the query
+     * builders, and read from the eager registry so those stay data-driven — and
+     * so a custom chart can opt in through the same flag.
+     */
+    recordGrain?: boolean;
 }
 /**
  * Registry of all chart type configurations

package/dist/client/charts.js

@@ -1,14 +1,14 @@
-import { ct as e, dt as t, ft as n, lt as r, mt as i, pt as a, st as o, t as s, ut as c } from "./chunks/chart-data-table-DoDHQRe7.js";
-import { d as l, l as u, s as d, u as f } from "./chunks/chart-activity-grid-4jfS8khG.js";
-import { t as p } from "./chunks/chart-funnel-Cd7da_sa.js";
-import { a as m, i as h, n as g, o as _, r as v, s as y, t as b } from "./chunks/charts-loader-CwMcOfwT.js";
-import { t as x } from "./chunks/chart-area-Dol6s9no.js";
+import { dt as e, ft as t, gt as n, ht as r, lt as i, mt as a, pt as o, t as s, ut as c } from "./chunks/chart-data-table-C_oHiK6N.js";
+import { d as l, l as u, s as d, u as f } from "./chunks/chart-activity-grid-DO82rrbW.js";
+import { t as p } from "./chunks/chart-funnel-B_CWC3cL.js";
+import { a as m, i as h, n as g, o as _, r as v, s as y, t as b } from "./chunks/charts-loader-Bya_zDIA.js";
+import { t as x } from "./chunks/chart-area-9SBeG0GM.js";
 import { i as S } from "./chunks/utils-CToHkuhU.js";
-import { t as C } from "./chunks/chart-bar-5_niozi2.js";
-import { t as w } from "./chunks/chart-line-DlwOB7C7.js";
-import { t as T } from "./chunks/chart-pie-FGw66XAH.js";
-import { t as E } from "./chunks/chart-scatter-D9EcAiMQ.js";
-import { t as D } from "./chunks/chart-radar-D-eRDoiA.js";
-import { t as O } from "./chunks/chart-radial-bar-DgtkNTs3.js";
-import { t as k } from "./chunks/chart-tree-map-D_ACSSiB.js";
-export { d as CHART_COLORS, u as CHART_MARGINS, s as DataTable, p as FunnelChart, b as LazyChart, f as NEGATIVE_COLOR, l as POSITIVE_COLOR, x as RechartsAreaChart, C as RechartsBarChart, w as RechartsLineChart, T as RechartsPieChart, D as RechartsRadarChart, O as RechartsRadialBarChart, E as RechartsScatterChart, k as RechartsTreeMapChart, o as clearChartConfigCache, S as formatChartData, g as getAvailableChartTypes, e as getChartConfigAsync, r as getChartConfigSync, v as getUnavailableChartTypes, c as isChartConfigLoaded, h as isChartTypeAvailable, m as isValidChartType, t as loadAllChartConfigs, _ as preloadChart, n as preloadChartConfig, a as preloadChartConfigs, y as preloadCharts, i as useChartConfig };
+import { t as C } from "./chunks/chart-bar-tfgmLK2D.js";
+import { t as w } from "./chunks/chart-line-pDe25JzB.js";
+import { t as T } from "./chunks/chart-pie-ZrnBycy1.js";
+import { t as E } from "./chunks/chart-scatter-DrwRkzzl.js";
+import { t as D } from "./chunks/chart-radar-BXbnYMUJ.js";
+import { t as O } from "./chunks/chart-radial-bar-CYxH3ryh.js";
+import { t as k } from "./chunks/chart-tree-map-BNjHhhVq.js";
+export { d as CHART_COLORS, u as CHART_MARGINS, s as DataTable, p as FunnelChart, b as LazyChart, f as NEGATIVE_COLOR, l as POSITIVE_COLOR, x as RechartsAreaChart, C as RechartsBarChart, w as RechartsLineChart, T as RechartsPieChart, D as RechartsRadarChart, O as RechartsRadialBarChart, E as RechartsScatterChart, k as RechartsTreeMapChart, i as clearChartConfigCache, S as formatChartData, g as getAvailableChartTypes, c as getChartConfigAsync, e as getChartConfigSync, v as getUnavailableChartTypes, t as isChartConfigLoaded, h as isChartTypeAvailable, m as isValidChartType, o as loadAllChartConfigs, _ as preloadChart, a as preloadChartConfig, r as preloadChartConfigs, y as preloadCharts, n as useChartConfig };