tplm-lang 0.3.6 → 0.3.7

package/dist/compiler/grid-spec-builder.d.ts

@@ -23,6 +23,11 @@ export interface BuildGridSpecOptions {
     malloyQueries?: MalloyQuerySpec[];
     /** Ordering provider for definition-order sorting */
     orderingProvider?: DimensionOrderingProvider;
+    /**
+     * Raw SQL queries by query ID, captured from the Malloy runtime.
+     * When provided, each CellValue will include `sql` and `cellSQL` fields.
+     */
+    sqlQueries?: Map<string, string>;
 }
 /**
  * Build a GridSpec from a TableSpec and query results.

package/dist/compiler/grid-spec-builder.js

@@ -102,12 +102,14 @@ export function buildGridSpec(spec, plan, results, malloyQueriesOrOptions) {
     // Handle both old signature (array) and new signature (options object)
     let malloyQueries;
     let orderingProvider;
+    let sqlQueries;
     if (Array.isArray(malloyQueriesOrOptions)) {
         malloyQueries = malloyQueriesOrOptions;
     }
     else if (malloyQueriesOrOptions) {
         malloyQueries = malloyQueriesOrOptions.malloyQueries;
         orderingProvider = malloyQueriesOrOptions.orderingProvider;
+        sqlQueries = malloyQueriesOrOptions.sqlQueries;
     }
     // Set module-level ordering provider for definition-order sorting
     currentOrderingProvider = orderingProvider;
@@ -174,7 +176,7 @@ export function buildGridSpec(spec, plan, results, malloyQueriesOrOptions) {
             }
         }
         // Build cell lookup (value-based)
-        const cellLookup = buildCellLookup(spec, plan, results, invertedQueries, flatQueries);
+        const cellLookup = buildCellLookup(spec, plan, results, invertedQueries, flatQueries, sqlQueries);
         // Check for totals
         const hasRowTotal = axisHasTotal(spec.rowAxis);
         const hasColTotal = axisHasTotal(spec.colAxis);
@@ -1023,6 +1025,37 @@ function makeCellKey(rowValues, colValues) {
         .map(([k, v]) => `${k}=${v}`)
         .join("|");
 }
+/**
+ * Build a cell-specific SQL query by wrapping the base SQL with a WHERE clause
+ * that narrows to the specific dimension values for this cell.
+ */
+function buildCellSQL(baseSQL, rowValues, colValues) {
+    const conditions = [];
+    const addCondition = (dim, val) => {
+        if (typeof val === "number") {
+            conditions.push(`${quoteIdentifier(dim)} = ${val}`);
+        }
+        else {
+            conditions.push(`${quoteIdentifier(dim)} = '${val.replace(/'/g, "''")}'`);
+        }
+    };
+    for (const [dim, val] of rowValues) {
+        addCondition(dim, val);
+    }
+    for (const [dim, val] of colValues) {
+        addCondition(dim, val);
+    }
+    if (conditions.length === 0)
+        return baseSQL;
+    // Wrap: SELECT * FROM (baseSQL) AS _tpl WHERE conditions
+    return `SELECT * FROM (\n${baseSQL}\n) AS _tpl_base\nWHERE ${conditions.join(" AND ")}`;
+}
+/**
+ * Quote a SQL identifier with double quotes.
+ */
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
 /**
  * Build a cell lookup function from query results.
  *
@@ -1032,9 +1065,10 @@ function makeCellKey(rowValues, colValues) {
  *
  * @param invertedQueries Set of query IDs that have inverted axes (column dim is outer in Malloy)
  * @param flatQueries Set of query IDs that use flat structure (all dims in single group_by)
+ * @param sqlQueries Optional map of query ID → SQL string for attribution
  */
