drizzle-cube 0.8.0 → 0.8.2

package/dist/cjs/client/types.d.ts

@@ -71,7 +71,7 @@ export interface CubeMeta {
 }
 export type FieldLabelMap = Record<string, string>;
 export type { ColorPalette } from './utils/colorPalettes.js';
-export type BuiltInChartType = 'line' | 'bar' | 'pie' | 'table' | 'area' | 'scatter' | 'radar' | 'radialBar' | 'treemap' | 'bubble' | 'activityGrid' | 'kpiNumber' | 'kpiDelta' | 'kpiText' | 'markdown' | 'funnel' | 'sankey' | 'sunburst' | 'heatmap' | 'retentionHeatmap' | 'retentionCombined' | 'boxPlot' | 'waterfall' | 'candlestick' | 'proportionBar' | 'measureProfile' | 'gauge';
+export type BuiltInChartType = 'line' | 'bar' | 'pie' | 'table' | 'area' | 'scatter' | 'radar' | 'radialBar' | 'treemap' | 'bubble' | 'activityGrid' | 'kpiNumber' | 'kpiDelta' | 'kpiText' | 'markdown' | 'funnel' | 'sankey' | 'sunburst' | 'heatmap' | 'retentionHeatmap' | 'retentionCombined' | 'boxPlot' | 'dotStrip' | 'waterfall' | 'candlestick' | 'proportionBar' | 'measureProfile' | 'gauge' | 'recordsTable';
 export type ChartType = BuiltInChartType | (string & {});
 export interface AxisFormatConfig {
     label?: string;
@@ -80,6 +80,7 @@ export interface AxisFormatConfig {
     decimals?: number;
     customPrefix?: string;
     customSuffix?: string;
+    currencyCode?: string;
 }
 export interface ChartAxisConfig {
     xAxis?: string[];
@@ -89,10 +90,49 @@ export interface ChartAxisConfig {
     colorField?: string;
     dateField?: string[];
     valueField?: string[];
+    columns?: string[];
+    hiddenColumns?: string[];
     x?: string;
     y?: string[];
     yAxisAssignment?: Record<string, 'left' | 'right'>;
 }
+/**
+ * How a records-table column renders its value. Chosen per column in the chart
+ * editor — never inferred from the data, so the same field can be a badge in one
+ * dashboard and plain text in another.
+ */
+export type ColumnFormatKind = 'text' | 'number' | 'date' | 'badge' | 'progress';
+export interface ColumnFormatConfig {
+    kind: ColumnFormatKind;
+    /** Numeric formatting for `kind: 'number'` — reuses the shared axis formatter. */
+    numberFormat?: AxisFormatConfig;
+    /** Granularity for `kind: 'date'`. */
+    dateGranularity?: TimeGranularity;
+    /**
+     * Value → palette colour index for `kind: 'badge'`. Values with no mapping
+     * render neutral rather than being assigned a guessed colour.
+     */
+    badgeColors?: Array<{
+        value: string;
+        colorIndex: number;
+    }>;
+    /** Bounds for `kind: 'progress'` (default 0-100). Values are clamped. */
+    progressMin?: number;
+    progressMax?: number;
+    /** How a `kind: 'progress'` cell draws: a full-width bar, or a compact ring for narrow columns. */
+    progressStyle?: 'bar' | 'circle';
+    /** Header override; falls back to the field's metadata title. */
+    label?: string;
+    align?: 'left' | 'right';
+}
+/**
+ * Row-level click-through for the records table. Tokens of the form
+ * `{Cube.field}` are substituted from the row, including hidden columns.
+ */
+export interface RowLinkConfig {
+    urlTemplate: string;
+    target?: 'self' | 'blank';
+}
 export interface ThresholdBand {
     value: number;
     color: string;
@@ -118,7 +158,16 @@ export interface ChartDisplayConfig {
     showPercentages?: boolean;
     sortSegments?: boolean;
     fitToWidth?: boolean;
+    showMedianMarker?: boolean;
+    showBandStats?: boolean;
+    showExtremeLabels?: boolean;
+    dotSize?: 'small' | 'medium' | 'large';
+    bandSort?: 'none' | 'valueDesc' | 'valueAsc' | 'count';
     pivotTimeDimension?: boolean;
+    columnFormats?: Record<string, ColumnFormatConfig>;
+    columnWidths?: Record<string, number>;
+    rowLink?: RowLinkConfig;
+    pageSize?: number;
     target?: string;
     template?: string;
     prefix?: string;
@@ -353,6 +402,12 @@ export interface CubeQuery {
     segments?: string[];
     /** When true, returns raw row-level data without GROUP BY or aggregation */
     ungrouped?: boolean;
+    /**
+     * Ask the server for the number of rows the query would return with no
+     * limit/offset, read back via `CubeResultSet.totalCount()`. Costs a second
+     * round trip, so only paginated views set it.
+     */
+    total?: boolean;
 }
 /**
  * Merge strategy for combining multiple query results
@@ -389,6 +444,17 @@ export interface CubeApiOptions {
     headers?: Record<string, string>;
     credentials?: 'include' | 'omit' | 'same-origin';
 }
+/**
+ * An unknown member the server rejected, mirroring the server's
+ * `QueryValidationIssue`. `source` is what decides the response: a projected
+ * member can be dropped and the query re-run, whereas dropping a filter would
+ * widen the result set and must stay an error.
+ */
+export interface CubeValidationIssue {
+    source: 'measure' | 'dimension' | 'timeDimension' | 'filter';
+    member: string;
+    message: string;
+}
 export interface CubeResultSet {
     rawData(): any[];
     tablePivot(): any[];
@@ -401,6 +467,8 @@ export interface CubeResultSet {
         ttlMs: number;
         ttlRemainingMs: number;
     } | undefined;
+    /** Rows the query would return without limit/offset — only when `total: true` was asked for. */
+    totalCount?(): number | undefined;
 }
 export interface AnalyticsPortletProps {
     query: string;
@@ -464,6 +532,34 @@ export interface ChartProps {
     onDataPointClick?: (event: import('./types/drill.js').ChartDataPointClickEvent) => void;
     /** Whether drill-down is enabled (shows pointer cursor on clickable elements) */
     drillEnabled?: boolean;
+    /**
+     * Server-side pagination, supplied by hosts that can re-query (the dashboard
+     * portlet). Absent in the AnalysisBuilder preview, the notebook and plugin
+     * hosts, where a chart pages and sorts over the rows it already has.
+     */
+    pagination?: ChartPagination;
+}
+/**
+ * Paging and sorting state a host drives on the chart's behalf.
+ *
+ * Sort lives here rather than in the chart because with server-side paging a
+ * header click has to re-order the whole result set: sorting only the loaded
+ * page would put the wrong rows on page 1.
+ */
+export interface ChartPagination {
+    page: number;
+    pageSize: number;
+    pageSizeOptions: number[];
+    /** Total matching rows, once the server has reported one. */
+    total?: number;
+    sort?: {
+        column: string;
+        direction: 'asc' | 'desc';
+    };
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+    /** Cycles the column asc → desc → unsorted, resetting to the first page. */
+    toggleSort: (column: string) => void;
 }
 export interface ThumbnailFeatureConfig {
     enabled: boolean;

package/dist/cjs/client/utils/recordsTableUtils.d.ts

@@ -0,0 +1,71 @@
+import { ColumnFormatConfig } from '../types.js';
+/** Fallback when an author has not sized a column. */
+export declare const DEFAULT_COLUMN_WIDTH = 160;
+/** Narrower than this and the resize handle overlaps the header text. */
+export declare const MIN_COLUMN_WIDTH = 60;
+/**
+ * Identity under which a viewer's column widths are remembered.
+ *
+ * A chart component has no portlet id, so widths key on the columns themselves:
+ * two records tables showing the same fields share widths, which is the
+ * behaviour an author would expect from two views of the same records.
+ */
+export declare function columnWidthStorageKey(columns: string[]): string;
+export declare function loadColumnWidths(key: string): Record<string, number>;
+export declare function saveColumnWidths(key: string, widths: Record<string, number>): void;
+/**
+ * A viewer's own column order, remembered under the same identity as widths.
+ *
+ * Stored as a list rather than a map so it survives the author adding or
+ * removing a column: {@link applyColumnOrder} reconciles it against the
+ * columns that actually exist.
+ */
+export declare function loadColumnOrder(key: string): string[];
+export declare function saveColumnOrder(key: string, order: string[]): void;
+/**
+ * Lay a remembered order over the columns the chart actually has.
+ *
+ * Columns the order does not mention keep their authored position relative to
+ * the end, so an author adding a column still sees it rather than having it
+ * silently swallowed by a stale local order.
+ */
+export declare function applyColumnOrder(columns: string[], order: string[]): string[];
+/** Move one column to another's position, returning a new order. */
+export declare function moveColumn(columns: string[], from: string, to: string): string[];
+/**
+ * A cell resolved to something renderable. `progress` carries its own shape
+ * because the component draws a bar or a ring rather than a string; every
+ * other kind reduces to text plus, for badges, a colour.
+ *
+ * The component only ever sees a `RenderedCell`, so the progress `style` is
+ * resolved here rather than being read back out of the column's config.
+ */
+export type RenderedCell = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'badge';
+    text: string;
+    colorIndex?: number;
+} | {
+    kind: 'progress';
+    text: string;
+    fraction: number;
+    style: 'bar' | 'circle';
+};
+/**
+ * Turn a raw cell value into its display form under the column's format.
+ *
+ * Every kind degrades to text rather than erroring: a non-numeric value under
+ * `number`/`progress` renders as-is (EAV columns legitimately contain 'n/a'),
+ * and a badge value with no colour mapping renders neutral rather than being
+ * given a guessed colour.
+ */
+export declare function renderCellValue(value: unknown, format: ColumnFormatConfig | undefined): RenderedCell;
+/**
+ * Sort rows by one column, client-side.
+ *
+ * Only used when the host provides no server-side pagination — with paging on,
+ * sorting the loaded page alone would put the wrong rows on page 1.
+ */
+export declare function sortRows(rows: Record<string, unknown>[], column: string, direction: 'asc' | 'desc'): Record<string, unknown>[];

package/dist/cjs/client/utils/rowLinkUtils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Row click-through URLs for the records table.
+ *
+ * A dashboard author writes a template such as `/employees/{Employees.id}`,
+ * and each row fills its own tokens. The template is author-controlled but the
+ * *values* are data, so they are percent-encoded before substitution — an
+ * encoded value cannot introduce a scheme, a path segment or a query separator.
+ *
+ * The resulting URL is then checked rather than trusted: only same-origin
+ * relative paths and absolute http(s) URLs are allowed through.
+ */
+/**
+ * Resolve a row link template against one row.
+ *
+ * Returns `null` — meaning "render no link" — when the template references a
+ * field the row does not carry, or when the result is not a URL we are willing
+ * to navigate to. Never throws: a malformed template must not take the table
+ * down with it.
+ *
+ * @param template - e.g. `/employees/{Employees.id}?tab=profile`
+ * @param row - the row's values, including hidden columns
+ * @param origin - the origin relative URLs are resolved against
+ */
+export declare function buildRowUrl(template: string | undefined, row: Record<string, unknown>, origin?: string): string | null;
+/**
+ * Whether a URL is one we will navigate to: an absolute `http(s)` URL, or a
+ * path that stays on this origin.
+ *
+ * Rejected, deliberately: `javascript:`, `data:`, `vbscript:` and every other
+ * scheme; protocol-relative `//evil.example`, which inherits the current scheme
+ * and silently leaves the origin; and backslash forms such as `\\evil.example`
+ * or `/\evil.example`, which several browsers normalise into that same
+ * protocol-relative shape.
+ */
+export declare function isSafeUrl(url: string, origin?: string): boolean;

package/dist/cjs/server/agent/chart-validation.d.ts

@@ -12,7 +12,7 @@ interface ValidationResult {
 /**
  * Validate chartConfig against the chart type's drop zone requirements.
  */
-export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, _query: Record<string, unknown>): ValidationResult;
+export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): ValidationResult;
 export declare function inferChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build per-chart-type requirements text for the agent tool description.

package/dist/cjs/server/ai/chart-schema.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Chart Configuration Schema — shared by the MCP and Agent tools
+ *
+ * The chart-side sibling of `QUERY_PARAMS_SCHEMA`. Used by BOTH:
+ * - MCP `chart` tool (adapters/mcp-transport.ts)
+ * - Agent `add_portlet` / `save_as_dashboard` tools (server/agent/tools.ts)
+ *
+ * Most charts need nothing here — their axes are inferred from the query. The
+ * records table is the exception: it lays out `columns` rather than axes, and a
+ * column renders as plain text unless the caller says what it is. Formats are
+ * never guessed from the data, so a model that cannot see this shape produces a
+ * listing of unformatted strings.
+ */
+/** `chartConfig` fields specific to the records table. */
+export declare const RECORDS_TABLE_CHART_CONFIG_SCHEMA: {
+    readonly columns: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+        };
+        readonly description: "recordsTable only: fields to render as columns, in this order. Omit to show every field the query returns, in query order.";
+    };
+    readonly hiddenColumns: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+        };
+        readonly description: "recordsTable only: fields fetched for row context or rowLink tokens but never displayed (e.g. an id used in the URL template). Leave empty unless a field is genuinely only needed behind the scenes — anything listed here disappears from the table.";
+    };
+};
+/** `displayConfig` fields specific to the records table. */
+export declare const RECORDS_TABLE_DISPLAY_CONFIG_SCHEMA: {
+    readonly columnFormats: {
+        readonly type: "object";
+        readonly description: "recordsTable only: how each column renders, keyed by field name (e.g. \"Employees.salary\"). Formats are never inferred from the data — a column is plain text unless you say otherwise, so set this for any numeric, date, status or ratio column.";
+        readonly additionalProperties: {
+            readonly type: "object";
+            readonly required: readonly ["kind"];
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly enum: readonly ["text", "number", "date", "badge", "progress"];
+                    readonly description: "Required on every entry. text: as-is. number: formatted numeric. date: formatted date. badge: coloured pill for statuses/categories. progress: bar or ring for a bounded value. Use \"text\" when you only want to set a label.";
+                };
+                readonly numberFormat: {
+                    readonly type: "object";
+                    readonly description: "kind \"number\": { unit: \"currency\"|\"percent\"|\"number\"|\"custom\", decimals, abbreviate (K/M/B), currencyCode, customPrefix, customSuffix }.";
+                };
+                readonly dateGranularity: {
+                    readonly type: "string";
+                    readonly description: "kind \"date\": granularity to render at (e.g. \"day\", \"month\", \"year\").";
+                };
+                readonly badgeColors: {
+                    readonly type: "array";
+                    readonly description: "kind \"badge\": an ARRAY of { value, colorIndex } entries, not an object keyed by value. colorIndex is a number index into the dashboard palette (0, 1, 2, …), never a colour name like \"green\" — the palette is themed, so names would not follow it. A value with no entry renders neutral rather than being assigned a guessed colour.";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["value", "colorIndex"];
+                        readonly properties: {
+                            readonly value: {
+                                readonly type: "string";
+                                readonly description: "Cell value to colour, matched exactly";
+                            };
+                            readonly colorIndex: {
+                                readonly type: "number";
+                                readonly description: "Index into the dashboard colour palette";
+                            };
+                        };
+                    };
+                };
+                readonly progressMin: {
+                    readonly type: "number";
+                    readonly description: "kind \"progress\": lower bound (default 0). Values are clamped.";
+                };
+                readonly progressMax: {
+                    readonly type: "number";
+                    readonly description: "kind \"progress\": upper bound (default 100). Values are clamped.";
+                };
+                readonly progressStyle: {
+                    readonly type: "string";
+                    readonly enum: readonly ["bar", "circle"];
+                    readonly description: "kind \"progress\": full-width bar, or a compact ring for narrow columns.";
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Header override; defaults to the field title from the cube metadata.";
+                };
+                readonly align: {
+                    readonly type: "string";
+                    readonly enum: readonly ["left", "right"];
+                    readonly description: "Cell alignment. Numbers usually read better right-aligned.";
+                };
+            };
+        };
+    };
+    readonly rowLink: {
+        readonly type: "object";
+        readonly description: "recordsTable only: makes each row a link.";
+        readonly required: readonly ["urlTemplate"];
+        readonly properties: {
+            readonly urlTemplate: {
+                readonly type: "string";
+                readonly description: "URL with {Cube.field} tokens substituted from the row, including hidden columns (e.g. \"/employees/{Employees.id}\"). Relative paths and http(s) URLs only.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["self", "blank"];
+                readonly description: "Open in the same tab (default) or a new one.";
+            };
+        };
+    };
+    readonly pageSize: {
+        readonly type: "number";
+        readonly enum: readonly [25, 50, 100];
+        readonly description: "recordsTable only: rows per page (default 25).";
+    };
+};

