@lightdash/query-sdk 0.2776.0 → 0.2778.0

package/dist/apiTransport.js

@@ -89,9 +89,21 @@ export function createApiTransport(config, adapter) {
             // Lightdash field IDs are `{table}_{column}`.
             // The SDK lets users write short names like 'driver_name'
             // and we qualify them to 'fct_race_results_driver_name'.
-            const qualify = (fieldId) => fieldId.startsWith(`${table}_`)
-                ? fieldId
-                : `${table}_${fieldId}`;
+            //
+            // For joined table fields, use dot notation: 'customers.name'
+            // which resolves to 'customers_name' (not 'orders_customers_name').
+            const qualify = (fieldId) => {
+                // Dot notation: 'customers.name' → 'customers_name'
+                if (fieldId.includes('.')) {
+                    return fieldId.replace('.', '_');
+                }
+                // Already qualified with explore name
+                if (fieldId.startsWith(`${table}_`)) {
+                    return fieldId;
+                }
+                // Short name → qualify with explore name
+                return `${table}_${fieldId}`;
+            };
             const qualifiedDims = query.dimensions.map(qualify);
             const qualifiedMetrics = query.metrics.map(qualify);
             // Step 1: Execute async query
@@ -110,6 +122,12 @@ export function createApiTransport(config, adapter) {
                     })),
                     limit: query.limit,
                     tableCalculations: query.tableCalculations,
+                    ...(query.additionalMetrics.length > 0
+                        ? { additionalMetrics: query.additionalMetrics }
+                        : {}),
+                    ...(query.customDimensions.length > 0
+                        ? { customDimensions: query.customDimensions }
+                        : {}),
                 },
             };
             // Pass label as transport metadata (not in the API body)

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { useLightdash } from './useLightdash';
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 export { createApiTransport, type FetchAdapter } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
-export type { Column, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, } from './types';
+export type { AdditionalMetric, Column, CustomDimension, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, MetricType, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, } from './types';
 export type { SdkFetchRequest, SdkFetchResponse, SdkReadyMessage, } from './postMessageTransport';

package/dist/query.d.ts

@@ -11,7 +11,22 @@
  *
  * The builder is immutable -- each method returns a new instance.
  */
-import type { Filter, InternalFilterDefinition, QueryDefinition, Sort, TableCalculation } from './types';
+import type { AdditionalMetric, CustomDimension, Filter, InternalFilterDefinition, QueryDefinition, Sort, TableCalculation } from './types';
+type BuilderState = {
+    explore: string;
+    dimensions: string[];
+    metrics: string[];
+    filters: InternalFilterDefinition[];
+    sorts: {
+        fieldId: string;
+        descending: boolean;
+    }[];
+    tableCalculations: TableCalculation[];
+    additionalMetrics: AdditionalMetric[];
+    customDimensions: CustomDimension[];
+    limit: number;
+    label: string | undefined;
+};
 /**
  * Create a query builder for a model.
  *
@@ -23,18 +38,10 @@ import type { Filter, InternalFilterDefinition, QueryDefinition, Sort, TableCalc
  */
 export declare function query(modelName: string): QueryBuilder;
 export declare class QueryBuilder {
-    private readonly _explore;
-    private readonly _dimensions;
-    private readonly _metrics;
-    private readonly _filters;
-    private readonly _sorts;
-    private readonly _tableCalculations;
-    private readonly _limit;
-    private readonly _label;
-    constructor(explore: string, dimensions?: string[], metrics?: string[], filters?: InternalFilterDefinition[], sorts?: {
-        fieldId: string;
-        descending: boolean;
-    }[], limit?: number, label?: string, tableCalculations?: TableCalculation[]);
+    private readonly _state;
+    constructor(explore: string);
+    constructor(state: BuilderState);
+    private _clone;
     /** Human-readable label for dev tools / query inspector */
     label(name: string): QueryBuilder;
     /** Set dimension fields (GROUP BY columns) */
@@ -47,8 +54,18 @@ export declare class QueryBuilder {
     sorts(sorts: Sort[]): QueryBuilder;
     /** Add table calculations (computed columns evaluated after the query) */
     tableCalculations(calcs: TableCalculation[]): QueryBuilder;
+    /**
+     * Add additional metrics (ad-hoc aggregations defined at query time).
+     * Use this for metrics on joined tables or custom aggregations not in the YAML.
+     */
+    additionalMetrics(metrics: AdditionalMetric[]): QueryBuilder;
+    /**
+     * Add custom dimensions (ad-hoc dimensions defined at query time).
+     */
+    customDimensions(dims: CustomDimension[]): QueryBuilder;
     /** Set the maximum number of rows to return (default: 500) */
     limit(n: number): QueryBuilder;
     /** Convert to a plain QueryDefinition object */
     build(): QueryDefinition;
 }
+export {};

package/dist/query.js

@@ -24,27 +24,43 @@ export function query(modelName) {
     return new QueryBuilder(modelName);
 }
 export class QueryBuilder {
-    constructor(explore, dimensions = [], metrics = [], filters = [], sorts = [], limit = 500, label, tableCalculations = []) {
-        this._explore = explore;
-        this._dimensions = dimensions;
-        this._metrics = metrics;
-        this._filters = filters;
-        this._sorts = sorts;
-        this._tableCalculations = tableCalculations;
-        this._limit = limit;
-        this._label = label;
+    constructor(exploreOrState) {
+        if (typeof exploreOrState === 'string') {
+            this._state = {
+                explore: exploreOrState,
+                dimensions: [],
+                metrics: [],
+                filters: [],
+                sorts: [],
+                tableCalculations: [],
+                additionalMetrics: [],
+                customDimensions: [],
+                limit: 500,
+                label: undefined,
+            };
+        }
+        else {
+            this._state = exploreOrState;
+        }
+    }
+    _clone(overrides) {
+        return new QueryBuilder({ ...this._state, ...overrides });
     }
     /** Human-readable label for dev tools / query inspector */
     label(name) {
-        return new QueryBuilder(this._explore, this._dimensions, this._metrics, this._filters, this._sorts, this._limit, name, this._tableCalculations);
+        return this._clone({ label: name });
     }
     /** Set dimension fields (GROUP BY columns) */
     dimensions(fields) {
-        return new QueryBuilder(this._explore, [...this._dimensions, ...fields], this._metrics, this._filters, this._sorts, this._limit, this._label, this._tableCalculations);
+        return this._clone({
+            dimensions: [...this._state.dimensions, ...fields],
+        });
     }
     /** Set metric fields (aggregations) */
     metrics(fields) {
-        return new QueryBuilder(this._explore, this._dimensions, [...this._metrics, ...fields], this._filters, this._sorts, this._limit, this._label, this._tableCalculations);
+        return this._clone({
+            metrics: [...this._state.metrics, ...fields],
+        });
     }
     /** Add filters */
     filters(filters) {
@@ -65,7 +81,9 @@ export class QueryBuilder {
                 settings: f.unit ? { unitOfTime: f.unit } : null,
             };
         });
-        return new QueryBuilder(this._explore, this._dimensions, this._metrics, [...this._filters, ...converted], this._sorts, this._limit, this._label, this._tableCalculations);
+        return this._clone({
+            filters: [...this._state.filters, ...converted],
+        });
     }
     /** Add sorts */
     sorts(sorts) {
@@ -73,27 +91,50 @@ export class QueryBuilder {
             fieldId: s.field,
             descending: s.direction === 'desc',
         }));
