@lightdash/query-sdk 0.2787.0 → 0.2789.0

package/dist/drillDown.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Drill-down helper — builds a new query from a clicked row.
+ *
+ * Usage:
+ *   const dq = drillDown({
+ *       sourceQuery: revenueBySegment,
+ *       metric: 'total_revenue',
+ *       dimension: 'order_date',
+ *       row: clickedRow,
+ *   });
+ *   // Pass dq to useLightdash() to execute
+ */
+import { QueryBuilder } from './query';
+import type { Row } from './types';
+export type DrillDownOptions = {
+    /** The original query builder that produced the data */
+    sourceQuery: QueryBuilder;
+    /** The metric to drill into */
+    metric: string;
+    /** The dimension to drill by */
+    dimension: string;
+    /** The clicked row — its dimension values become equality filters */
+    row: Row;
+    /** Optional label for the drill query (shown in query inspector) */
+    label?: string;
+};
+/**
+ * Build a drill-down query from a clicked row.
+ *
+ * Takes the source query's dimension values from the clicked row and turns
+ * them into equality filters, then queries the same metric grouped by the
+ * chosen drill-by dimension.
+ *
+ * Returns a new QueryBuilder that can be passed to useLightdash().
+ */
+export declare function drillDown(options: DrillDownOptions): QueryBuilder;

package/dist/drillDown.js

@@ -0,0 +1,54 @@
+/**
+ * Drill-down helper — builds a new query from a clicked row.
+ *
+ * Usage:
+ *   const dq = drillDown({
+ *       sourceQuery: revenueBySegment,
+ *       metric: 'total_revenue',
+ *       dimension: 'order_date',
+ *       row: clickedRow,
+ *   });
+ *   // Pass dq to useLightdash() to execute
+ */
+import { QueryBuilder } from './query';
+/**
+ * Build a drill-down query from a clicked row.
+ *
+ * Takes the source query's dimension values from the clicked row and turns
+ * them into equality filters, then queries the same metric grouped by the
+ * chosen drill-by dimension.
+ *
+ * Returns a new QueryBuilder that can be passed to useLightdash().
+ */
+export function drillDown(options) {
+    const { sourceQuery, metric, dimension, row, label } = options;
+    const sourceDef = sourceQuery.build();
+    // Build equality filters from the clicked row's dimension values
+    const rowFilters = sourceDef.dimensions.map((dimFieldId) => {
+        const value = row[dimFieldId];
+        if (value === null || value === undefined) {
+            return { field: dimFieldId, operator: 'isNull' };
+        }
+        return {
+            field: dimFieldId,
+            operator: 'equals',
+            value: value,
+        };
+    });
+    // Carry forward existing filters from the source query
+    const sourceFilters = sourceDef.filters.map((f) => ({
+        field: f.fieldId,
+        operator: f.operator,
+        ...(f.values.length > 0
+            ? { value: f.values.length === 1 ? f.values[0] : f.values }
+            : {}),
+        ...(f.settings?.unitOfTime ? { unit: f.settings.unitOfTime } : {}),
+    }));
+    return new QueryBuilder(sourceDef.exploreName)
+        .label(label ?? `[Drill down] ${metric} by ${dimension}`)
+        .dimensions([dimension])
+        .metrics([metric])
+        .filters([...sourceFilters, ...rowFilters])
+        .sorts([{ field: dimension, direction: 'asc' }])
+        .limit(500);
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { query } from './query';
+export { drillDown } from './drillDown';
 export { createClient, LightdashClient } from './client';
 export { useLightdash } from './useLightdash';
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';

package/dist/index.js

@@ -1,5 +1,7 @@
 // Query builder
 export { query } from './query';
+// Drill-down helper
+export { drillDown } from './drillDown';
 // Client
 export { createClient, LightdashClient } from './client';
 // React hook

package/package.json

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