drizzle-cube 0.7.0 → 0.8.0

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>;

package/dist/cjs/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/cjs/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[];

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

@@ -1,9 +1,70 @@
 import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types/index.js';
 import { PlanOptimiser } from './logical-plan/index.js';
 export { validateQueryAgainstCubes } from './query-validator.js';
+/**
+ * Identifier of the base cube set — the cubes registered with {@link
+ * SemanticLayerCompiler.registerCube}, shared by every tenant. The empty string
+ * is used so a set id can never collide with it (`registerCubeSet` rejects it).
+ */
+export declare const BASE_CUBE_SET_ID = "";
+/**
+ * Security context for deployments with no tenancy at all.
+ *
+ * Every cube-resolving method requires a `SecurityContext` so that omitting one
+ * is a compile error rather than a silent fall back to the wrong tenant's
+ * cubes. Single-tenant callers pass this constant to say "no tenancy here" out
+ * loud, instead of an anonymous `{}` that reads like an oversight.
+ */
+export declare const SINGLE_TENANT_CONTEXT: SecurityContext;
+/** Reported to `onCubeSetRegistered` after each {@link SemanticLayerCompiler.registerCubeSet}. */
+export interface CubeSetRegistrationInfo {
+    /** The set that was registered. */
+    setId: string;
+    /** Cubes in the set after merging over the base set. */
+    cubeCount: number;
+    /** Total dimensions across those cubes — the number that explains a slow boot. */
+    dimensionCount: number;
+    /**
+     * Monotonic across the whole compiler — incremented on every registration of
+     * any set, never reset. Part of the cache key, so results computed from
+     * superseded definitions can never be served.
+     */
+    generation: number;
+    /** Wall-clock cost of this registration. */
+    durationMs: number;
+}
+/** Aggregate registration cost, for a single summary line after the boot loop. */
+export interface CubeSetStats {
+    /** Number of registered sets, excluding the base set. */
+    setCount: number;
+    /** Total cubes across all sets (merged), excluding the base set. */
+    cubeCount: number;
+    /** Sum of every set's most recent registration time. */
+    totalRegistrationMs: number;
+    /** The most expensive set to register, if any sets are registered. */
+    slowestSet?: {
+        setId: string;
+        durationMs: number;
+    };
+}
 export declare class SemanticLayerCompiler {
-    private cubes;
-    private metadataCache?;
+    /** Cubes shared by every tenant. */
+    private baseCubes;
+    /** Per-tenant overlays, keyed by cube-set id. */
+    private cubeSets;
+    /** Generated metadata per cube set (`BASE_CUBE_SET_ID` for the base set). */
+    private metadataCache;
+    /** Bumped on every base-set mutation; part of every set's cache key. */
+    private baseGeneration;
+    /**
+     * Monotonic registration counter, never reset. Used as each set's generation
+     * so that unregistering a set and registering a different one under the same
+     * id cannot reproduce an earlier cache key and serve its stale results.
+     */
+    private registrationCounter;
+    private contextToCubeSetId?;
+    private missingCubeSet;
+    private onCubeSetRegistered?;
     private cacheConfig?;
     private rlsSetup?;
     private planOptimiser?;
@@ -29,6 +90,25 @@ export declare class SemanticLayerCompiler {
          * Defaults to a no-op IdentityOptimiser when omitted.
          */
         planOptimiser?: PlanOptimiser;
+        /**
+         * Maps a security context to the cube set that serves it — drizzle-cube's
+         * equivalent of Cube's `contextToAppId`. Return `undefined` (or omit this
+         * option entirely) to serve the base set, which is the single-tenant
+         * behaviour and the default.
+         */
+        contextToCubeSetId?: (securityContext: SecurityContext) => string | number | undefined;
+        /**
+         * What to do when `contextToCubeSetId` names a set that is not registered.
+         * `'base'` (default) serves the base set; `'throw'` fails the request, for
+         * deployments where every tenant is required to have its own set.
+         */
+        missingCubeSet?: 'base' | 'throw';
+        /**
+         * Called after each `registerCubeSet` with its cost. Registering a set per
+         * tenant is real startup work, so it is reported rather than hidden; emit
+         * it to your own logger or metrics.
+         */
+        onCubeSetRegistered?: (info: CubeSetRegistrationInfo) => void;
     });
     /**
      * Set or update the database connection
@@ -65,12 +145,75 @@ export declare class SemanticLayerCompiler {
      * Validates calculated measures during registration
      */
     registerCube(cube: Cube): void;
