drizzle-cube 0.7.1 → 0.8.1

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

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

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

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

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

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

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

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

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

@@ -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/cjs/server/builders/group-by-builder.d.ts

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

package/dist/cjs/server/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,72 @@
 import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types/index.js';
+import { QueryValidationResult } from './query-validator.js';
 import { PlanOptimiser } from './logical-plan/index.js';
 export { validateQueryAgainstCubes } from './query-validator.js';
+export type { QueryValidationIssue, QueryValidationResult } from './query-validator.js';
+/**
+ * Identifier of the base cube set — the cubes registered with {@link
+ * SemanticLayerCompiler.registerCube}, shared by every tenant. The empty string
+ * 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 +92,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 +147,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 +224,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 +254,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 +319,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,18 +338,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): {
-        isValid: boolean;
-        errors: string[];
-    };
+    validateQuery(query: SemanticQuery, securityContext: SecurityContext): QueryValidationResult;
     /**
      * Analyze query planning decisions for debugging and transparency
      * Returns detailed metadata about how the query would be planned

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

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

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

@@ -4,7 +4,12 @@ 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 { QueryValidationError } from './query-validator.js';
+export type { QueryValidationIssue, QueryValidationResult } from './query-validator.js';
+export { buildAttributeDimensions } from './attribute-dimensions.js';
+export type { AttributeDefinition, AttributeValueType, BuildAttributeDimensionsOptions } from './attribute-dimensions.js';
 export { QueryExecutor } from './executor.js';
 export { detectQueryMode, detectQueryModes, getActiveQueryModes, hasComparisonMode, hasFunnelMode, hasFlowMode, hasRetentionMode } from './query-modes.js';
 export type { QueryMode, QueryModeFlags } from './query-modes.js';
@@ -29,8 +34,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:
@@ -76,4 +76,5 @@ export declare function handleLoad(semanticLayer: SemanticLayerCompiler, securit
     data: Record<string, unknown>[];
     annotation: any;
     query: SemanticQuery;
+    total?: number;
 }>;