-function buildCellLookup(spec, plan, results, invertedQueries, flatQueries = new Set()) {
-    // Build an index: cellKey → aggregateName → value
+function buildCellLookup(spec, plan, results, invertedQueries, flatQueries = new Set(), sqlQueries) {
+    // Build an index: cellKey → aggregateName → CellEntry (value + queryId)
     const cellIndex = new Map();
     // Index all query results by plan query ID
     // Since we now use a unified QueryPlan system, IDs should match directly
@@ -1078,12 +1112,24 @@ function buildCellLookup(spec, plan, results, invertedQueries, flatQueries = new
                     pathDescription: cellKey,
                 };
             }
-            const value = cellData.get(aggName) ?? null;
+            const entry = cellData.get(aggName);
+            const value = entry?.value ?? null;
+            // Build SQL attribution if available
+            let sql;
+            let cellSQL;
+            if (sqlQueries && entry?.queryId) {
+                sql = sqlQueries.get(entry.queryId);
+                if (sql) {
+                    cellSQL = buildCellSQL(sql, rowValues, colValues);
+                }
+            }
             return {
                 raw: value,
                 formatted: formatValue(value, agg),
                 aggregate: aggName,
                 pathDescription: cellKey,
+                sql,
+                cellSQL,
             };
         },
     };
@@ -1129,7 +1175,7 @@ function indexQueryResults(data, query, cellIndex, aggregates, isInverted = fals
     new Map(), // values for malloy nested (will be mapped to correct axis)
     cellIndex, 0, isInverted, query.rowGroupings, // logical row groupings
     query.colGroupings, // logical col groupings
-    primarySuffix);
+    primarySuffix, query.id);
     // Handle merged queries with additional column variants
     // Each variant has its own nests (e.g., by_gender vs by_sector_label)
     // that need to be indexed separately
@@ -1147,7 +1193,7 @@ function indexQueryResults(data, query, cellIndex, aggregates, isInverted = fals
                 seenFirstDims.set(firstDim, count + 1);
                 nestNameSuffix = count > 0 ? `_${count}` : "";
             }
-            flattenAndIndex(data, malloyRowGroupings, variantColGroupings, aggregates, new Map(), new Map(), cellIndex, 0, isInverted, query.rowGroupings, variant.colGroupings, nestNameSuffix);
+            flattenAndIndex(data, malloyRowGroupings, variantColGroupings, aggregates, new Map(), new Map(), cellIndex, 0, isInverted, query.rowGroupings, variant.colGroupings, nestNameSuffix, query.id);
         }
     }
 }
@@ -1192,7 +1238,7 @@ function indexFlatQueryResults(data, query, cellIndex, aggregates) {
             }
         }
         // Index aggregate values using the combined row/col values
-        indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex);
+        indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex, query.id);
     }
 }
 /**
@@ -1205,7 +1251,7 @@ function indexFlatQueryResults(data, query, cellIndex, aggregates) {
  * @param logicalColGroupings The actual col groupings for cell key building
  * @param nestNameSuffix Suffix for nest names (e.g., '_1' for merged query variants)
  */
-function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggregates, baseOuterValues, baseNestedValues, cellIndex, outerDepth, isInverted = false, logicalRowGroupings, logicalColGroupings, nestNameSuffix = "") {
+function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggregates, baseOuterValues, baseNestedValues, cellIndex, outerDepth, isInverted = false, logicalRowGroupings, logicalColGroupings, nestNameSuffix = "", queryId) {
     for (const row of data) {
         // Build outer values - collect ALL outer dimension values from the current row
         // This handles the case where multiple dimensions are in the same group_by
@@ -1234,7 +1280,7 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
                 const nestedKey = `by_${dim}${nestNameSuffix}`;
                 if (row[nestedKey] && Array.isArray(row[nestedKey])) {
                     // This dimension is nested - recurse
-                    flattenAndIndex(row[nestedKey], malloyOuterGroupings, malloyNestedGroupings, aggregates, currentOuterValues, baseNestedValues, cellIndex, i, isInverted, logicalRowGroupings, logicalColGroupings, nestNameSuffix);
+                    flattenAndIndex(row[nestedKey], malloyOuterGroupings, malloyNestedGroupings, aggregates, currentOuterValues, baseNestedValues, cellIndex, i, isInverted, logicalRowGroupings, logicalColGroupings, nestNameSuffix, queryId);
                     break; // Don't continue with this row, we recursed
                 }
             }
@@ -1247,7 +1293,7 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
             continue; // Skipped this row because we recursed into nested data
         }
         if (malloyNestedGroupings.length > 0) {
-            indexColumnPivots(row, malloyNestedGroupings, aggregates, currentOuterValues, new Map(), cellIndex, 0, isInverted, nestNameSuffix);
+            indexColumnPivots(row, malloyNestedGroupings, aggregates, currentOuterValues, new Map(), cellIndex, 0, isInverted, nestNameSuffix, queryId);
         }
         else {
             // Direct aggregate values
@@ -1256,10 +1302,10 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
             if (isInverted) {
                 indexAggregateValues(row, aggregates, baseNestedValues, // These are actually the row values (empty when no nesting)
                 currentOuterValues, // These are actually the col values
-                cellIndex);
+                cellIndex, queryId);
             }
             else {
-                indexAggregateValues(row, aggregates, currentOuterValues, baseNestedValues, cellIndex);
+                indexAggregateValues(row, aggregates, currentOuterValues, baseNestedValues, cellIndex, queryId);
             }
         }
     }