+    /**
+     * Register the cubes that serve one tenant, overlaying the base set.
+     *
+     * Cubes are matched to the base set by name, so a set can either add cubes or
+     * replace a base cube with a tenant-specific version (the usual case for
+     * generated per-tenant dimensions). Call once per tenant at application boot;
+     * calling again for the same id replaces that set and invalidates its cached
+     * metadata and query results.
+     */
+    registerCubeSet(setId: string, cubes: Cube[]): void;
+    /**
+     * Remove a tenant's cube set. That tenant then resolves to the base set (or
+     * throws, under `missingCubeSet: 'throw'`).
+     * Returns true if the set existed.
+     */
+    unregisterCubeSet(setId: string): boolean;
+    /** Whether a cube set is registered for this id. */
+    hasCubeSet(setId: string): boolean;
+    /** Ids of every registered cube set, excluding the base set. */
+    getCubeSetIds(): string[];
+    /**
+     * Aggregate registration cost across all sets — for the single summary line
+     * worth logging after a boot loop.
+     */
+    getCubeSetStats(): CubeSetStats;
+    /**
+     * Validate and enrich a cube ahead of registration, against the cubes that
+     * will be visible alongside it.
+     */
+    private prepareCube;
+    /** Base cubes with an overlay applied over them, by cube name. */
+    private mergeWithBase;
+    /** Recompute every set's merged view — after any base-set mutation. */
+    private rebuildAllMergedSets;
+    /**
+     * Resolve the cube set serving this security context.
+     *
+     * Returns {@link BASE_CUBE_SET_ID} when no mapping is configured or the
+     * mapping yields nothing. A configured id that has no registered set falls
+     * back to the base set, or throws under `missingCubeSet: 'throw'`.
+     */
+    private resolveSetId;
+    /**
+     * The cubes this security context may see.
+     *
+     * This is the only path by which cube *contents* are read for a query,
+     * metadata, validation or MCP response — so no such path can reach a cube
+     * list without a security context. The returned map must be treated as
+     * read-only; it is the live merged view, not a copy.
+     */
+    private resolveCubes;
+    /**
+     * Cache-key component identifying which cube definitions produced a result.
+     *
+     * Appended unconditionally to every query cache key: the security-context
+     * hash is not enough, because `includeSecurityContext: false` and a custom
+     * `securityContextSerializer` can both hash two tenants identically. The
+     * generation makes re-registering a set invalidate its cached results, so a
+     * retyped or renamed dimension cannot be served stale for the TTL.
+     */
+    private cubeSetCacheKey;
     /**
      * Validate that all string-based cube references in joins resolve to registered cubes.
      * Call after all cubes are registered for strict startup validation.
      * Throws an error listing all unresolved references.
      */
     validateCubeReferences(): void;
+    /** Join targets naming a cube that is absent from the given cube scope. */
+    private unresolvedJoinRefs;
     /**
      * Validate calculated measures in a cube
      * Checks template syntax, dependency existence, and circular dependencies
@@ -79,15 +222,17 @@ export declare class SemanticLayerCompiler {
     /**
      * Get a cube by name
      */
-    getCube(name: string): Cube | undefined;
+    getCube(name: string, securityContext: SecurityContext): Cube | undefined;
     /**
      * Get all registered cubes
      */