package/dist/cjs/server/ai/discovery-helpers.d.ts

@@ -21,6 +21,20 @@ export declare function accumulateFieldScores(keyword: string, fields: Field[],
 }): number;
 /** Return the top-N field names from a score map, highest score first. */
 export declare function topScoredFields(scores: Map<string, number>, limit: number): string[];
+/**
+ * Titles for suggested fields whose name does not already say what they are.
+ *
+ * Most field names describe themselves (`Employees.salary`), so repeating the
+ * title would be noise. A user-defined (EAV) attribute is the case this exists
+ * for: it is addressed by a generated slot name like `attr_2`, and the title is
+ * the only thing that says it means "Completion %". Discovery scores against
+ * that title, so without this the caller is handed an opaque identifier and told
+ * it is relevant.
+ *
+ * Returned as a separate name-keyed map rather than annotated into the field
+ * lists, which callers are told to copy verbatim into queries.
+ */
+export declare function buildFieldTitles(fields: Field[], suggested: string[]): Record<string, string> | undefined;
 /**
  * Score a single field as a best-match candidate (used by findBestFieldMatch).
  * Returns the best score across name, title and synonyms (no description match).

package/dist/cjs/server/ai/discovery.d.ts

@@ -11,6 +11,12 @@ export interface CubeDiscoveryResult {
     matchedOn: ('name' | 'title' | 'description' | 'exampleQuestions' | 'measures' | 'dimensions')[];
     suggestedMeasures: string[];
     suggestedDimensions: string[];
+    /**
+     * Titles for suggested fields whose name does not say what they are — chiefly
+     * user-defined (EAV) attributes, addressed as `attr_<id>`. Keyed by field name
+     * so the names above stay copyable verbatim. Omitted when nothing needs it.
+     */
+    fieldTitles?: Record<string, string>;
     capabilities: {
         query: true;
         funnel: boolean;

package/dist/cjs/server/ai/query-schema.d.ts

@@ -97,7 +97,7 @@ export declare const QUERY_PARAMS_SCHEMA: {
     };
     readonly ungrouped: {
         readonly type: "boolean";
-        readonly description: "When true, returns raw row-level data without GROUP BY. Requires at least one dimension. Incompatible with count/countDistinct measures and analysis modes.";
+        readonly description: "When true, returns raw row-level data without GROUP BY. Requires at least one dimension. Incompatible with count/countDistinct measures and analysis modes. Cannot reference two cubes joined by a hasMany relationship in EITHER direction (e.g. Departments hasMany Employees) — an ungrouped query stays at one record grain, so keep it to a single cube plus its to-one joins. A field from a hasMany-related cube has to be pre-aggregated in a grouped query instead.";
     };
     readonly funnel: {
         readonly type: "object";

package/dist/cjs/server/attribute-dimensions.d.ts

@@ -81,14 +81,17 @@ export interface BuildAttributeDimensionsOptions {
  *   returned by a subquery" on Postgres.
  * - **Security inside the subquery**, not merely on the outer query.
  *
- * **Grouping limitation.** The subquery correlates on the record key, so a
- * *grouped* query must also group by that key — `dimensions: ['Employees.id',
- * 'Employees.attr_1']` is fine, `dimensions: ['Employees.attr_1']` with a
- * measure is not. Postgres rejects the latter with "subquery uses ungrouped
- * column … from outer query", and MySQL with `only_full_group_by`; SQLite
- * permits it. Record-grain listings (`ungrouped: true`) — the case this exists
- * for — are unaffected. If you need to aggregate freely by an attribute, pivot
- * it into a real column with a view (see the performance ladder below).
+ * **Grouping.** The subquery correlates on the record key, so a *grouped* query
+ * must also group by that key or Postgres rejects it with "subquery uses
+ * ungrouped column … from outer query" (MySQL likewise under
+ * `only_full_group_by`; SQLite permits it). The caller does not have to know
+ * that: each generated dimension declares its key via `Dimension.correlatesOn`,
+ * and the GROUP BY builder adds it. The grouping is therefore per record — the
+ * only grain at which a per-record attribute can be read — so an aggregate over
+ * an attribute counts records, not attribute values. If you need to aggregate
+ * freely *by* an attribute, pivot it into a real column with a view (see the
+ * performance ladder below). Record-grain listings (`ungrouped: true`) skip
+ * GROUP BY entirely and are unaffected.
  *
  * Performance: projection is cheap (a page of 25 rows is 25 indexed lookups per
  * attribute), but `ORDER BY (SELECT …)` and `WHERE (SELECT …) = …` are

package/dist/cjs/server/builders/group-by-builder.d.ts

@@ -24,6 +24,21 @@ export declare class GroupByBuilder {
      * Window functions do not require GROUP BY and operate on individual rows.
      */
     buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan): (SQL | AnyColumn)[];
+    /**
+     * Add the correlation key of any selected dimension that declares one.
+     *
+     * A dimension built from a correlated subquery (`buildAttributeDimensions`)
+     * references the record key inside its SQL. Grouping by the subquery alone is
+     * rejected by Postgres ("subquery uses ungrouped column … from outer query")
+     * and by MySQL under `only_full_group_by`, so the key it correlates on is
+     * grouped too.
+     *
+     * This only ever fires for queries that are invalid on those engines today, so
+     * nothing that currently works changes shape. The key is the record's primary
+     * key, so adding it makes the grouping per-record — which is the grain such a
+     * dimension can be read at in the first place.
+     */
+    private addCorrelationKeys;
     /**
      * Determine whether the query contains at least one aggregate (or calculated,
      * or post-aggregation window over an aggregate) measure — which forces GROUP BY.

package/dist/cjs/server/compiler.d.ts

@@ -1,6 +1,8 @@
 import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types/index.js';
+import { QueryValidationResult } from './query-validator.js';
 import { PlanOptimiser } from './logical-plan/index.js';
 export { validateQueryAgainstCubes } from './query-validator.js';
+export type { QueryValidationIssue, QueryValidationResult } from './query-validator.js';
 /**
  * Identifier of the base cube set — the cubes registered with {@link
  * SemanticLayerCompiler.registerCube}, shared by every tenant. The empty string
@@ -346,10 +348,7 @@ export declare class SemanticLayerCompiler {
      * Validate a query against registered cubes
      * Ensures all referenced cubes and fields exist
      */
-    validateQuery(query: SemanticQuery, securityContext: SecurityContext): {
-        isValid: boolean;
-        errors: string[];
-    };
+    validateQuery(query: SemanticQuery, securityContext: SecurityContext): QueryValidationResult;
     /**
      * Analyze query planning decisions for debugging and transparency
      * Returns detailed metadata about how the query would be planned

package/dist/cjs/server/executor.d.ts

@@ -95,6 +95,21 @@ export declare class QueryExecutor {
      *   (e.g. comparison period sub-queries cache at the comparison level).
      */
     private executeStandardQuery;
+    /**
+     * Count the rows the query would return with no limit or offset — Cube's
+     * `total`.
+     *
+     * Rebuilds the *same* physical plan with pagination and ordering stripped and
+     * counts over it as a subquery. The wrapper is what makes a grouped query
+     * count groups rather than base rows, and rebuilding from `planQuery` rather
+     * than reading the paginated query's effective values matters because
+     * `applyLimitAndOffset` injects a default limit when an offset arrives
+     * without one.
+     *
+     * Runs inside the caller's RLS context, so the count sees exactly the rows
+     * the page did.
+     */
+    private executeTotalCount;
     /**
      * Create a query context with optional filter cache.
      */

package/dist/cjs/server/index.d.ts

@@ -6,6 +6,8 @@ import { SemanticLayerCompiler } from './compiler.js';
  */
 export { SemanticLayerCompiler, BASE_CUBE_SET_ID, SINGLE_TENANT_CONTEXT } from './compiler.js';
 export type { CubeSetRegistrationInfo, CubeSetStats } from './compiler.js';
+export { QueryValidationError } from './query-validator.js';
+export type { QueryValidationIssue, QueryValidationResult } from './query-validator.js';
 export { buildAttributeDimensions } from './attribute-dimensions.js';
 export type { AttributeDefinition, AttributeValueType, BuildAttributeDimensionsOptions } from './attribute-dimensions.js';
 export { QueryExecutor } from './executor.js';

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

@@ -76,4 +76,5 @@ export declare function handleLoad(semanticLayer: SemanticLayerCompiler, securit
     data: Record<string, unknown>[];
     annotation: any;
     query: SemanticQuery;
+    total?: number;
 }>;

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

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

@@ -160,6 +160,18 @@ export interface Dimension {
     sql: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
     /** Whether this is a primary key */
     primaryKey?: boolean;
+    /**
+     * 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

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