@lightdash/query-sdk 1.85.1 → 1.86.0

package/README.md

@@ -92,10 +92,18 @@ lightdash
         { field: 'amount', operator: 'greaterThan', value: 1000 },
         { field: 'order_date', operator: 'inThePast', value: 90, unit: 'days' },
     ])
+    .metricFilters([
+        { field: 'total_revenue', operator: 'greaterThanOrEqual', value: 5000 },
+    ])
     .sorts([{ field: 'total_revenue', direction: 'desc' }])
     .limit(100);
 ```
 
+`.filters()` accepts dimensions and serializes them as WHERE filters.
+`.metricFilters()` accepts metrics and serializes them as HAVING filters. A
+metric can be used only as a filter and does not need to be selected with
+`.metrics()`.
+
 Supported filter operators: `equals`, `notEquals`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `inThePast`, `notInThePast`, `inTheNext`, `inTheCurrent`, `notInTheCurrent`, `inBetween`, `notInBetween`, `isNull`, `notNull`, `startsWith`, `endsWith`, `include`, `doesNotInclude`.
 
 ## Parameters

package/dist/apiTransport.js

@@ -20,27 +20,31 @@ const sleep = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
 /**
- * Convert SDK filter definitions into the Lightdash API filter format.
- * The API expects { dimensions: { id, and: [...rules] } }
+ * Convert SDK dimension and metric filter definitions into the Lightdash API
+ * filter format.
  */
-function buildApiFilters(filters) {
-    if (filters.length === 0) {
-        return {};
-    }
-    // For now, all filters are AND-ed on dimensions.
-    // TODO: support metric filters and OR groups
-    const rules = filters.map((f, i) => ({
-        id: `sdk-filter-${i}`,
-        target: { fieldId: f.fieldId },
-        operator: f.operator,
-        values: f.values,
-        ...(f.settings ? { settings: f.settings } : {}),
-    }));
+function buildApiFilters(dimensionFilters, metricFilters = []) {
+    const buildGroup = (filters, rootId, ruleIdPrefix) => ({
+        id: rootId,
+        and: filters.map((filter, index) => ({
+            id: `${ruleIdPrefix}-${index}`,
+            target: { fieldId: filter.fieldId },
+            operator: filter.operator,
+            values: filter.values,
+            ...(filter.settings ? { settings: filter.settings } : {}),
+        })),
+    });
     return {
-        dimensions: {
-            id: 'sdk-root',
-            and: rules,
-        },
+        ...(dimensionFilters.length > 0
+            ? {
+                dimensions: buildGroup(dimensionFilters, 'sdk-root', 'sdk-filter'),
+            }
+            : {}),
+        ...(metricFilters.length > 0
+            ? {
+                metrics: buildGroup(metricFilters, 'sdk-metric-root', 'sdk-metric-filter'),
+            }
+            : {}),
     };
 }
 const createFieldQualifier = (table) => (fieldId) => {
@@ -123,6 +127,9 @@ function buildMetricQueryBody(query, qualify, limit = query.limit) {
             filters: buildApiFilters(query.filters.map((f) => ({
                 ...f,
                 fieldId: qualify(f.fieldId),
+            })), (query.metricFilters ?? []).map((f) => ({
+                ...f,
+                fieldId: qualify(f.fieldId),
             }))),
             sorts: query.sorts.map((s) => ({
                 fieldId: qualify(s.fieldId),

package/dist/features.js

@@ -13,6 +13,12 @@ export const SDK_FEATURES = [
         label: 'Semantic layer queries',
         description: 'Run metric and dimension queries against the Lightdash semantic layer.',
     },
+    {
+        key: 'metric-filters',
+        label: 'Metric filters',
+        description: 'Filter grouped query results by metric values, including metrics used only as filters.',
+        wiring: 'Pass metric filter rules to query(...).metricFilters([...]); keep dimension filter rules in .filters([...]).',
+    },
     {
         key: 'saved-chart',
         label: 'Saved chart queries',

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.85.1";
+export declare const SDK_VERSION = "1.86.0";

package/dist/generated/sdkVersion.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generateSdkVersion.mjs (prebuild) — do not edit.
-export const SDK_VERSION = '1.85.1';
+export const SDK_VERSION = '1.86.0';

package/dist/query.d.ts

@@ -6,6 +6,7 @@
  *     .dimensions(['customer_segment', 'order_date'])
  *     .metrics(['total_revenue', 'order_count'])
  *     .filters([{ field: 'order_date', operator: 'inThePast', value: 90, unit: 'days' }])
+ *     .metricFilters([{ field: 'total_revenue', operator: 'greaterThan', value: 1000 }])
  *     .sorts([{ field: 'total_revenue', direction: 'desc' }])
  *     .limit(100)
  *
@@ -17,6 +18,7 @@ type BuilderState = {
     dimensions: string[];
     metrics: string[];
     filters: InternalFilterDefinition[];
+    metricFilters: InternalFilterDefinition[];
     sorts: {
         fieldId: string;
         descending: boolean;
@@ -49,8 +51,10 @@ export declare class QueryBuilder {
     dimensions(fields: string[]): QueryBuilder;
     /** Set metric fields (aggregations) */
     metrics(fields: string[]): QueryBuilder;
-    /** Add filters */
+    /** Add dimension (WHERE) filters */
     filters(filters: Filter[]): QueryBuilder;
+    /** Add metric (HAVING) filters. The metrics do not need to be selected. */
+    metricFilters(filters: Filter[]): QueryBuilder;
     /** Add sorts */
     sorts(sorts: Sort[]): QueryBuilder;
     /** Add table calculations (computed columns evaluated after the query) */

package/dist/query.js

@@ -6,6 +6,7 @@
  *     .dimensions(['customer_segment', 'order_date'])
  *     .metrics(['total_revenue', 'order_count'])
  *     .filters([{ field: 'order_date', operator: 'inThePast', value: 90, unit: 'days' }])
+ *     .metricFilters([{ field: 'total_revenue', operator: 'greaterThan', value: 1000 }])
  *     .sorts([{ field: 'total_revenue', direction: 'desc' }])
  *     .limit(100)
  *
@@ -32,6 +33,7 @@ export class QueryBuilder {
                 dimensions: [],
                 metrics: [],
                 filters: [],
+                metricFilters: [],
                 sorts: [],
                 tableCalculations: [],
                 additionalMetrics: [],
@@ -73,12 +75,21 @@ export class QueryBuilder {
             metrics: [...this._state.metrics, ...fields],
         });
     }
-    /** Add filters */
+    /** Add dimension (WHERE) filters */
     filters(filters) {
         return this._clone({
             filters: [...this._state.filters, ...toInternalFilters(filters)],
         });
     }
+    /** Add metric (HAVING) filters. The metrics do not need to be selected. */
+    metricFilters(filters) {
+        return this._clone({
+            metricFilters: [
+                ...this._state.metricFilters,
+                ...toInternalFilters(filters),
+            ],
+        });
+    }
     /** Add sorts */
     sorts(sorts) {
         const converted = sorts.map((s) => ({
@@ -135,6 +146,7 @@ export class QueryBuilder {
             dimensions: this._state.dimensions,
             metrics: this._state.metrics,
             filters: this._state.filters,
+            metricFilters: this._state.metricFilters,
             sorts: this._state.sorts,
             tableCalculations: this._state.tableCalculations,
             additionalMetrics: this._state.additionalMetrics,

package/dist/savedChart.d.ts

@@ -6,7 +6,7 @@ import type { AdditionalMetric, CustomDimension, Filter, InternalFilterDefinitio
  *
  * CRITICAL: this mirrors the ENTIRE chainable `QueryBuilder` surface. Generated
  * apps chain builder methods on every query (`.dimensions().metrics().filters()