-    getAllCubes(): Cube[];
+    getAllCubes(securityContext: SecurityContext): Cube[];
     /**
-     * Get all cubes as a Map for multi-cube queries
+     * Get all cubes as a Map for multi-cube queries.
+     *
+     * Returns the live merged view for this context — treat it as read-only.
      */
-    getAllCubesMap(): Map<string, Cube>;
+    getAllCubesMap(securityContext: SecurityContext): Map<string, Cube>;
     /**
      * Unified query execution method that handles both single and multi-cube queries
      * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
@@ -107,7 +252,7 @@ export declare class SemanticLayerCompiler {
      * Uses caching to improve performance for repeated requests
      * Cache is invalidated when cubes are modified (registerCube, removeCube, clearCubes)
      */
-    getMetadata(): CubeMetadata[];
+    getMetadata(securityContext: SecurityContext): CubeMetadata[];
     /**
      * Extract column name from Drizzle column reference
      * Handles different column types and extracts the actual column name
@@ -172,7 +317,7 @@ export declare class SemanticLayerCompiler {
     /**
      * Check if a cube exists
      */
-    hasCube(name: string): boolean;
+    hasCube(name: string, securityContext: SecurityContext): boolean;
     /**
      * Unregister a cube by name.
      * Returns true if the cube existed and was removed, false if not found.
@@ -191,15 +336,17 @@ export declare class SemanticLayerCompiler {
      * Called whenever cubes are modified
      */
     private invalidateMetadataCache;
+    /** Cubes for an already-resolved set id. */
+    private cubeSetId2Cubes;
     /**
      * Get cube names
      */
-    getCubeNames(): string[];
+    getCubeNames(securityContext: SecurityContext): string[];
     /**
      * Validate a query against registered cubes
      * Ensures all referenced cubes and fields exist
      */