-        return new QueryBuilder(this._explore, this._dimensions, this._metrics, this._filters, [...this._sorts, ...converted], this._limit, this._label, this._tableCalculations);
+        return this._clone({
+            sorts: [...this._state.sorts, ...converted],
+        });
     }
     /** Add table calculations (computed columns evaluated after the query) */
     tableCalculations(calcs) {
-        return new QueryBuilder(this._explore, this._dimensions, this._metrics, this._filters, this._sorts, this._limit, this._label, [...this._tableCalculations, ...calcs]);
+        return this._clone({
+            tableCalculations: [...this._state.tableCalculations, ...calcs],
+        });
+    }
+    /**
+     * Add additional metrics (ad-hoc aggregations defined at query time).
+     * Use this for metrics on joined tables or custom aggregations not in the YAML.
+     */
+    additionalMetrics(metrics) {
+        return this._clone({
+            additionalMetrics: [...this._state.additionalMetrics, ...metrics],
+        });
+    }
+    /**
+     * Add custom dimensions (ad-hoc dimensions defined at query time).
+     */
+    customDimensions(dims) {
+        return this._clone({
+            customDimensions: [...this._state.customDimensions, ...dims],
+        });
     }
     /** Set the maximum number of rows to return (default: 500) */
     limit(n) {
-        return new QueryBuilder(this._explore, this._dimensions, this._metrics, this._filters, this._sorts, n, this._label, this._tableCalculations);
+        return this._clone({ limit: n });
     }
     /** Convert to a plain QueryDefinition object */
     build() {
         return {
-            exploreName: this._explore,
-            dimensions: this._dimensions,
-            metrics: this._metrics,
-            filters: this._filters,
-            sorts: this._sorts,
-            tableCalculations: this._tableCalculations,
-            limit: this._limit,
-            ...(this._label ? { label: this._label } : {}),
+            exploreName: this._state.explore,
+            dimensions: this._state.dimensions,
+            metrics: this._state.metrics,
+            filters: this._state.filters,
+            sorts: this._state.sorts,
+            tableCalculations: this._state.tableCalculations,
+            additionalMetrics: this._state.additionalMetrics,
+            customDimensions: this._state.customDimensions,
+            limit: this._state.limit,
+            ...(this._state.label ? { label: this._state.label } : {}),
         };
     }
 }

package/dist/types.d.ts

@@ -22,6 +22,33 @@ export type TableCalculation = {
     /** SQL expression for the calculation */
     sql: string;
 };
+export type MetricType = 'average' | 'count' | 'count_distinct' | 'sum' | 'sum_distinct' | 'min' | 'max' | 'number' | 'median' | 'percentile';
+export type AdditionalMetric = {
+    /** Internal name of the metric (used as the field ID in results) */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Table the metric belongs to */
+    table: string;
+    /** Aggregation type */
+    type: MetricType;
+    /** SQL expression (e.g., ${TABLE}.column_name) */
+    sql: string;
+    /** Description of what the metric measures */
+    description?: string;
+};
+export type CustomDimension = {
+    /** Unique ID for the custom dimension */
+    id: string;
+    /** Internal name */
+    name: string;
+    /** Table the dimension belongs to */
+    table: string;
+    /** SQL expression */
+    sql: string;
+    /** The dimension type */
+    dimensionId: string;
+};
 export type InternalFilterDefinition = {
     fieldId: string;
     operator: string;
@@ -40,6 +67,8 @@ export type QueryDefinition = {
         descending: boolean;
     }[];
     tableCalculations: TableCalculation[];
+    additionalMetrics: AdditionalMetric[];
+    customDimensions: CustomDimension[];
     limit: number;
     /** Human-readable label for dev tools / query inspector (not sent to the API) */
     label?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "0.2776.0",
+  "version": "0.2778.0",
   "private": false,
   "type": "module",
   "description": "SDK for building custom data apps against the Lightdash semantic layer",