tplm-lang 0.3.5 → 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);
@@ -461,15 +463,13 @@ function buildSiblingHeaders(node, plan, results, axis, currentPath, depth, pare
  * Format an aggregate name for display (e.g., "births sum" from "births", "sum")
  */
 function formatAggregateName(measure, aggregation) {
-    // For count/n without a measure, just return the aggregation name
-    // This handles cases like standalone "count" or "n"
+    // For count/n without a measure, just return "N"
     if (!measure || measure === "__pending__") {
         return aggregation === "count" ? "N" : aggregation;
     }
-    // For count with a measure (e.g., income.count), just return "N" since
-    // count doesn't really bind to a measure in Malloy
+    // For field-bound count (distinct count), show "field N"
     if (aggregation === "count") {
-        return "N";
+        return `${measure} N`;
     }
     return `${measure} ${aggregation}`;
 }
@@ -1025,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.
  *
@@ -1034,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
@@ -1080,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,
             };
         },
     };
@@ -1131,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
@@ -1149,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);
         }
     }
 }
@@ -1194,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);
     }
 }
 /**
@@ -1207,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
@@ -1236,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
                 }
             }
@@ -1249,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
@@ -1258,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);
             }
         }
     }
@@ -1275,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
@@ -1313,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;
@@ -1342,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
@@ -1351,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);
             }
         }
     }
@@ -1362,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) {
@@ -1372,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/malloy-generator.js

@@ -110,16 +110,33 @@ function buildNestedPivot(colGroupings, aggregates, indent) {
 function buildAggregates(aggregates, indent = 2) {
     const pad = ' '.repeat(indent);
     const aggs = aggregates.map(a => {
-        return `${a.name} is ${a.measure}.${a.aggregation}()`;
+        return `${a.name} is ${buildAggExpr(a.measure, a.aggregation)}`;
     });
     return `${pad}aggregate: ${aggs.join(', ')}`;
 }
+/** Build a Malloy aggregate expression (mirrors multi-query-utils buildAggExpression) */
+function buildAggExpr(measure, aggregation) {
+    if (aggregation === 'count') {
+        if (measure && measure !== '__pending__' && measure !== '') {
+            return `count(${escapeForMalloy(measure)})`;
+        }
+        return 'count()';
+    }
+    if (!measure || measure === '__pending__')
+        return 'count()';
+    const methodMap = { mean: 'avg', stdev: 'stddev', pct: 'sum', pctn: 'count', pctsum: 'sum' };
+    return `${measure}.${methodMap[aggregation] ?? aggregation}()`;
+}
+const MALLOY_RESERVED = new Set(['all', 'and', 'as', 'asc', 'avg', 'by', 'case', 'cast', 'count', 'day', 'desc', 'dimension', 'else', 'end', 'exclude', 'extend', 'false', 'from', 'group', 'having', 'hour', 'import', 'is', 'join', 'limit', 'max', 'measure', 'min', 'minute', 'month', 'nest', 'not', 'now', 'null', 'number', 'on', 'or', 'order', 'pick', 'quarter', 'run', 'second', 'source', 'sum', 'then', 'true', 'week', 'when', 'where', 'year']);
+function escapeForMalloy(name) {
+    return MALLOY_RESERVED.has(name.toLowerCase()) ? `\`${name}\`` : name;
+}
 /**
  * Build total aggregate for column totals.
  */
 function buildTotalAggregate(aggregates, label) {
     const aggs = aggregates.map(a => {
-        return `${a.name} is ${a.measure}.${a.aggregation}()`;
+        return `${a.name} is ${buildAggExpr(a.measure, a.aggregation)}`;
     });
     const nestName = label ? `"${label}"` : '"total"';
     return `  nest: total is { aggregate: ${aggs.join(', ')} }`;

package/dist/compiler/multi-query-utils.d.ts

@@ -16,7 +16,12 @@ export declare function escapeFieldName(name: string): string;
  */
 export declare function escapeWhereExpression(expr: string): string;
 /**
- * Build a Malloy aggregate expression from measure and aggregation
+ * Build a Malloy aggregate expression from measure and aggregation.
+ *
+ * Count semantics:
+ * - Standalone `count` or `n` (no measure) → `count()` — counts all rows
+ * - Field-bound `user_id.count` (with measure) → `count(user_id)` — counts distinct values
+ *   This matches Malloy's native semantics where count(field) = COUNT(DISTINCT field).
  */
 export declare function buildAggExpression(measure: string, aggregation: string): string;
 /**

package/dist/compiler/multi-query-utils.js

@@ -86,16 +86,21 @@ const AGG_METHOD_MAP = {
     pctsum: 'sum',
 };
 /**
- * Build a Malloy aggregate expression from measure and aggregation
+ * Build a Malloy aggregate expression from measure and aggregation.
+ *
+ * Count semantics:
+ * - Standalone `count` or `n` (no measure) → `count()` — counts all rows
+ * - Field-bound `user_id.count` (with measure) → `count(user_id)` — counts distinct values
+ *   This matches Malloy's native semantics where count(field) = COUNT(DISTINCT field).
  */
 export function buildAggExpression(measure, aggregation) {
     const malloyMethod = AGG_METHOD_MAP[aggregation] ?? aggregation;
-    // Handle count - in Malloy, count() doesn't take a measure argument
-    // count() counts all rows, not a specific field
-    // When users write "income.count" or "income.n", they semantically mean "count"
-    // since you can't "count" a measure - you can only count rows
+    // Handle count: standalone = row count, field-bound = distinct count
     if (aggregation === 'count') {
-        return 'count()';
+        if (measure && measure !== '__pending__' && measure !== '') {
+            return `count(${escapeFieldName(measure)})`; // distinct count of field
+        }
+        return 'count()'; // standalone row count
     }
     // Handle other aggregations without a measure (use placeholder)
     // Also handle the __pending__ placeholder used for standalone count

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

@@ -6536,6 +6536,9 @@ var AGG_METHOD_MAP = {
 function buildAggExpression(measure, aggregation) {
   const malloyMethod = AGG_METHOD_MAP[aggregation] ?? aggregation;
   if (aggregation === "count") {
+    if (measure && measure !== "__pending__" && measure !== "") {
+      return `count(${escapeFieldName(measure)})`;
+    }
     return "count()";
   }
   if (!measure || measure === "__pending__") {
@@ -8426,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);
@@ -8486,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);
@@ -8760,7 +8766,7 @@ function formatAggregateName(measure, aggregation) {
     return aggregation === "count" ? "N" : aggregation;
   }
   if (aggregation === "count") {
-    return "N";
+    return `${measure} N`;
   }
   return `${measure} ${aggregation}`;
 }
@@ -9078,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) {
@@ -9127,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
       };
     }
   };