-    validateQuery(query: SemanticQuery): {
+    validateQuery(query: SemanticQuery, securityContext: SecurityContext): {
         isValid: boolean;
         errors: string[];
     };

package/dist/cjs/server/execution/query-result-cache.d.ts

@@ -6,7 +6,7 @@ export declare class QueryResultCache {
      * Returns the cache key when caching is enabled and a provider is configured,
      * otherwise undefined (which disables lookup and store).
      */
-    generateKey(query: SemanticQuery, securityContext: SecurityContext): string | undefined;
+    generateKey(query: SemanticQuery, securityContext: SecurityContext, cubeSetKey?: string): string | undefined;
     /**
      * Look up a cached result. Returns the cached value (with cache metadata
      * attached) on a hit, or undefined on miss / bypass / no-cache. Emits

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

@@ -4,7 +4,10 @@ import { SemanticLayerCompiler } from './compiler.js';
  * Drizzle Cube - Semantic Layer for Drizzle ORM
  * Drizzle ORM-first semantic layer with Cube.js compatibility
  */
-export { SemanticLayerCompiler } from './compiler.js';
+export { SemanticLayerCompiler, BASE_CUBE_SET_ID, SINGLE_TENANT_CONTEXT } from './compiler.js';
+export type { CubeSetRegistrationInfo, CubeSetStats } from './compiler.js';
+export { buildAttributeDimensions } from './attribute-dimensions.js';
+export type { AttributeDefinition, AttributeValueType, BuildAttributeDimensionsOptions } from './attribute-dimensions.js';
 export { QueryExecutor } from './executor.js';
 export { detectQueryMode, detectQueryModes, getActiveQueryModes, hasComparisonMode, hasFunnelMode, hasFlowMode, hasRetentionMode } from './query-modes.js';
 export type { QueryMode, QueryModeFlags } from './query-modes.js';
@@ -29,8 +32,13 @@ export type { CubeDiscoveryResult, DiscoveryOptions, QuerySuggestion, Validation
 export type * from './types/index.js';
 export type { SQL } from 'drizzle-orm';
 /**
- * Create a new semantic layer instance with Drizzle integration
- * Use this when you need multiple isolated instances
+ * Create a new semantic layer instance with Drizzle integration.
+ *
+ * Use this when you need multiple isolated instances. To serve different cube
+ * definitions to different tenants from one instance, prefer cube sets —
+ * `new SemanticLayerCompiler({ contextToCubeSetId })` plus `registerCubeSet()`
+ * per tenant — which shares the base cubes and keeps metadata and result caches
+ * correctly partitioned.
  */
 export declare function createDrizzleSemanticLayer(options: {
     drizzle: DrizzleDatabase;

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

@@ -56,7 +56,7 @@ export interface DiscoverResponse {
  * Always returns `queryLanguageReference` and `dateFilteringGuide` alongside
  * the matched cubes. See `DiscoverResponse` for the rationale.
  */
-export declare function handleDiscover(semanticLayer: SemanticLayerCompiler, body: DiscoverRequest): Promise<DiscoverResponse>;
+export declare function handleDiscover(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: DiscoverRequest): Promise<DiscoverResponse>;
 /**
  * Normalize AI-generated query fields before validation/execution.
  * Fixes common LLM mistakes:

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

@@ -85,6 +85,14 @@ export interface SqlResult {
 export interface ExecutionOptions {
     /** Skip the cache lookup (but still cache the result for future requests) */
     skipCache?: boolean;
+    /**
+     * Identifies the cube definitions that produced the result, as
+     * `setId:baseGeneration.setGeneration`. Appended unconditionally to the query
+     * cache key so results can never be shared between tenants whose cube sets
+     * differ, nor survive a re-registration that changed a definition.
+     * Set by SemanticLayerCompiler; callers do not supply it.
+     */
+    cubeSetKey?: string;
 }
 /**
  * Core database interface that supports all Drizzle instances

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

@@ -64,6 +64,19 @@ export interface QueryContext {
      * without aggregation wrappers. Set from SemanticQuery.ungrouped.
      */
     ungrouped?: boolean;
+    /**
+     * Cast an expression to a type, in this engine's dialect (`::decimal` on
+     * Postgres, `CAST(... AS DECIMAL)` elsewhere). Strict: unparseable input
+     * fails the query on Postgres and silently yields `0` on MySQL/SQLite.
+     */
+    cast: (fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer') => SQL;
+    /**
+     * Cast an expression to a type, yielding NULL rather than failing when the
+     * input cannot be parsed. Use this over {@link QueryContext.cast} whenever
+     * the source column is free text — one dirty value should leave a row with a
+     * NULL cell, not fail the whole query.
+     */
+    tryCast: (fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer') => SQL;
 }
 /**
  * Multi-cube query context for cross-cube operations
@@ -147,7 +160,13 @@ export interface Dimension {
     sql: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
     /** Whether this is a primary key */
     primaryKey?: boolean;
-    /** Whether to show in UI */
+    /**
+     * Whether to include this dimension in generated cube metadata (`/meta`,
+     * the client field picker, AI prompts). Defaults to `true` (shown) when
+     * omitted. Setting `shown: false` hides the dimension from metadata/UI
+     * only — it remains fully usable in queries and filters, matching Cube.js
+     * semantics for `shown: false`.
+     */
     shown?: boolean;
     /** Display format */
     format?: string;
@@ -182,7 +201,13 @@ export interface Measure {
     sql?: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
     /** Display format */
     format?: string;
-    /** Whether to show in UI */
+    /**
+     * Whether to include this measure in generated cube metadata (`/meta`,
+     * the client field picker, AI prompts). Defaults to `true` (shown) when
+     * omitted. Setting `shown: false` hides the measure from metadata/UI
+     * only — it remains fully usable in queries and filters, matching Cube.js
+     * semantics for `shown: false`.
+     */
     shown?: boolean;
     /** Filters applied to this measure */
     filters?: Array<(ctx: QueryContext) => SQL>;

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

@@ -28,7 +28,7 @@ export interface DisplayOptionConfig {
     /** Display label for the option */
     label: string;
     /** Type of input control to render */
-    type: 'boolean' | 'string' | 'number' | 'select' | 'color' | 'paletteColor' | 'axisFormat' | 'stringArray' | 'buttonGroup';
+    type: 'boolean' | 'string' | 'number' | 'select' | 'color' | 'paletteColor' | 'axisFormat' | 'stringArray' | 'buttonGroup' | 'thresholdBands';
     /** Default value for the option */
     defaultValue?: any;
     /** Placeholder text for string/number inputs */

package/dist/client/charts.js

@@ -1,14 +1,14 @@
-import { ct as e, dt as t, ft as n, lt as r, mt as i, pt as a, st as o, t as s, ut as c } from "./chunks/chart-data-table-SNSqZj9B.js";
-import { d as l, l as u, s as d, u as f } from "./chunks/chart-activity-grid-DVOhLgxv.js";
-import { t as p } from "./chunks/chart-funnel-CkHSXp6h.js";
-import { a as m, i as h, n as g, o as _, r as v, s as y, t as b } from "./chunks/charts-loader-0avVzeDd.js";
-import { t as x } from "./chunks/chart-area-C-5ATxvi.js";
+import { ct as e, dt as t, ft as n, lt as r, mt as i, pt as a, st as o, t as s, ut as c } from "./chunks/chart-data-table-DgiNBOWf.js";
+import { d as l, l as u, s as d, u as f } from "./chunks/chart-activity-grid-DvD_4wJz.js";
+import { t as p } from "./chunks/chart-funnel-YLZlyN1X.js";
+import { a as m, i as h, n as g, o as _, r as v, s as y, t as b } from "./chunks/charts-loader-eToV8je7.js";
+import { t as x } from "./chunks/chart-area-DPp3hSOK.js";
 import { i as S } from "./chunks/utils-CToHkuhU.js";
-import { t as C } from "./chunks/chart-bar-CPiLaXHP.js";
-import { t as w } from "./chunks/chart-line-CzvVL3Be.js";
-import { t as T } from "./chunks/chart-pie-CwRfwWWZ.js";
-import { t as E } from "./chunks/chart-scatter-BtLfAsZb.js";
-import { t as D } from "./chunks/chart-radar-Dfql2E7i.js";
-import { t as O } from "./chunks/chart-radial-bar-oE9OZ1IX.js";
-import { t as k } from "./chunks/chart-tree-map-DU5M3-qe.js";
+import { t as C } from "./chunks/chart-bar-Od3pOyZ0.js";
+import { t as w } from "./chunks/chart-line-NCmpxBfE.js";
+import { t as T } from "./chunks/chart-pie-ChrasEI8.js";
+import { t as E } from "./chunks/chart-scatter-DgcEF-kI.js";
+import { t as D } from "./chunks/chart-radar-CxSVF7yL.js";
+import { t as O } from "./chunks/chart-radial-bar--SN0Wph0.js";
+import { t as k } from "./chunks/chart-tree-map-DeDXveVd.js";
 export { d as CHART_COLORS, u as CHART_MARGINS, s as DataTable, p as FunnelChart, b as LazyChart, f as NEGATIVE_COLOR, l as POSITIVE_COLOR, x as RechartsAreaChart, C as RechartsBarChart, w as RechartsLineChart, T as RechartsPieChart, D as RechartsRadarChart, O as RechartsRadialBarChart, E as RechartsScatterChart, k as RechartsTreeMapChart, o as clearChartConfigCache, S as formatChartData, g as getAvailableChartTypes, e as getChartConfigAsync, r as getChartConfigSync, v as getUnavailableChartTypes, c as isChartConfigLoaded, h as isChartTypeAvailable, m as isValidChartType, t as loadAllChartConfigs, _ as preloadChart, n as preloadChartConfig, a as preloadChartConfigs, y as preloadCharts, i as useChartConfig };