@@ -1273,7 +1319,7 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
  * @param nestNameSuffix Suffix for nest names (e.g., '_1' for merged query variants).
  *   Only applied to the outermost nest (nestedDepth === 0) to match Malloy query structure.
  */
-function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNestedValues, cellIndex, nestedDepth, isInverted = false, nestNameSuffix = "") {
+function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNestedValues, cellIndex, nestedDepth, isInverted = false, nestNameSuffix = "", queryId) {
     const currentDim = nestedGroupings[nestedDepth];
     const remainingDims = nestedGroupings.slice(nestedDepth);
     // First try the single dimension key
@@ -1311,10 +1357,10 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
                 if (isInverted) {
                     indexAggregateValues(nestedRow, aggregates, currentNestedValues, // These are actually row values
                     outerValues, // These are actually col values
-                    cellIndex);
+                    cellIndex, queryId);
                 }
                 else {
-                    indexAggregateValues(nestedRow, aggregates, outerValues, currentNestedValues, cellIndex);
+                    indexAggregateValues(nestedRow, aggregates, outerValues, currentNestedValues, cellIndex, queryId);
                 }
             }
             return;
@@ -1340,7 +1386,7 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
         }
         if (nestedDepth + 1 < nestedGroupings.length) {
             // More nesting
-            indexColumnPivots(nestedRow, nestedGroupings, aggregates, outerValues, currentNestedValues, cellIndex, nestedDepth + 1, isInverted, nestNameSuffix);
+            indexColumnPivots(nestedRow, nestedGroupings, aggregates, outerValues, currentNestedValues, cellIndex, nestedDepth + 1, isInverted, nestNameSuffix, queryId);
         }
         else {
             // Leaf - index aggregate values
@@ -1349,10 +1395,10 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
             if (isInverted) {
                 indexAggregateValues(nestedRow, aggregates, currentNestedValues, // These are actually row values
                 outerValues, // These are actually col values
-                cellIndex);
+                cellIndex, queryId);
             }
             else {
-                indexAggregateValues(nestedRow, aggregates, outerValues, currentNestedValues, cellIndex);
+                indexAggregateValues(nestedRow, aggregates, outerValues, currentNestedValues, cellIndex, queryId);
             }
         }
     }
@@ -1360,7 +1406,7 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
 /**
  * Index aggregate values at a specific row/col value combination.
  */
-function indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex) {
+function indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex, queryId) {
     const cellKey = makeCellKey(rowValues, colValues);
     let cellData = cellIndex.get(cellKey);
     if (!cellData) {
@@ -1370,7 +1416,10 @@ function indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex)
     for (const agg of aggregates) {
         const value = row[agg.name];
         if (value !== undefined) {
-            cellData.set(agg.name, typeof value === "number" ? value : null);
+            cellData.set(agg.name, {
+                value: typeof value === "number" ? value : null,
+                queryId,
+            });
         }
     }
 }

package/dist/compiler/table-spec.d.ts