@@ -9168,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) {
@@ -9192,7 +9234,8 @@ function indexQueryResults(data, query, cellIndex, aggregates, isInverted = fals
         isInverted,
         query.rowGroupings,
         variant.colGroupings,
-        nestNameSuffix
+        nestNameSuffix,
+        query.id
       );
     }
   }
@@ -9227,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++) {
@@ -9261,7 +9304,8 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
             isInverted,
             logicalRowGroupings,
             logicalColGroupings,
-            nestNameSuffix
+            nestNameSuffix,
+            queryId
           );
           break;
         }
@@ -9283,7 +9327,8 @@ function flattenAndIndex(data, malloyOuterGroupings, malloyNestedGroupings, aggr
         cellIndex,
         0,
         isInverted,
-        nestNameSuffix
+        nestNameSuffix,
+        queryId
       );
     } else {
       if (isInverted) {
@@ -9294,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(
@@ -9302,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}`;
@@ -9340,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(
@@ -9348,7 +9396,8 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
             aggregates,
             outerValues,
             currentNestedValues,
-            cellIndex
+            cellIndex,
+            queryId
           );
         }
       }
@@ -9379,7 +9428,8 @@ function indexColumnPivots(row, nestedGroupings, aggregates, outerValues, baseNe
         cellIndex,
         nestedDepth + 1,
         isInverted,
-        nestNameSuffix
+        nestNameSuffix,
+        queryId
       );
     } else {
       if (isInverted) {
@@ -9390,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(
@@ -9398,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) {
@@ -9414,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
+      });
     }
   }
 }
@@ -10206,6 +10261,17 @@ ${ordinalPick}`);
 }
 
 // packages/renderer/grid-renderer.ts
