drizzle-cube 0.7.1 → 0.8.1

package/dist/server/adapters/base-adapter.d.ts

@@ -111,6 +111,17 @@ export interface DatabaseAdapter {
      * @returns SQL expression with type casting
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Cast expression to specific database type, tolerantly: unparseable input yields NULL
+     * instead of raising an error (PostgreSQL's `::`/`CAST` on bad input) or silently producing
+     * 0 (MySQL/SQLite `CAST` on non-numeric text). Intended for EAV-style schemas where a text
+     * column holds numbers/timestamps for some attributes and free text for others, so one dirty
+     * value doesn't fail the whole query or masquerade as a real 0.
+     * @param fieldExpr - The field expression to cast
+     * @param targetType - Target database type
+     * @returns SQL expression with tolerant type casting; unparseable/NULL input yields NULL
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Build AVG aggregation expression with database-specific null handling
      * @param fieldExpr - The field expression to average
@@ -216,6 +227,7 @@ export declare abstract class BaseDatabaseAdapter implements DatabaseAdapter {
     abstract buildPeriodSeriesSubquery(maxPeriod: number): SQL;
     abstract buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
     abstract castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    abstract tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     abstract getCapabilities(): DatabaseCapabilities;
     abstract buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL | null;
     /**
@@ -303,6 +315,40 @@ export declare abstract class BaseDatabaseAdapter implements DatabaseAdapter {
         field: AnyColumn | SQL;
         direction: 'asc' | 'desc';
     }>, config?: WindowFunctionConfig): SQL | null;
+    /**
+     * Regex pattern for tryCastToType's decimal guard: optional leading sign, digits with an
+     * optional fractional part (or a bare fractional part like `.5`), surrounded by optional
+     * spaces; rejects everything else. Shared by PostgreSQL (`~`) and MySQL/SingleStore
+     * (`REGEXP`).
+     *
+     * Deliberately written using only POSIX ERE syntax (`[0-9]` instead of `\d`, a literal
+     * space instead of `\s`) rather than Perl/ICU shorthands. PostgreSQL's `~` always
+     * understands `\d`/`\s`, and MySQL 8.0.4+'s default ICU regex engine does too — but
+     * SingleStore's `REGEXP` is dialect-switchable via the `regexp_format` session variable
+     * ('extended' = POSIX ERE, 'advanced' = ICU/PCRE-style), and SingleStore's own docs
+     * recommend explicitly opting into 'advanced' for new regex logic, implying 'extended'
+     * (POSIX, no `\d`/`\s`) is the default. Since SingleStoreAdapter inherits this pattern
+     * unchanged from MySQLAdapter and this repo doesn't control session variables for
+     * consumers, the pattern is written as the POSIX-ERE/ICU/ARE intersection so it matches
+     * correctly regardless of which dialect is active.
+     */
+    protected decimalTryCastPattern(): string;
+    /**
+     * Regex pattern for tryCastToType's integer guard: optional leading sign, digits only,
+     * surrounded by optional spaces. Same POSIX-ERE/ICU/ARE-portable rationale as
+     * decimalTryCastPattern().
+     */
+    protected integerTryCastPattern(): string;
+    /**
+     * Regex pattern for tryCastToType's timestamp guard: an ISO 8601-shaped date, optionally
+     * followed by a time component (with optional seconds, fractional seconds and a UTC/offset
+     * suffix), surrounded by optional spaces. This only validates the *shape* of the input —
+     * it does not catch calendar-invalid dates (e.g. 2024-02-30) or reject strings that "look"
+     * like a timestamp but aren't (that would need engine-side parsing, which is exactly what
+     * tryCastToType is avoiding relying on for error-safety). Same POSIX-ERE/ICU/ARE-portable
+     * rationale as decimalTryCastPattern().
+     */
+    protected timestampTryCastPattern(): string;
     /**
      * Helper method to build pattern for string matching
      * Can be overridden by specific adapters if needed

package/dist/server/adapters/databend-adapter.d.ts

@@ -45,6 +45,11 @@ export declare class DatabendAdapter extends BaseDatabaseAdapter {
      * Databend supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Databend tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Databend capabilities - start conservative
      */

package/dist/server/adapters/duckdb-adapter.d.ts

@@ -52,6 +52,11 @@ export declare class DuckDBAdapter extends BaseDatabaseAdapter {
      * DuckDB supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build DuckDB tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * DuckDB has full support for statistical and window functions
      * Note: supportsPercentileSubqueries is false because DuckDB's QUANTILE_CONT

package/dist/server/adapters/mysql-adapter.d.ts

@@ -47,6 +47,20 @@ export declare class MySQLAdapter extends BaseDatabaseAdapter {
      * MySQL equivalent to PostgreSQL's :: casting syntax
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build MySQL tolerant type casting: NULL on unparseable input instead of MySQL's usual
+     * lenient-but-wrong behaviour. `CAST(x AS DECIMAL/SIGNED)` parses a leading numeric prefix
+     * (or returns 0 with a warning if there's no numeric prefix at all) rather than erroring —
+     * so a dirty value like 'n/a' silently becomes 0. `CAST(x AS DATETIME)` on a string that
+     * merely looks date-shaped but is calendar-invalid can, depending on sql_mode, raise an
+     * error (strict mode, the MySQL 8 default) rather than returning NULL. Guard all three with
+     * REGEXP so we only ever attempt the cast on input that already looks like the target type;
+     * anything else short-circuits to NULL first.
+     *
+     * The timestamp guard only validates ISO 8601 *shape* — it will not catch calendar-invalid
+     * dates like 2024-02-30, which could still error under strict SQL mode.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * MySQL AVG/STDDEV/VARIANCE use IFNULL (no COALESCE-for-zero idiom mismatch,
      * but IFNULL is the MySQL-idiomatic null guard).

package/dist/server/adapters/postgres-adapter.d.ts

@@ -43,6 +43,21 @@ export declare class PostgresAdapter extends BaseDatabaseAdapter {
      * Extracted from various locations where ::timestamp was used
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build PostgreSQL tolerant type casting: NULL on unparseable input instead of an error.
+     * PostgreSQL has no TRY_CAST, and `CAST(x AS type DEFAULT NULL ON ERROR)` (added in a
+     * recent PostgreSQL release) requires a minimum server version. This repo pins no minimum
+     * PostgreSQL version anywhere (CI/dev docker-compose both run `postgres:18`, but nothing
+     * documents that as a floor for consumers), so we don't assume newer syntax is available.
+     * Instead, guard the cast with a POSIX regex (`~`) so we only ever attempt to cast values
+     * that already look like the target type; anything else short-circuits to NULL before the
+     * cast runs, so PostgreSQL never gets a chance to raise.
+     *
+     * The timestamp guard only validates ISO 8601 *shape* (see timestampTryCastPattern) — it
+     * will not catch calendar-invalid dates like 2024-02-30, which would still error. A full
+     * guarantee would need a helper SQL function (out of scope here).
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * PostgreSQL has full support for statistical and window functions
      */

package/dist/server/adapters/snowflake-adapter.d.ts

@@ -41,6 +41,12 @@ export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
      * Snowflake supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build Snowflake tolerant type casting using the native TRY_CAST function, which returns
+     * NULL on conversion failure instead of raising an error (unlike `::`/CAST). Snowflake's
+     * TRY_CAST supports VARCHAR, NUMBER-family types (including DECIMAL) and TIMESTAMP.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * Snowflake capabilities - full SQL support
      */

package/dist/server/adapters/sqlite-adapter.d.ts

@@ -51,6 +51,27 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      * SQLite has dynamic typing but supports CAST for consistency
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
+    /**
+     * Build SQLite tolerant type casting: NULL on unparseable input instead of SQLite's usual
+     * dynamic-typing behaviour. SQLite's CAST-to-numeric applies "prefix" conversion — the
+     * longest numeric prefix of the string is used, or 0 if there is none — so `CAST('n/a' AS
+     * REAL)` silently yields 0.0 rather than erroring or returning NULL.
+     *
+     * SQLite has no REGEXP operator by default (it requires loading an extension, same
+     * limitation regexCondition() works around with GLOB). GLOB's `*`/`?`/`[...]` syntax can't
+     * express "one or more digits" directly, but the standard SQLite idiom for "string contains
+     * only characters from a set" is `NOT x GLOB '*[^set]*'` — true only if no character outside
+     * the set appears anywhere. That's what's used below to validate the trimmed value contains
+     * only the characters a valid decimal/integer/epoch-ms value could use, before attempting
+     * the cast; empty/whitespace-only strings are excluded separately.
+     *
+     * Known limitation: this is a character-set check, not a full grammar check, so a malformed
+     * value that still only uses allowed characters (e.g. '1.2.3' or '+-5') passes the guard and
+     * is then handled by SQLite's own prefix-based numeric parsing (never an error, but not
+     * necessarily NULL either). Clearly non-numeric input (letters, 'n/a', punctuation outside
+     * the allowed set) is reliably rejected to NULL, which is the case this method exists for.
+     */
+    tryCastToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
      * SQLite AVG uses IFNULL rather than COALESCE for null-to-zero handling.
      */

package/dist/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/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/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/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/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/server/attribute-dimensions.d.ts

@@ -0,0 +1,102 @@
+import { AnyColumn, SQL } from 'drizzle-orm';
+import { Dimension, QueryContext } from './types/index.js';
+/** The value types a generated attribute dimension can be cast to. */
+export type AttributeValueType = 'string' | 'number' | 'time';
+/** One admin-defined attribute, as loaded from the application's own table. */
+export interface AttributeDefinition {
+    /**
+     * Stable identifier. The dimension's member name is derived from this, never
+     * from the attribute's name — so renaming an attribute updates every table
+     * header without breaking saved dashboards, drill state or share links.
+     */
+    id: string | number;
+    /** Display name. Becomes the dimension's `title`, which the client renders. */
+    name: string;
+    /**
+     * Value type, if the application's attribute table records one. Filtering and
+     * sorting happen in SQL over the whole table before any row reaches the
+     * browser, so this is not cosmetic — see {@link buildAttributeDimensions}.
+     */
+    valueType?: AttributeValueType;
+}
+export interface BuildAttributeDimensionsOptions {
+    /** The attributes to generate a dimension for. */
+    attributes: AttributeDefinition[];
+    /** The junction table holding one row per (record, attribute). */
+    valueTable: unknown;
+    /** Primary key of the record being extended — e.g. `employees.id`. */
+    recordKey: AnyColumn;
+    /** Column on the junction table pointing back at the record. */
+    foreignKey: AnyColumn;
+    /** Column on the junction table identifying the attribute. */
+    attributeKey: AnyColumn;
+    /** Column on the junction table holding the value. */
+    valueColumn: AnyColumn;
+    /**
+     * Row-level security for the junction table. **Required**: the subquery reads
+     * the junction table directly, so without this a tenant sees every tenant's
+     * attribute values. It is a parameter rather than an option so that omitting
+     * it is impossible rather than merely inadvisable.
+     */
+    security: (ctx: QueryContext) => SQL;
+    /**
+     * Per-attribute type overrides, keyed by attribute id. Wins over
+     * `AttributeDefinition.valueType`.
+     */
+    types?: Record<string, AttributeValueType>;
+    /** Member-name prefix. Defaults to `attr_`. */
+    namePrefix?: string;
+    /** Passed through to each generated dimension's `shown`. */
+    shown?: boolean;
+}
+/**
+ * Build one dimension per attribute, each backed by a correlated scalar
+ * subquery against the junction table.
+ *
+ * ```ts
+ * dimensions: {
+ *   ...baseDimensions,
+ *   ...buildAttributeDimensions({
+ *     attributes: attrs,
+ *     valueTable: employeeAttributeValues,
+ *     recordKey: employees.id,
+ *     foreignKey: employeeAttributeValues.employeeId,
+ *     attributeKey: employeeAttributeValues.attributeId,
+ *     valueColumn: employeeAttributeValues.value,
+ *     security: (ctx) => eq(employeeAttributeValues.organisationId, ctx.securityContext.organisationId)
+ *   })
+ * }
+ * ```
+ *
+ * Three details that are easy to get wrong, and are handled here:
+ *
+ * - **Typing is mandatory, not cosmetic.** Sorting and filtering run in SQL
+ *   over the whole table before a page reaches the browser, so client-side
+ *   conversion cannot repair them: sorted as text, `100` sorts below `9`, and
+ *   `> 50` admits `'9'` while rejecting `'100'`. A `number` attribute is cast
+ *   in SQL — tolerantly, so one `n/a` yields NULL for that row instead of
+ *   failing the whole query.
+ * - **`LIMIT 1`.** EAV tables rarely carry a unique constraint on
+ *   (record, attribute); without it a duplicate row raises "more than one row
+ *   returned by a subquery" on Postgres.
+ * - **Security inside the subquery**, not merely on the outer query.
+ *
+ * **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
+ * proportional to the base table because no index serves them. At tens of
+ * thousands of rows that is fine; beyond it, pivot the attributes into real
+ * indexable columns via a view.
+ */
+export declare function buildAttributeDimensions(options: BuildAttributeDimensionsOptions): Record<string, Dimension>;

package/dist/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/server/cache-utils.d.ts

@@ -24,9 +24,13 @@ export interface CacheKeyConfig {
  * @param query - The semantic query to cache
  * @param securityContext - Security context for tenant isolation
  * @param config - Cache key configuration
+ * @param cubeSetKey - Identifies the cube definitions behind the result. Always
+ *   included when present: `includeSecurityContext: false` and a custom
+ *   `securityContextSerializer` can each hash two tenants identically, so the
+ *   security-context hash alone cannot keep differing cube sets apart.
  * @returns Deterministic cache key string
  */
-export declare function generateCacheKey(query: SemanticQuery, securityContext: SecurityContext, config?: CacheKeyConfig): string;
+export declare function generateCacheKey(query: SemanticQuery, securityContext: SecurityContext, config?: CacheKeyConfig, cubeSetKey?: string): string;
 /**
  * Normalize query for consistent hashing
  * Sorts arrays and object keys to ensure same query = same hash

package/dist/server/compiler-metadata.d.ts

@@ -1,11 +1,32 @@
 import { Cube, MeasureMetadata, DimensionMetadata, CubeRelationshipMetadata, HierarchyMetadata, TimeGranularity } from './types/index.js';
 /** Default time granularities used when a time dimension omits `granularities`. */
 export declare const DEFAULT_TIME_GRANULARITIES: TimeGranularity[];
-/** Build measure metadata, normalizing drillMembers to fully-qualified names. */
+/**
+ * Build measure metadata, normalizing drillMembers to fully-qualified names.
+ *
+ * Measures with `shown: false` are omitted from the result — matching Cube.js
+ * semantics, where a hidden measure remains fully usable in queries but is
+ * excluded from metadata/UI surfaces. `shown: undefined` means shown, so
+ * today's behaviour is preserved exactly.
+ */
 export declare function buildMeasureMetadata(cube: Cube): MeasureMetadata[];
-/** Build dimension metadata, including granularities for time dimensions. */
+/**
+ * Build dimension metadata, including granularities for time dimensions.
+ *
+ * Dimensions with `shown: false` are omitted from the result — matching
+ * Cube.js semantics, where a hidden dimension remains fully usable in queries
+ * but is excluded from metadata/UI surfaces. `shown: undefined` means shown,
+ * so today's behaviour is preserved exactly.
+ */
 export declare function buildDimensionMetadata(cube: Cube): DimensionMetadata[];
 /** Build relationship metadata from a cube's joins, resolving target cubes. */
 export declare function buildRelationshipMetadata(cube: Cube, cubes: Map<string, Cube>, getColumnName: (column: any) => string): CubeRelationshipMetadata[];
-/** Build hierarchy metadata, qualifying level names to full member names. */
+/**
+ * Build hierarchy metadata, qualifying level names to full member names.
+ *
+ * Levels referencing a dimension with `shown: false` are dropped, so a
+ * hierarchy never emits a dangling reference to a dimension that has been
+ * omitted from the cube's own dimension metadata. A hierarchy left with no
+ * visible levels is omitted entirely rather than published as empty.
+ */
 export declare function buildHierarchyMetadata(cube: Cube): HierarchyMetadata[];