@@ -399,6 +399,22 @@ export interface CellValue {
     readonly aggregate: string;
     /** Path description for tooltips */
     readonly pathDescription: string;
+    /**
+     * The SQL query that produced this cell's data.
+     * Only populated when `trackSQL: true` is set.
+     * This is the full SQL for the query — multiple cells may share the same SQL
+     * when they come from the same underlying query.
+     */
+    readonly sql?: string;
+    /**
+     * A cell-specific SQL query narrowed with WHERE conditions for this cell's
+     * exact dimension values. This would return only the row(s) relevant to
+     * this specific cell if executed independently.
+     * Only populated when `trackSQL: true` is set.
+     * Note: For percentage/ACROSS aggregates, the narrowed SQL may not reproduce
+     * the same value because window functions depend on the full result set.
+     */
+    readonly cellSQL?: string;
 }
 /**
  * Walk the axis tree and call a visitor for each node.

package/dist/executor/index.d.ts

@@ -76,6 +76,8 @@ export interface ExecuteOptions {
     outputPath?: string;
     /** Return raw Malloy result object */
     raw?: boolean;
+    /** When true, also capture the generated SQL string */
+    captureSQL?: boolean;
 }
 /**
  * Execute a Malloy query string

package/dist/executor/index.js

@@ -273,7 +273,13 @@ export async function executeMalloy(malloySource, options = {}) {
     try {
         // Parse and run the Malloy query
         // Note: Malloy has a default rowLimit of 10 - we use a high limit to get all data
-        const result = await runtime.loadQuery(malloySource).run({ rowLimit: 100000 });
+        const materializer = runtime.loadQuery(malloySource);
+        // Capture SQL before running if requested
+        let sql;
+        if (options.captureSQL) {
+            sql = await materializer.getSQL();
+        }
+        const result = await materializer.run({ rowLimit: 100000 });
         // Get the data
         const data = result.data.toObject();
         // Write to file if requested
@@ -281,6 +287,9 @@ export async function executeMalloy(malloySource, options = {}) {
             fs.writeFileSync(options.outputPath, JSON.stringify(data, null, 2), 'utf-8');
             console.log(`Results written to: ${options.outputPath}`);
         }
+        if (options.captureSQL) {
+            return { data: options.raw ? result : data, sql };
+        }
         return options.raw ? result : data;
     }
     catch (error) {

package/dist/index.cjs

@@ -8429,11 +8429,13 @@ function normalizeQueryResults(results) {
 function buildGridSpec(spec, plan, results, malloyQueriesOrOptions) {
   let malloyQueries;
   let orderingProvider;
+  let sqlQueries;
   if (Array.isArray(malloyQueriesOrOptions)) {
     malloyQueries = malloyQueriesOrOptions;
   } else if (malloyQueriesOrOptions) {
     malloyQueries = malloyQueriesOrOptions.malloyQueries;
     orderingProvider = malloyQueriesOrOptions.orderingProvider;
+    sqlQueries = malloyQueriesOrOptions.sqlQueries;
   }
   currentOrderingProvider2 = orderingProvider;
   results = normalizeQueryResults(results);
@@ -8489,7 +8491,8 @@ function buildGridSpec(spec, plan, results, malloyQueriesOrOptions) {
       plan,
       results,
       invertedQueries,
-      flatQueries
+      flatQueries,
+      sqlQueries
     );
     const hasRowTotal = axisHasTotal(spec.rowAxis);
     const hasColTotal = axisHasTotal(spec.colAxis);
@@ -9081,7 +9084,31 @@ function makeCellKey(rowValues, colValues) {
   ];
   return allEntries.sort((a, b) => a[0].localeCompare(b[0])).map(([k, v]) => `${k}=${v}`).join("|");
 }
-function buildCellLookup(spec, plan, results, invertedQueries, flatQueries = /* @__PURE__ */ new Set()) {
+function buildCellSQL(baseSQL, rowValues, colValues) {
+  const conditions = [];
+  const addCondition = (dim, val) => {
+    if (typeof val === "number") {
+      conditions.push(`${quoteIdentifier(dim)} = ${val}`);
+    } else {
+      conditions.push(`${quoteIdentifier(dim)} = '${val.replace(/'/g, "''")}'`);
+    }
+  };
+  for (const [dim, val] of rowValues) {
+    addCondition(dim, val);
+  }
+  for (const [dim, val] of colValues) {
+    addCondition(dim, val);
+  }
+  if (conditions.length === 0) return baseSQL;
+  return `SELECT * FROM (
+${baseSQL}
+) AS _tpl_base
+WHERE ${conditions.join(" AND ")}`;
+}
+function quoteIdentifier(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+function buildCellLookup(spec, plan, results, invertedQueries, flatQueries = /* @__PURE__ */ new Set(), sqlQueries) {
   const cellIndex = /* @__PURE__ */ new Map();
   const DEBUG = process.env.DEBUG_GRID === "true";
   for (const query of plan.queries) {
@@ -9130,12 +9157,23 @@ function buildCellLookup(spec, plan, results, invertedQueries, flatQueries = /*
           pathDescription: cellKey
         };
       }
-      const value = cellData.get(aggName) ?? null;
+      const entry = cellData.get(aggName);
+      const value = entry?.value ?? null;
+      let sql;
+      let cellSQL;
+      if (sqlQueries && entry?.queryId) {
+        sql = sqlQueries.get(entry.queryId);
+        if (sql) {
+          cellSQL = buildCellSQL(sql, rowValues, colValues);
+        }
+      }
       return {
         raw: value,
         formatted: formatValue(value, agg),
         aggregate: aggName,
-        pathDescription: cellKey
+        pathDescription: cellKey,
+        sql,
+        cellSQL
       };
     }
   };
@@ -9171,7 +9209,8 @@ function indexQueryResults(data, query, cellIndex, aggregates, isInverted = fals
     // logical row groupings
     query.colGroupings,
     // logical col groupings
-    primarySuffix
+    primarySuffix,
+    query.id
   );
   if (query.additionalColVariants) {
     for (const variant of query.additionalColVariants) {
@@ -9195,7 +9234,8 @@ function indexQueryResults(data, query, cellIndex, aggregates, isInverted = fals
         isInverted,
         query.rowGroupings,
         variant.colGroupings,
-        nestNameSuffix
+        nestNameSuffix,
+        query.id
       );
     }
   }
@@ -9230,10 +9270,10 @@ function indexFlatQueryResults(data, query, cellIndex, aggregates) {
         colValues.set(g.dimension, value);
       }
     }
-    indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex);
+    indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex, query.id);
   }
 }
-function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggregates, baseOuterValues, baseNestedValues, cellIndex, outerDepth, isInverted = false, logicalRowGroupings, logicalColGroupings, nestNameSuffix = "") {
+function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggregates, baseOuterValues, baseNestedValues, cellIndex, outerDepth, isInverted = false, logicalRowGroupings, logicalColGroupings, nestNameSuffix = "", queryId) {
   for (const row of data) {
     const currentOuterValues = new Map(baseOuterValues);
     for (let i = outerDepth; i < malloyOuterGroupings.length; i++) {
@@ -9264,7 +9304,8 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
             isInverted,
             logicalRowGroupings,
             logicalColGroupings,
-            nestNameSuffix
+            nestNameSuffix,
+            queryId
           );
           break;
         }
@@ -9286,7 +9327,8 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
         cellIndex,
         0,
         isInverted,
-        nestNameSuffix
+        nestNameSuffix,
+        queryId
       );
     } else {
       if (isInverted) {
@@ -9297,7 +9339,8 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
           // These are actually the row values (empty when no nesting)
           currentOuterValues,
           // These are actually the col values
-          cellIndex
+          cellIndex,
+          queryId
         );
       } else {
         indexAggregateValues(
@@ -9305,13 +9348,14 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
           aggregates,
           currentOuterValues,
           baseNestedValues,
-          cellIndex
+          cellIndex,
+          queryId
         );
       }
     }
   }
 }
-function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNestedValues, cellIndex, nestedDepth, isInverted = false, nestNameSuffix = "") {
+function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNestedValues, cellIndex, nestedDepth, isInverted = false, nestNameSuffix = "", queryId) {
   const currentDim = nestedGroupings[nestedDepth];
   const remainingDims = nestedGroupings.slice(nestedDepth);
   let nestedKey = nestedDepth === 0 ? `by_${currentDim.dimension}${nestNameSuffix}` : `by_${currentDim.dimension}`;
@@ -9343,7 +9387,8 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
             // These are actually row values
             outerValues,
             // These are actually col values
-            cellIndex
+            cellIndex,
+            queryId
           );
         } else {
           indexAggregateValues(
@@ -9351,7 +9396,8 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
             aggregates,
             outerValues,
             currentNestedValues,
-            cellIndex
+            cellIndex,
+            queryId
           );
         }
       }
@@ -9382,7 +9428,8 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
         cellIndex,
         nestedDepth + 1,
         isInverted,
-        nestNameSuffix
+        nestNameSuffix,
+        queryId
       );
     } else {
       if (isInverted) {
@@ -9393,7 +9440,8 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
           // These are actually row values
           outerValues,
           // These are actually col values
-          cellIndex
+          cellIndex,
+          queryId
         );
       } else {
         indexAggregateValues(
@@ -9401,13 +9449,14 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
           aggregates,
           outerValues,
           currentNestedValues,
-          cellIndex
+          cellIndex,
+          queryId
         );
       }
     }
   }
 }
-function indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex) {
+function indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex, queryId) {
   const cellKey = makeCellKey(rowValues, colValues);
   let cellData = cellIndex.get(cellKey);
   if (!cellData) {
@@ -9417,7 +9466,10 @@ function indexAggregateValues(row, aggregates, rowValues, colValues, cellIndex)
   for (const agg of aggregates) {
     const value = row[agg.name];
     if (value !== void 0) {
-      cellData.set(agg.name, typeof value === "number" ? value : null);
+      cellData.set(agg.name, {
+        value: typeof value === "number" ? value : null,
+        queryId
+      });
     }
   }
 }
@@ -10582,7 +10634,9 @@ function renderDataCell(grid, rowValues, colValues, rowLeaf, colLeaf, rowRoots,
   const humanPath = buildHumanPath(rowValues, colValues, aggregateName, grid.aggregates);
   const titleAttr = humanPath ? ` title="${escapeHTML(humanPath)}"` : "";
   const dataAttr = cell.pathDescription ? ` data-cell="${escapeHTML(cell.pathDescription)}"` : "";
-  lines.push(`<td${classAttr}${titleAttr}${dataAttr}>${escapeHTML(cell.formatted)}</td>`);
+  const sqlAttr = cell.sql ? ` data-sql="${escapeHTML(cell.sql)}"` : "";
+  const cellSQLAttr = cell.cellSQL ? ` data-cell-sql="${escapeHTML(cell.cellSQL)}"` : "";
+  lines.push(`<td${classAttr}${titleAttr}${dataAttr}${sqlAttr}${cellSQLAttr}>${escapeHTML(cell.formatted)}</td>`);
 }
 function renderDataCells(grid, rowValues, rowLeaf, lines) {
   const colValues = /* @__PURE__ */ new Map();
@@ -10594,14 +10648,18 @@ function renderDataCells(grid, rowValues, rowLeaf, lines) {
     const humanPath = buildHumanPath(rowValues, colValues, rowAgg, grid.aggregates);
     const titleAttr = humanPath ? ` title="${escapeHTML(humanPath)}"` : "";
     const dataAttr = cell.pathDescription ? ` data-cell="${escapeHTML(cell.pathDescription)}"` : "";
-    lines.push(`<td${classAttr}${titleAttr}${dataAttr}>${escapeHTML(cell.formatted)}</td>`);
+    const sqlAttr = cell.sql ? ` data-sql="${escapeHTML(cell.sql)}"` : "";
+    const cellSQLAttr = cell.cellSQL ? ` data-cell-sql="${escapeHTML(cell.cellSQL)}"` : "";
+    lines.push(`<td${classAttr}${titleAttr}${dataAttr}${sqlAttr}${cellSQLAttr}>${escapeHTML(cell.formatted)}</td>`);
   } else {
     for (const agg of grid.aggregates) {
       const cell = grid.getCell(rowValues, colValues, agg.name);
       const humanPath = buildHumanPath(rowValues, colValues, agg.name, grid.aggregates);
       const titleAttr = humanPath ? ` title="${escapeHTML(humanPath)}"` : "";
       const dataAttr = cell.pathDescription ? ` data-cell="${escapeHTML(cell.pathDescription)}"` : "";
-      lines.push(`<td${classAttr}${titleAttr}${dataAttr}>${escapeHTML(cell.formatted)}</td>`);
+      const sqlAttr = cell.sql ? ` data-sql="${escapeHTML(cell.sql)}"` : "";
+      const cellSQLAttr = cell.cellSQL ? ` data-cell-sql="${escapeHTML(cell.cellSQL)}"` : "";
+      lines.push(`<td${classAttr}${titleAttr}${dataAttr}${sqlAttr}${cellSQLAttr}>${escapeHTML(cell.formatted)}</td>`);
     }
   }
 }
@@ -10769,7 +10827,12 @@ async function executeMalloy(malloySource, options = {}) {
     connection: conn
   });
   try {
-    const result = await runtime.loadQuery(malloySource).run({ rowLimit: 1e5 });
+    const materializer = runtime.loadQuery(malloySource);
+    let sql;
+    if (options.captureSQL) {
+      sql = await materializer.getSQL();
+    }
+    const result = await materializer.run({ rowLimit: 1e5 });
     const data = result.data.toObject();
     if (options.outputPath) {
       fs.writeFileSync(
@@ -10779,6 +10842,9 @@ async function executeMalloy(malloySource, options = {}) {
       );
       console.log(`Results written to: ${options.outputPath}`);
     }
+    if (options.captureSQL) {
+      return { data: options.raw ? result : data, sql };
+    }
     return options.raw ? result : data;
   } catch (error) {
     console.error("Malloy execution error:", error);
@@ -10827,18 +10893,28 @@ var TPL = class {
       orderingProvider: options.orderingProvider
     });
     const rawResults = /* @__PURE__ */ new Map();
+    const sqlQueries = this.options.trackSQL ? /* @__PURE__ */ new Map() : void 0;
     for (const queryInfo of queries) {
       const fullMalloy = `${effectiveModel}
 ${queryInfo.malloy}`;
-      const data = await executeMalloy(fullMalloy);
-      rawResults.set(queryInfo.id, data);
+      if (this.options.trackSQL) {
+        const result = await executeMalloy(fullMalloy, { captureSQL: true });
+        rawResults.set(queryInfo.id, result.data);
+        if (result.sql) {
+          sqlQueries.set(queryInfo.id, result.sql);
+        }
+      } else {
+        const data = await executeMalloy(fullMalloy);
+        rawResults.set(queryInfo.id, data);
+      }
     }
     const grid = buildGridSpec(spec, plan, rawResults, {
       malloyQueries: queries,
-      orderingProvider: options.orderingProvider
+      orderingProvider: options.orderingProvider,
+      sqlQueries
     });
     const html = renderGridToHTML(grid);
-    return { html, grid, malloy, rawResults };
+    return { html, grid, malloy, rawResults, sqlQueries };
   }
 };
 function createTPL(options = {}) {

package/dist/index.d.ts

@@ -53,6 +53,13 @@ export interface TPLOptions {
     sourceName?: string;
     /** @deprecated Use `sourceName` instead */
     source?: string;
+    /**
+     * When true, captures the raw SQL generated by Malloy for each query
+     * and makes it available on each cell via `CellValue.sql` and `CellValue.cellSQL`.
+     * Useful for audit environments where consumers need to verify how each
+     * number was produced.
+     */
+    trackSQL?: boolean;
 }
 /**
  * Result of compiling TPL to Malloy
@@ -115,6 +122,13 @@ export interface ExecuteResult {
     malloy: string;
     /** raw query results by query ID */
     rawResults: Map<string, any[]>;
+    /**
+     * Raw SQL queries by query ID.
+     * Only populated when `trackSQL: true` is set.
+     * Each entry maps a query ID (e.g., 'q0') to the SQL string
+     * that was sent to the database.
+     */
+    sqlQueries?: Map<string, string>;
 }
 /**
  * High-level TPL API for parsing, compiling, executing, and rendering.

package/dist/index.js

@@ -86,18 +86,29 @@ export class TPL {
         });
         // execute all queries
         const rawResults = new Map();
+        const sqlQueries = this.options.trackSQL ? new Map() : undefined;
         for (const queryInfo of queries) {
             const fullMalloy = `${effectiveModel}\n${queryInfo.malloy}`;
-            const data = await executeMalloy(fullMalloy);
-            rawResults.set(queryInfo.id, data);
+            if (this.options.trackSQL) {
+                const result = await executeMalloy(fullMalloy, { captureSQL: true });
+                rawResults.set(queryInfo.id, result.data);
+                if (result.sql) {
+                    sqlQueries.set(queryInfo.id, result.sql);
+                }
+            }
+            else {
+                const data = await executeMalloy(fullMalloy);
+                rawResults.set(queryInfo.id, data);
+            }
         }
         // build grid and render
         const grid = buildGridSpec(spec, plan, rawResults, {
             malloyQueries: queries,
             orderingProvider: options.orderingProvider,
+            sqlQueries,
         });
         const html = renderGridToHTML(grid);
-        return { html, grid, malloy, rawResults };
+        return { html, grid, malloy, rawResults, sqlQueries };
     }
 }
 /**

package/dist/renderer/grid-renderer.js

@@ -569,7 +569,9 @@ function renderDataCell(grid, rowValues, colValues, rowLeaf, colLeaf, rowRoots,
     const humanPath = buildHumanPath(rowValues, colValues, aggregateName, grid.aggregates);
     const titleAttr = humanPath ? ` title="${escapeHTML(humanPath)}"` : '';
     const dataAttr = cell.pathDescription ? ` data-cell="${escapeHTML(cell.pathDescription)}"` : '';
-    lines.push(`<td${classAttr}${titleAttr}${dataAttr}>${escapeHTML(cell.formatted)}</td>`);
+    const sqlAttr = cell.sql ? ` data-sql="${escapeHTML(cell.sql)}"` : '';
+    const cellSQLAttr = cell.cellSQL ? ` data-cell-sql="${escapeHTML(cell.cellSQL)}"` : '';
+    lines.push(`<td${classAttr}${titleAttr}${dataAttr}${sqlAttr}${cellSQLAttr}>${escapeHTML(cell.formatted)}</td>`);
 }
 /**
  * Render data cells when there are no column pivots.
@@ -587,7 +589,9 @@ function renderDataCells(grid, rowValues, rowLeaf, lines) {
         const humanPath = buildHumanPath(rowValues, colValues, rowAgg, grid.aggregates);
         const titleAttr = humanPath ? ` title="${escapeHTML(humanPath)}"` : '';
         const dataAttr = cell.pathDescription ? ` data-cell="${escapeHTML(cell.pathDescription)}"` : '';
-        lines.push(`<td${classAttr}${titleAttr}${dataAttr}>${escapeHTML(cell.formatted)}</td>`);
+        const sqlAttr = cell.sql ? ` data-sql="${escapeHTML(cell.sql)}"` : '';
+        const cellSQLAttr = cell.cellSQL ? ` data-cell-sql="${escapeHTML(cell.cellSQL)}"` : '';
+        lines.push(`<td${classAttr}${titleAttr}${dataAttr}${sqlAttr}${cellSQLAttr}>${escapeHTML(cell.formatted)}</td>`);
     }
     else {
         // Multiple aggregate cells
@@ -596,7 +600,9 @@ function renderDataCells(grid, rowValues, rowLeaf, lines) {
             const humanPath = buildHumanPath(rowValues, colValues, agg.name, grid.aggregates);
             const titleAttr = humanPath ? ` title="${escapeHTML(humanPath)}"` : '';
             const dataAttr = cell.pathDescription ? ` data-cell="${escapeHTML(cell.pathDescription)}"` : '';
-            lines.push(`<td${classAttr}${titleAttr}${dataAttr}>${escapeHTML(cell.formatted)}</td>`);
+            const sqlAttr = cell.sql ? ` data-sql="${escapeHTML(cell.sql)}"` : '';
+            const cellSQLAttr = cell.cellSQL ? ` data-cell-sql="${escapeHTML(cell.cellSQL)}"` : '';
+            lines.push(`<td${classAttr}${titleAttr}${dataAttr}${sqlAttr}${cellSQLAttr}>${escapeHTML(cell.formatted)}</td>`);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tplm-lang",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "TPLm - Table Producing Language backed by Malloy.",
   "type": "module",
   "main": "./dist/index.cjs",