+function formatAggDisplayName(agg) {
+  if (agg.label) return agg.label;
+  if (agg.aggregation === "count") {
+    if (agg.measure && agg.measure !== "__pending__" && agg.measure !== "") {
+      return `${agg.measure} N`;
+    }
+    return "N";
+  }
+  if (!agg.measure || agg.measure === "__pending__") return agg.aggregation;
+  return `${agg.measure} ${agg.aggregation}`;
+}
 function renderGridToHTML(grid, options = {}) {
   const {
     tableClass = "tpl-table",
@@ -10288,7 +10354,7 @@ function renderColumnHeaders(grid, lines, showDimensionLabels) {
         lines.push('<th class="tpl-corner"></th>');
       }
     }
-    lines.push(`<th>${escapeHTML(grid.aggregates[0]?.label ?? grid.aggregates[0]?.name ?? "Value")}</th>`);
+    lines.push(`<th>${escapeHTML(grid.aggregates[0] ? formatAggDisplayName(grid.aggregates[0]) : "Value")}</th>`);
     lines.push("</tr>");
     lines.push("</thead>");
     return;
@@ -10320,7 +10386,7 @@ function renderColumnHeaders(grid, lines, showDimensionLabels) {
       lines.push("<th>Value</th>");
     } else {
       for (const agg of grid.aggregates) {
-        lines.push(`<th>${escapeHTML(agg.label ?? agg.name)}</th>`);
+        lines.push(`<th>${escapeHTML(formatAggDisplayName(agg))}</th>`);
       }
     }
     lines.push("</tr>");
@@ -10537,23 +10603,13 @@ function buildHumanPath(rowValues, colValues, aggregateName, aggregates) {
     if (aggInfo?.label) {
       displayAgg = aggInfo.label;
     } else if (aggInfo) {
-      if (aggInfo.aggregation === "count") {
-        displayAgg = "count";
-      } else {
-        displayAgg = `${aggInfo.measure}.${aggInfo.aggregation}`;
-      }
+      displayAgg = formatAggDisplayName(aggInfo);
     } else {
       displayAgg = aggregateName.replace(/^__pending___/, "").replace(/_/g, ".");
     }
   } else if (aggregates.length === 1) {
     const aggInfo = aggregates[0];
-    if (aggInfo.label) {
-      displayAgg = aggInfo.label;
-    } else if (aggInfo.aggregation === "count") {
-      displayAgg = "count";
-    } else {
-      displayAgg = `${aggInfo.measure}.${aggInfo.aggregation}`;
-    }
+    displayAgg = formatAggDisplayName(aggInfo);
   }
   if (displayAgg) {
     return dimPath ? `${dimPath} \u2192 ${displayAgg}` : displayAgg;
@@ -10578,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();
@@ -10590,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>`);
     }
   }
 }
@@ -10765,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(
@@ -10775,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);
@@ -10823,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

@@ -6,6 +6,25 @@
  * Key simplification: GridSpec already has the complete header hierarchy
  * with pre-computed spans, so we don't need to reconstruct structure.
  */
+/**
+ * Format an aggregate's display name.
+ * - Standalone count/n → "N"
+ * - field.count (distinct count) → "field N"
+ * - field.sum → "field sum"
+ */
+function formatAggDisplayName(agg) {
+    if (agg.label)
+        return agg.label;
+    if (agg.aggregation === 'count') {
+        if (agg.measure && agg.measure !== '__pending__' && agg.measure !== '') {
+            return `${agg.measure} N`;
+        }
+        return 'N';
+    }
+    if (!agg.measure || agg.measure === '__pending__')
+        return agg.aggregation;
+    return `${agg.measure} ${agg.aggregation}`;
+}
 /**
  * Render a GridSpec to HTML.
  */
@@ -118,7 +137,7 @@ function renderColumnHeaders(grid, lines, showDimensionLabels) {
             }
         }
         // Single aggregate header
-        lines.push(`<th>${escapeHTML(grid.aggregates[0]?.label ?? grid.aggregates[0]?.name ?? 'Value')}</th>`);
+        lines.push(`<th>${escapeHTML(grid.aggregates[0] ? formatAggDisplayName(grid.aggregates[0]) : 'Value')}</th>`);
         lines.push('</tr>');
         lines.push('</thead>');
         return;
@@ -159,7 +178,7 @@ function renderColumnHeaders(grid, lines, showDimensionLabels) {
         else {
             // Aggregates are not on row axis, render each aggregate as a column header
             for (const agg of grid.aggregates) {
-                lines.push(`<th>${escapeHTML(agg.label ?? agg.name)}</th>`);
+                lines.push(`<th>${escapeHTML(formatAggDisplayName(agg))}</th>`);
             }
         }
         lines.push('</tr>');
@@ -505,13 +524,7 @@ function buildHumanPath(rowValues, colValues, aggregateName, aggregates) {
             displayAgg = aggInfo.label;
         }
         else if (aggInfo) {
-            // Build display from measure + aggregation
-            if (aggInfo.aggregation === 'count') {
-                displayAgg = 'count';
-            }
-            else {
-                displayAgg = `${aggInfo.measure}.${aggInfo.aggregation}`;
-            }
+            displayAgg = formatAggDisplayName(aggInfo);
         }
         else {
             // Fallback: clean up the internal name
@@ -523,15 +536,7 @@ function buildHumanPath(rowValues, colValues, aggregateName, aggregates) {
     else if (aggregates.length === 1) {
         // Single aggregate - still show it in tooltip
         const aggInfo = aggregates[0];
-        if (aggInfo.label) {
-            displayAgg = aggInfo.label;
-        }
-        else if (aggInfo.aggregation === 'count') {
-            displayAgg = 'count';
-        }
-        else {
-            displayAgg = `${aggInfo.measure}.${aggInfo.aggregation}`;
-        }
+        displayAgg = formatAggDisplayName(aggInfo);
     }
     if (displayAgg) {
         return dimPath ? `${dimPath} → ${displayAgg}` : displayAgg;
@@ -564,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.
@@ -582,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
@@ -591,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.5",
+  "version": "0.3.7",
   "description": "TPLm - Table Producing Language backed by Malloy.",
   "type": "module",
   "main": "./dist/index.cjs",