- * .sorts().label().limit()…`); calling a method that doesn't exist on a plain
+ * .metricFilters().sorts().label().limit()…`); calling a method that doesn't exist on a plain
  * object throws `TypeError: X is not a function` and crashes the whole app. So a
  * linked chart must be exactly as crash-safe as a normal query — every method
  * below exists and is chainable.
@@ -41,6 +41,7 @@ export type SavedChartQuery = {
     tableCalculations: (calcs: TableCalculation[]) => SavedChartQuery;
     additionalMetrics: (metrics: AdditionalMetric[]) => SavedChartQuery;
     customDimensions: (dims: CustomDimension[]) => SavedChartQuery;
+    metricFilters: (filters: Filter[]) => SavedChartQuery;
 };
 export declare function savedChart(chartUuid: string, label?: string): SavedChartQuery;
 /** Identity key for a saved-chart query — anything that changes the run must change the key. */

package/dist/savedChart.js

@@ -31,6 +31,7 @@ export function savedChart(chartUuid, label) {
             tableCalculations: () => self,
             additionalMetrics: () => self,
             customDimensions: () => self,
+            metricFilters: () => self,
         };
         return self;
     };

package/dist/types.d.ts

@@ -73,7 +73,10 @@ export type QueryDefinition = {
     exploreName: string;
     dimensions: string[];
     metrics: string[];
+    /** Dimension (WHERE) filters added with `.filters()`. */
     filters: InternalFilterDefinition[];
+    /** Metric (HAVING) filters added with `.metricFilters()`. Optional for definitions built by older SDK versions. */
+    metricFilters?: InternalFilterDefinition[];
     sorts: {
         fieldId: string;
         descending: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "1.85.1",
+  "version": "1.86.0",
   "private": false,
   "type": "module",
   "description": "SDK for building custom data apps against the Lightdash semantic layer",
@@ -34,7 +34,7 @@
     "jsdom": "26.1.0",
     "typescript": "7.0.2",
     "vitest": "4.1.6",
-    "@lightdash/common": "1.85.1"
+    "@lightdash/common": "1.86.0"
   },
   "scripts": {
     "prebuild": "node ./scripts/generateSdkVersion.mjs",