drizzle-cube 0.7.1 → 0.8.0

package/dist/adapters/{utils-DboNUT3A.js → utils-DkmShl5f.js}

@@ -714,6 +714,9 @@ var e = Object.create, t = Object.defineProperty, n = Object.getOwnPropertyDescr
 	"server.errors.retentionValidationFailed": "Retention validation failed: {errors}",
 	"server.errors.cubeRefUnresolved": "{cubeName}.joins.{joinName}: target cube '{targetCube}' is not registered",
 	"server.errors.unresolvedCubeRefs": "Unresolved cube references:\n{details}",
+	"server.errors.cubeSetIdEmpty": "Cube set id must not be empty — the empty id is reserved for the base cube set",
+	"server.errors.cubeSetNotFound": "No cube set registered for '{setId}'",
+	"server.errors.attributeIdRequired": "Attribute definitions must have a non-empty id",
 	"server.errors.calculatedMeasureValidation": "Calculated measure validation failed for cube '{cubeName}':\n{details}",
 	"server.errors.queryValidationFailed": "Query validation failed: {errors}",
 	"server.errors.queryContainsMultipleModes": "Query contains multiple query modes: {modes}",
@@ -6425,13 +6428,13 @@ function Mo(e, t, n) {
 //#endregion
 //#region src/server/query-handlers.ts
 var No = fo.messages[0]?.content.text ?? "";
-async function Po(e, t) {
+async function Po(e, t, n) {
 	return {
-		cubes: jo(e.getMetadata(), {
-			topic: t.topic,
-			intent: t.intent,
-			limit: t.limit,
-			minScore: t.minScore
+		cubes: jo(e.getMetadata(t), {
+			topic: n.topic,
+			intent: n.intent,
+			limit: n.limit,
+			minScore: n.minScore
 		}),
 		queryLanguageReference: co,
 		dateFilteringGuide: No
@@ -6484,7 +6487,7 @@ function zo(e, t) {
 	return r;
 }
 async function Bo(e, t, n) {
-	let r = Fo(n.query), i = e.validateQuery(r);
+	let r = Fo(n.query), i = e.validateQuery(r, t);
 	if (!i.isValid) throw Error(`Query validation failed: ${i.errors.join(", ")}`);
 	let a = await e.executeMultiCubeQuery(r, t);
 	return {
@@ -7218,9 +7221,9 @@ function ys(e, t, n) {
 		return;
 	}
 }
-function Y(e, t, n) {
-	let r = t.validateQuery(e);
-	if (!r.isValid) throw Error(`${n} validation failed: ${r.errors.join(", ")}`);
+function Y(e, t, n, r) {
+	let i = n.validateQuery(e, t);
+	if (!i.isValid) throw Error(`${r} validation failed: ${i.errors.join(", ")}`);
 }
 async function X(e, t, n) {
 	return {
@@ -7293,7 +7296,7 @@ async function ws(e, t, n) {
 	}[vs(e)]();
 }
 async function Ts(e, t, n) {
-	Y(e, n, "Query");
+	Y(e, t, n, "Query");
 	let r = bs(e), i = r.length > 1, { sqlResult: a, analysis: o } = await X(e, t, n), s = r.map((t) => ({
 		cube: t,
 		query: {
@@ -7319,7 +7322,7 @@ async function Ts(e, t, n) {
 	});
 }
 async function Es(e, t, n) {
-	Y(e, n, "Comparison query");
+	Y(e, t, n, "Comparison query");
 	let r = bs(e), i = r.length > 1, { sqlResult: a, analysis: o } = await X(e, t, n), s = e.timeDimensions?.find((e) => e.compareDateRange && e.compareDateRange.length >= 2), c = s ? {
 		timeDimension: s.dimension,
 		granularity: s.granularity || "day",
@@ -7468,7 +7471,7 @@ async function js(e, t, n, r) {
 	}) };
 }
 async function Ms(e, t, n) {
-	Y(e, n, "Funnel query");
+	Y(e, t, n, "Funnel query");
 	let r = xs(e), { sqlResult: i, analysis: a } = await X(e, t, n), o = e.funnel;
 	return $({
 		mode: "funnel",
@@ -7495,7 +7498,7 @@ async function Ms(e, t, n) {
 	});
 }
 async function Ns(e, t, n) {
-	Y(e, n, "Flow query");
+	Y(e, t, n, "Flow query");
 	let r = Ss(e), { sqlResult: i, analysis: a } = await X(e, t, n), o = e.flow;
 	return $({
 		mode: "flow",
@@ -7517,7 +7520,7 @@ async function Ns(e, t, n) {
 	});
 }
 async function Ps(e, t, n) {
-	Y(e, n, "Retention query");
+	Y(e, t, n, "Retention query");
 	let r = Cs(e), { sqlResult: i, analysis: a } = await X(e, t, n), o = e.retention;
 	return $({
 		mode: "retention",
@@ -7539,13 +7542,13 @@ async function Ps(e, t, n) {
 		}
 	});
 }
-async function Fs(e, t) {
-	return es(e.getMetadata(), t.naturalLanguage, t.cube);
+async function Fs(e, t, n) {
+	return es(e.getMetadata(t), n.naturalLanguage, n.cube);
 }
 async function Is(e, t, n) {
-	let r = e.getMetadata(), i = await fs(t.query, r);
-	if (i.isValid && n) try {
-		let r = Fo(i.correctedQuery ?? t.query), a = await e.dryRun(r, n);
+	let r = e.getMetadata(t), i = await fs(n.query, r);
+	if (i.isValid) try {
+		let r = Fo(i.correctedQuery ?? n.query), a = await e.dryRun(r, t);
 		return {
 			...i,
 			sql: a

package/dist/adapters/utils.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./utils-BoOeig94.cjs");exports.buildTransformedQuery=e.t,exports.calculateQueryComplexity=e.n,exports.formatCubeResponse=e.r,exports.formatErrorResponse=e.i,exports.formatMetaResponse=e.a,exports.formatSqlResponse=e.o,exports.formatSqlString=e.S,exports.generateRequestId=e.s,exports.getDatabaseType=e.c,exports.handleBatchRequest=e.l,exports.handleDiscover=e.p,exports.handleDryRun=e.u,exports.handleLoad=e.m,exports.handleSuggest=e.d,exports.handleValidate=e.f,exports.normalizeQueryFields=e.h;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./utils-BY0-KFyI.cjs");exports.buildTransformedQuery=e.t,exports.calculateQueryComplexity=e.n,exports.formatCubeResponse=e.r,exports.formatErrorResponse=e.i,exports.formatMetaResponse=e.a,exports.formatSqlResponse=e.o,exports.formatSqlString=e.S,exports.generateRequestId=e.s,exports.getDatabaseType=e.c,exports.handleBatchRequest=e.l,exports.handleDiscover=e.p,exports.handleDryRun=e.u,exports.handleLoad=e.m,exports.handleSuggest=e.d,exports.handleValidate=e.f,exports.normalizeQueryFields=e.h;

package/dist/adapters/utils.d.ts

@@ -354,11 +354,11 @@ export interface ValidateRequest {
 /**
  * Handle /suggest endpoint - generate query from natural language
  */
-export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, body: SuggestRequest): Promise<QuerySuggestion>;
+export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: SuggestRequest): Promise<QuerySuggestion>;
 /**
  * Handle /validate endpoint - validate query with corrections
  */
-export declare function handleValidate(semanticLayer: SemanticLayerCompiler, body: ValidateRequest, securityContext?: SecurityContext): Promise<AIValidationResult & {
+export declare function handleValidate(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: ValidateRequest): Promise<AIValidationResult & {
     sql?: {
         sql: string;
         params?: any[];

package/dist/adapters/utils.js

@@ -1,2 +1,2 @@
-import { S as e, a as t, c as n, d as r, f as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./utils-DboNUT3A.js";
+import { S as e, a as t, c as n, d as r, f as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./utils-DkmShl5f.js";
 export { m as buildTransformedQuery, l as calculateQueryComplexity, f as formatCubeResponse, o as formatErrorResponse, t as formatMetaResponse, u as formatSqlResponse, e as formatSqlString, p as generateRequestId, n as getDatabaseType, s as handleBatchRequest, d as handleDiscover, h as handleDryRun, c as handleLoad, r as handleSuggest, i as handleValidate, a as normalizeQueryFields };

package/dist/cjs/adapters/core/http-port.d.ts

@@ -7,8 +7,16 @@
  * (Hono/Next.js). Implementations are constructed per request by each adapter.
  *
  * This interface is public — third parties implement it to build adapters for
- * other frameworks. Add new capabilities as optional members or via a separate
- * extension interface; a new required member is a breaking change.
+ * other frameworks. Prefer optional members or a separate extension interface
+ * for new capabilities, because a new required member is a breaking change for
+ * those adapters.
+ *
+ * `setHeader` was promoted from {@link McpHttpPort} to this interface in the
+ * per-tenant cube sets release, so that the core can stamp `Cache-Control` on
+ * every REST response (see {@link withRestCacheHeaders}). Every REST body is now
+ * tenant-scoped, and that guarantee cannot be left to each adapter. The break is
+ * accepted for this release: third-party REST-only adapters must add
+ * `setHeader`, which all four first-party adapters already implemented.
  */
 export interface HttpPort<TRes> {
     /** Read a request header by (case-insensitive) name. Synchronous. */
@@ -17,23 +25,42 @@ export interface HttpPort<TRes> {
     getBody(): Promise<unknown>;
     /** Read a raw query-string value by name (used by GET). */
     getQueryParam(name: string): string | undefined;
+    /** Set a response header. Must be called before `send`/`sendSse`/`sendEmpty`. */
+    setHeader(name: string, value: string): void;
     /** Send a response with the given status and JSON body; returns the framework's response value. */
     send(status: number, body: unknown): TRes;
 }
 /**
- * Extension of {@link HttpPort} for the MCP POST handler, which needs to set
- * response headers (WWW-Authenticate, MCP-Session-Id), emit a single-event SSE
- * response, and send an empty-body acknowledgement (202 for notifications).
+ * Extension of {@link HttpPort} for the MCP POST handler, which needs to emit a
+ * single-event SSE response and send an empty-body acknowledgement (202 for
+ * notifications).
  *
  * Kept separate from the minimal REST port so third-party adapters only
  * implement these when they wire up MCP. New required members on this interface
  * are still a breaking change for MCP-capable adapters.
  */
 export interface McpHttpPort<TRes> extends HttpPort<TRes> {
-    /** Set a response header. Must be called before `send`/`sendSse`/`sendEmpty`. */
-    setHeader(name: string, value: string): void;
     /** Send a single-event SSE response (status 200): write the pre-serialized body, then end. */
     sendSse(status: number, body: string): TRes;
     /** Send an empty-body response (no JSON), e.g. a 202 notification acknowledgement. */
     sendEmpty(status: number): TRes;
 }
+/**
+ * `Cache-Control` stamped on every REST response.
+ *
+ * Every REST body varies by tenant: `/meta` returns the caller's cube set, and
+ * `/load`, `/sql`, `/dry-run`, `/batch` and `/explain` return that tenant's data
+ * or SQL. With no `Cache-Control` a shared cache may store and reuse these
+ * responses heuristically, which would cross-serve one tenant's cubes to
+ * another. `private` bars shared caches; `no-store` bars storage entirely.
+ */
+export declare const REST_CACHE_CONTROL = "private, no-store";
+/**
+ * Wrap a port so every response it sends carries {@link REST_CACHE_CONTROL}.
+ *
+ * Applied once over the whole REST surface in `createCubeHttpHandler`, not per
+ * route, so no endpoint can forget it — including the 400/500 error paths.
+ * Deliberately NOT applied to MCP: its SSE responses set their own
+ * `Cache-Control`, and JSON-RPC POSTs are not heuristically cacheable.
+ */
+export declare function withRestCacheHeaders<TRes>(port: HttpPort<TRes>): HttpPort<TRes>;

package/dist/cjs/adapters/core/index.d.ts

@@ -6,6 +6,7 @@
  * {@link createCubeHttpHandler}.
  */
 export type { HttpPort, McpHttpPort } from './http-port.js';
+export { withRestCacheHeaders, REST_CACHE_CONTROL } from './http-port.js';
 export { withLocaleFromHeaders, resolveSecurityContext, type HeaderReader, type BaseSecurityContextThunk } from './security-context.js';
 export { createCubeHttpHandler, type CubeHttpHandler, type CubeHttpHandlerOptions } from './cube-http-handler.js';
 export type { RestHandlers } from './rest-handlers.js';

package/dist/cjs/adapters/core/rest-handlers.d.ts

@@ -3,7 +3,7 @@ import { HttpPort } from './http-port.js';
 import { BaseSecurityContextThunk } from './security-context.js';
 /** REST handlers keyed by endpoint; each closes over the shared semantic layer. */
 export interface RestHandlers {
-    handleMetaGet<TRes>(port: HttpPort<TRes>): TRes;
+    handleMetaGet<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;
     handleSqlGet<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;
     handleSqlPost<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;
     handleDryRunGet<TRes>(port: HttpPort<TRes>, getBaseSecurityContext: BaseSecurityContextThunk): Promise<TRes>;

package/dist/cjs/adapters/express/index.d.ts

@@ -2,15 +2,24 @@ import { Router, Request, Response, Express } from 'express';
 import { CorsOptions } from 'cors';
 import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
 import { AgentConfig } from '../../server/agent/types.js';
+import { SemanticLayerCompiler } from '../../server/compiler.js';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { MySql2Database } from 'drizzle-orm/mysql2';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 import { MCPOptions } from '../utils.js';
 export interface ExpressAdapterOptions {
     /**
-     * Array of cube definitions to register
+     * Pre-configured SemanticLayerCompiler instance.
+     * When provided, skips creating a new compiler and cube registration (caller
+     * manages it). Required to use per-tenant cube sets, since the caller must own
+     * the compiler to call `registerCubeSet` — see docs/per-tenant-cube-sets.md.
      */
-    cubes: Cube[];
+    semanticLayer?: SemanticLayerCompiler;
+    /**
+     * Array of cube definitions to register.
+     * Required unless `semanticLayer` is provided.
+     */
+    cubes?: Cube[];
     /**
      * Drizzle database instance (REQUIRED)
      * This is the core of drizzle-cube - Drizzle ORM integration

package/dist/cjs/adapters/fastify/index.d.ts

@@ -2,15 +2,24 @@ import { FastifyPluginCallback, FastifyRequest, FastifyInstance } from 'fastify'
 import { FastifyCorsOptions } from '@fastify/cors';
 import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
 import { AgentConfig } from '../../server/agent/types.js';
+import { SemanticLayerCompiler } from '../../server/compiler.js';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { MySql2Database } from 'drizzle-orm/mysql2';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
 import { MCPOptions } from '../utils.js';
 export interface FastifyAdapterOptions {
     /**
-     * Array of cube definitions to register
+     * Pre-configured SemanticLayerCompiler instance.
+     * When provided, skips creating a new compiler and cube registration (caller
+     * manages it). Required to use per-tenant cube sets, since the caller must own
+     * the compiler to call `registerCubeSet` — see docs/per-tenant-cube-sets.md.
      */
-    cubes: Cube[];
+    semanticLayer?: SemanticLayerCompiler;
+    /**
+     * Array of cube definitions to register.
+     * Required unless `semanticLayer` is provided.
+     */
+    cubes?: Cube[];
     /**
      * Drizzle database instance (REQUIRED)
      * This is the core of drizzle-cube - Drizzle ORM integration

package/dist/cjs/adapters/mcp-tools-handlers.d.ts

@@ -6,9 +6,16 @@ export interface CubeToolHandlerDeps {
     wrapContent: (result: unknown) => MCPToolResult;
     wrapError: (error: unknown) => MCPToolResult;
 }
-/** Execute the `discover` tool. */
-export declare function runDiscoverTool(deps: CubeToolHandlerDeps, args: unknown): Promise<MCPToolResult>;
-/** Execute the `validate` tool — security context is optional (SQL omitted without auth). */
+/**
+ * Execute the `discover` tool. Reads the caller's cube set, so it resolves a
+ * security context first — discovery has no unauthenticated mode.
+ */
+export declare function runDiscoverTool(deps: CubeToolHandlerDeps, args: unknown, meta?: unknown): Promise<MCPToolResult>;
+/**
+ * Execute the `validate` tool. The security context is required: validation is
+ * against the caller's cube set, so a caller whose context cannot be resolved
+ * gets an error rather than a base-set answer with the SQL omitted.
+ */
 export declare function runValidateTool(deps: CubeToolHandlerDeps, args: unknown, meta?: unknown): Promise<MCPToolResult>;
 /**
  * Execute the `load` / `chart` tools. Both run the same query path; `chart`

package/dist/cjs/adapters/mcp-transport.d.ts

@@ -172,5 +172,16 @@ export declare function resolveMcpResources(resources?: MCPResourceResolver): MC
  *   project-specific guidance like custom cube semantics).
  */
 export declare function resolveMcpInstructions(instructions?: MCPInstructionsResolver): string;
-export declare function buildMcpSchemaResource(semanticLayer: SemanticLayerCompiler): MCPResource;
-export declare function buildMcpResources(semanticLayer: SemanticLayerCompiler, resources?: MCPResourceResolver): MCPResource[];
+/**
+ * The `drizzle-cube://schema` resource: this caller's cube metadata as JSON.
+ *
+ * Its body is tenant-specific, so it must be built per request under the
+ * caller's security context. Building it once at handler construction — as this
+ * used to be — would freeze every tenant's view to the base set.
+ */
+export declare function buildMcpSchemaResource(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext): MCPResource;
+/**
+ * Static resources plus this caller's schema resource. Call per request, never
+ * at setup time — see {@link buildMcpSchemaResource}.
+ */
+export declare function buildMcpResources(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, resources?: MCPResourceResolver): MCPResource[];

package/dist/cjs/adapters/nextjs/index.d.ts

@@ -26,9 +26,12 @@ export interface NextCorsOptions {
 }
 export interface NextAdapterOptions {
     /**
-     * Array of cube definitions to register
+     * Array of cube definitions to register.
+     * Required unless `semanticLayer` is provided — `createSemanticLayer` returns
+     * an injected compiler untouched, so a caller managing their own (which
+     * per-tenant cube sets require) supplies no cubes here.
      */
-    cubes: Cube[];
+    cubes?: Cube[];
     /**
      * Drizzle database instance (REQUIRED)
      * This is the core of drizzle-cube - Drizzle ORM integration

package/dist/cjs/adapters/utils.d.ts

@@ -354,11 +354,11 @@ export interface ValidateRequest {
 /**
  * Handle /suggest endpoint - generate query from natural language
  */
-export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, body: SuggestRequest): Promise<QuerySuggestion>;
+export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: SuggestRequest): Promise<QuerySuggestion>;
 /**
  * Handle /validate endpoint - validate query with corrections
  */
-export declare function handleValidate(semanticLayer: SemanticLayerCompiler, body: ValidateRequest, securityContext?: SecurityContext): Promise<AIValidationResult & {
+export declare function handleValidate(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: ValidateRequest): Promise<AIValidationResult & {
     sql?: {
         sql: string;
         params?: any[];

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

@@ -0,0 +1,99 @@
+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 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).
+ *
+ * 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>;