tplm-lang 0.3.4 → 0.3.6

package/README.md

@@ -94,6 +94,25 @@ const tpl = fromConnection({
   dialect: "bigquery",
 });
 
+// SQL source (JOINs, CTEs, subqueries)
+import { fromConnectionSQL } from "tplm-lang";
+const tpl = fromConnectionSQL({
+  connection: conn,
+  sql: `
+    SELECT a.revenue, a.product, b.region
+    FROM \`p.d.sales\` a
+    JOIN \`p.d.regions\` b ON a.region_id = b.id
+  `,
+  dialect: "bigquery",
+});
+
+// DuckDB SQL source (no connection needed)
+import { fromDuckDBSQL } from "tplm-lang";
+const tpl = fromDuckDBSQL(`
+  SELECT a.*, b.region
+  FROM 'sales.csv' a JOIN 'regions.csv' b ON a.region_id = b.id
+`);
+
 // Then query the same way
 const { html } = await tpl.query("TABLE ROWS region * revenue.sum;");
 ```
@@ -195,7 +214,8 @@ COLS education * (revenue.sum ACROSS COLS | revenue.mean)
 
 ```typescript
 import {
-  fromCSV, fromDuckDBTable, fromBigQueryTable, fromConnection
+  fromCSV, fromDuckDBTable, fromBigQueryTable, fromConnection,
+  fromConnectionSQL, fromDuckDBSQL,
 } from "tplm-lang";
 
 // CSV or Parquet files
@@ -217,6 +237,16 @@ const tpl = fromConnection({
   dialect: "bigquery", // or "duckdb"
 });
 
+// SQL source — query JOINs, CTEs, or any SQL result
+const tpl = fromConnectionSQL({
+  connection: conn,
+  sql: `SELECT a.*, b.region FROM \`p.d.sales\` a JOIN \`p.d.regions\` b ON a.rid = b.id`,
+  dialect: "bigquery",
+});
+
+// DuckDB SQL source (no connection needed)
+const tpl = fromDuckDBSQL(`SELECT a.*, b.region FROM 'sales.csv' a JOIN 'regions.csv' b ON a.rid = b.id`);
+
 // Add computed dimensions with .extend()
 const tplWithDims = tpl.extend(`
   dimension: region is pick 'North' when region_code = 1 else 'South'
@@ -345,7 +375,7 @@ The renderer produces HTML tables with:
 
 ## Advanced: Using Full Malloy Models
 
-For complex scenarios requiring joins, pre-defined measures, or multiple sources, you can use full Malloy models. This is an advanced approach for users already familiar with Malloy.
+For complex scenarios requiring pre-defined measures, multiple sources, or advanced Malloy patterns, you can use full Malloy models. This is an advanced approach for users already familiar with Malloy. (For simple joins, consider `fromConnectionSQL` or `fromDuckDBSQL` instead.)
 
 ```typescript
 import { createTPL } from "tplm-lang";
@@ -365,12 +395,12 @@ const { html } = await tpl.execute(
 );
 ```
 
-> **Note:** When using full Malloy models, **percentile aggregations are not supported** (`p25`, `p50`, `p75`, `p90`, `p95`, `p99`, `median`). This is because percentiles require pre-computing values via SQL window functions against the raw table, and TPL cannot introspect complex Malloy models to determine the underlying table structure. Use the Easy Connectors (fromCSV, fromDuckDBTable, fromBigQueryTable) for percentile support.
+> **Note:** When using full Malloy models, **percentile aggregations are not supported** (`p25`, `p50`, `p75`, `p90`, `p95`, `p99`, `median`). This is because percentiles require pre-computing values via SQL window functions against the raw table, and TPL cannot introspect complex Malloy models to determine the underlying table structure. Use the Easy Connectors (fromCSV, fromDuckDBTable, fromBigQueryTable, fromConnectionSQL, fromDuckDBSQL) for percentile support.
 
 **What belongs in your Malloy model:**
 
-- Joins between tables
 - Complex calculated measures TPL cannot express
+- Advanced Malloy patterns (views, refinements, etc.)
 
 **What TPL computes at query time:**
 

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

@@ -461,15 +461,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}`;
 }

package/dist/compiler/index.d.ts

@@ -9,5 +9,5 @@ export { buildTableSpec, printTableSpec, } from './table-spec-builder.js';
 export { generateQueryPlan, generateMalloyQueries, printQueryPlan, countRawQueries, } from './query-plan-generator.js';
 export type { MalloyQuerySpec, GenerateMalloyOptions } from './query-plan-generator.js';
 export { buildGridSpec, printGridSpec, type QueryResults, type BuildGridSpecOptions, } from './grid-spec-builder.js';
-export { analyzeAndGeneratePercentileConfig, findPercentileAggregations, findDimensions, findPartitionLevels, findCollapsedDimensions, generatePercentileSourceSQL, generateMultiLevelPercentileSQL, generatePercentileMalloySource, transformTPLForPercentiles, postProcessMalloyForPercentiles, isPercentileMethod, PERCENTILE_METHODS, PERCENTILE_VALUES, PERCENTILE_LABELS, type PercentileInfo, type PercentileConfig, type PartitionLevel, type SqlDialect, } from './percentile-utils.js';
+export { analyzeAndGeneratePercentileConfig, findPercentileAggregations, findDimensions, findPartitionLevels, findCollapsedDimensions, generatePercentileSourceSQL, generateMultiLevelPercentileSQL, generatePercentileMalloySource, transformTPLForPercentiles, postProcessMalloyForPercentiles, isPercentileMethod, PERCENTILE_METHODS, PERCENTILE_VALUES, PERCENTILE_LABELS, tableSource, sqlSource, type PercentileInfo, type PercentileConfig, type PartitionLevel, type SqlDialect, type SourceRef, } from './percentile-utils.js';
 export { malloyPickToSqlCase, parseDimensionMappings, detectDimensionOrdering, type DimensionInfo, type DimensionOrderingProvider, } from './dimension-utils.js';

package/dist/compiler/index.js

@@ -12,6 +12,6 @@ export { generateQueryPlan, generateMalloyQueries, printQueryPlan, countRawQueri
 // gridspec builder
 export { buildGridSpec, printGridSpec, } from './grid-spec-builder.js';
 // percentile support
-export { analyzeAndGeneratePercentileConfig, findPercentileAggregations, findDimensions, findPartitionLevels, findCollapsedDimensions, generatePercentileSourceSQL, generateMultiLevelPercentileSQL, generatePercentileMalloySource, transformTPLForPercentiles, postProcessMalloyForPercentiles, isPercentileMethod, PERCENTILE_METHODS, PERCENTILE_VALUES, PERCENTILE_LABELS, } from './percentile-utils.js';
+export { analyzeAndGeneratePercentileConfig, findPercentileAggregations, findDimensions, findPartitionLevels, findCollapsedDimensions, generatePercentileSourceSQL, generateMultiLevelPercentileSQL, generatePercentileMalloySource, transformTPLForPercentiles, postProcessMalloyForPercentiles, isPercentileMethod, PERCENTILE_METHODS, PERCENTILE_VALUES, PERCENTILE_LABELS, tableSource, sqlSource, } from './percentile-utils.js';
 // dimension utilities (for percentile partitioning and ordering)
 export { malloyPickToSqlCase, parseDimensionMappings, detectDimensionOrdering, } from './dimension-utils.js';

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/percentile-utils.d.ts

@@ -61,6 +61,26 @@ export declare function findPercentileAggregations(stmt: TPLStatement): Percenti
  */
 export declare function findDimensions(stmt: TPLStatement): string[];
 export type SqlDialect = 'duckdb' | 'bigquery';
+/**
+ * Describes the data source for SQL generation.
+ * - 'table': a table path (file or fully-qualified table name)
+ * - 'sql': a raw SQL query to wrap as a subquery
+ */
+export type SourceRef = {
+    type: 'table';
+    path: string;
+} | {
+    type: 'sql';
+    query: string;
+};
+/**
+ * Create a SourceRef from a table path string (backwards compatibility).
+ */
+export declare function tableSource(path: string): SourceRef;
+/**
+ * Create a SourceRef from a raw SQL query.
+ */
+export declare function sqlSource(query: string): SourceRef;
 /**
  * Generate the SQL window function for a percentile computation.
  *
@@ -71,14 +91,14 @@ export declare function generatePercentileWindowFunction(measure: string, quanti
 /**
  * Generate a derived SQL source that pre-computes percentiles.
  *
- * @param tablePath The path to the source table (e.g., 'data/file.csv')
+ * @param source The data source (table path or SQL query) — accepts string for backwards compat or SourceRef
  * @param percentiles The percentiles to compute
  * @param partitionColumns Columns to partition by (dimensions)
  * @param dialect SQL dialect
  * @param whereClause Optional WHERE clause to filter data before computing percentiles
  * @returns SQL query string for the derived source
  */
-export declare function generatePercentileSourceSQL(tablePath: string, percentiles: PercentileInfo[], partitionColumns: string[], dialect: SqlDialect, whereClause?: string): string;
+export declare function generatePercentileSourceSQL(source: string | SourceRef, percentiles: PercentileInfo[], partitionColumns: string[], dialect: SqlDialect, whereClause?: string): string;
 /**
  * Generate a Malloy source definition that uses the derived SQL.
  *
@@ -179,13 +199,13 @@ export interface PercentileConfig {
  * Analyze a TPL statement and generate percentile configuration if needed.
  *
  * @param stmt Parsed TPL statement
- * @param tablePath Path to the source table
+ * @param source Path to the source table (string) or a SourceRef
  * @param sourceName Malloy source name
  * @param dialect SQL dialect
  * @param originalTPL Original TPL query string
  * @returns Configuration for percentile support
  */
-export declare function analyzeAndGeneratePercentileConfig(stmt: TPLStatement, tablePath: string, sourceName: string, dialect: SqlDialect, originalTPL: string): PercentileConfig;
+export declare function analyzeAndGeneratePercentileConfig(stmt: TPLStatement, source: string | SourceRef, sourceName: string, dialect: SqlDialect, originalTPL: string): PercentileConfig;
 /**
  * Generate SQL with window functions for multiple partition levels.
  *
@@ -196,4 +216,4 @@ export declare function analyzeAndGeneratePercentileConfig(stmt: TPLStatement, t
  * - __income_p50__gender_state: PARTITION BY gender, state (for detailed cells)
  * - __income_p50__state: PARTITION BY state (for ALL gender cells)
  */
-export declare function generateMultiLevelPercentileSQL(tablePath: string, percentiles: PercentileInfo[], partitionLevels: PartitionLevel[], dialect: SqlDialect, whereClause?: string): string;
+export declare function generateMultiLevelPercentileSQL(source: string | SourceRef, percentiles: PercentileInfo[], partitionLevels: PartitionLevel[], dialect: SqlDialect, whereClause?: string): string;

package/dist/compiler/percentile-utils.js

@@ -179,6 +179,31 @@ export function findDimensions(stmt) {
     collectFromAxis(stmt.colAxis);
     return Array.from(dims);
 }
+/**
+ * Build a FROM clause for the given source reference and dialect.
+ */
+function buildFromClause(source, dialect) {
+    if (source.type === 'sql') {
+        return `(${source.query}) _src`;
+    }
+    if (dialect === 'duckdb') {
+        return `'${source.path}'`;
+    }
+    // BigQuery uses backtick-quoted table names
+    return `\`${source.path}\``;
+}
+/**
+ * Create a SourceRef from a table path string (backwards compatibility).
+ */
+export function tableSource(path) {
+    return { type: 'table', path };
+}
+/**
+ * Create a SourceRef from a raw SQL query.
+ */
+export function sqlSource(query) {
+    return { type: 'sql', query };
+}
 /**
  * Generate the SQL window function for a percentile computation.
  *
@@ -200,14 +225,15 @@ export function generatePercentileWindowFunction(measure, quantile, partitionCol
 /**
  * Generate a derived SQL source that pre-computes percentiles.
  *
- * @param tablePath The path to the source table (e.g., 'data/file.csv')
+ * @param source The data source (table path or SQL query) — accepts string for backwards compat or SourceRef
  * @param percentiles The percentiles to compute
  * @param partitionColumns Columns to partition by (dimensions)
  * @param dialect SQL dialect
  * @param whereClause Optional WHERE clause to filter data before computing percentiles
  * @returns SQL query string for the derived source
  */
-export function generatePercentileSourceSQL(tablePath, percentiles, partitionColumns, dialect, whereClause) {
+export function generatePercentileSourceSQL(source, percentiles, partitionColumns, dialect, whereClause) {
+    const sourceRef = typeof source === 'string' ? tableSource(source) : source;
     // Build SELECT clause with window functions
     const windowFunctions = percentiles.map(p => {
         const windowFunc = generatePercentileWindowFunction(p.measure, p.quantile, partitionColumns, dialect);
@@ -215,15 +241,7 @@ export function generatePercentileSourceSQL(tablePath, percentiles, partitionCol
     });
     // Build WHERE clause if provided
     const wherePart = whereClause ? ` WHERE ${whereClause}` : '';
-    // Generate the SQL
-    if (dialect === 'duckdb') {
-        // DuckDB can read files directly
-        return `SELECT *, ${windowFunctions.join(', ')} FROM '${tablePath}'${wherePart}`;
-    }
-    else {
-        // BigQuery uses fully qualified table names
-        return `SELECT *, ${windowFunctions.join(', ')} FROM \`${tablePath}\`${wherePart}`;
-    }
+    return `SELECT *, ${windowFunctions.join(', ')} FROM ${buildFromClause(sourceRef, dialect)}${wherePart}`;
 }
 /**
  * Generate a Malloy source definition that uses the derived SQL.
@@ -487,13 +505,13 @@ function collectDimensionsFromGroup(group, dims) {
  * Analyze a TPL statement and generate percentile configuration if needed.
  *
  * @param stmt Parsed TPL statement
- * @param tablePath Path to the source table
+ * @param source Path to the source table (string) or a SourceRef
  * @param sourceName Malloy source name
  * @param dialect SQL dialect
  * @param originalTPL Original TPL query string
  * @returns Configuration for percentile support
  */
-export function analyzeAndGeneratePercentileConfig(stmt, tablePath, sourceName, dialect, originalTPL) {
+export function analyzeAndGeneratePercentileConfig(stmt, source, sourceName, dialect, originalTPL) {
     const percentiles = findPercentileAggregations(stmt);
     if (percentiles.length === 0) {
         return {
@@ -513,7 +531,7 @@ export function analyzeAndGeneratePercentileConfig(stmt, tablePath, sourceName,
     // Find the full partition level (most dimensions) for TPL transformation
     const fullLevel = partitionLevels.reduce((max, level) => level.dimensions.length > max.dimensions.length ? level : max);
     // Generate SQL with all needed partition levels
-    const derivedSQL = generateMultiLevelPercentileSQL(tablePath, percentiles, partitionLevels, dialect, whereClause);
+    const derivedSQL = generateMultiLevelPercentileSQL(source, percentiles, partitionLevels, dialect, whereClause);
     const derivedMalloySource = generatePercentileMalloySource(sourceName, derivedSQL, percentiles, dialect);
     // Transform TPL to use full partition column names (post-processing will fix outer aggregates)
     const transformedTPL = transformTPLForPercentiles(originalTPL, percentiles, fullLevel.suffix);
@@ -538,7 +556,8 @@ export function analyzeAndGeneratePercentileConfig(stmt, tablePath, sourceName,
  * - __income_p50__gender_state: PARTITION BY gender, state (for detailed cells)
  * - __income_p50__state: PARTITION BY state (for ALL gender cells)
  */
-export function generateMultiLevelPercentileSQL(tablePath, percentiles, partitionLevels, dialect, whereClause) {
+export function generateMultiLevelPercentileSQL(source, percentiles, partitionLevels, dialect, whereClause) {
+    const sourceRef = typeof source === 'string' ? tableSource(source) : source;
     const windowFunctions = [];
     for (const level of partitionLevels) {
         for (const p of percentiles) {
@@ -548,10 +567,5 @@ export function generateMultiLevelPercentileSQL(tablePath, percentiles, partitio
         }
     }
     const wherePart = whereClause ? ` WHERE ${whereClause}` : '';
-    if (dialect === 'duckdb') {
-        return `SELECT *, ${windowFunctions.join(', ')} FROM '${tablePath}'${wherePart}`;
-    }
-    else {
-        return `SELECT *, ${windowFunctions.join(', ')} FROM \`${tablePath}\`${wherePart}`;
-    }
+    return `SELECT *, ${windowFunctions.join(', ')} FROM ${buildFromClause(sourceRef, dialect)}${wherePart}`;
 }

package/dist/executor/index.js

@@ -67,13 +67,24 @@ export async function createConnection(options) {
 }
 async function createBigQueryConnection(options) {
     const { BigQueryConnection } = await loadBigQuery();
-    const credentialsPath = options.credentialsPath ?? './config/dev-credentials.json';
-    // Read credentials to get project ID if not provided
-    const credentials = JSON.parse(fs.readFileSync(credentialsPath, 'utf-8'));
-    const projectId = options.projectId ?? credentials.project_id;
-    // Set the environment variable for Google Cloud authentication
-    process.env.GOOGLE_APPLICATION_CREDENTIALS = path.resolve(credentialsPath);
-    const connection = new BigQueryConnection('bigquery', {}, { projectId, location: options.location ?? 'US' });
+    // Resolve credentials file: explicit path > default dev path > none (ADC)
+    const credentialsPath = options.credentialsPath
+        ?? (fs.existsSync('./config/dev-credentials.json') ? './config/dev-credentials.json' : undefined);
+    let projectId = options.projectId;
+    if (credentialsPath) {
+        const credentials = JSON.parse(fs.readFileSync(credentialsPath, 'utf-8'));
+        projectId = projectId ?? credentials.project_id;
+        process.env.GOOGLE_APPLICATION_CREDENTIALS = path.resolve(credentialsPath);
+    }
+    // Fall back to standard env vars for project ID (gcloud config doesn't propagate to client libraries)
+    projectId = projectId
+        ?? process.env.BIGQUERY_PROJECT_ID
+        ?? process.env.GOOGLE_CLOUD_PROJECT
+        ?? process.env.GCLOUD_PROJECT;
+    const config = { location: options.location ?? 'US' };
+    if (projectId)
+        config.projectId = projectId;
+    const connection = new BigQueryConnection('bigquery', {}, config);
     connectionInstance = connection;
     currentConnectionType = 'bigquery';
     return connection;
@@ -228,10 +239,12 @@ source: names is duckdb.table('${csvPath}') extend {
 }
 `;
     }
-    // BigQuery source
+    // BigQuery source — public dataset uses 'number' instead of 'births'
+    const bqTable = process.env.BIGQUERY_TEST_TABLE || 'bigquery-public-data.usa_names.usa_1910_current';
     return `
-source: names is bigquery.table('slite-development.tpl_test.test_usa_names') extend {
+source: names is bigquery.table('${bqTable}') extend {
   dimension:
+    births is number
     population is floor(births * 37.5)
   measure:
     total_births is births.sum()

package/dist/index.cjs

@@ -44,6 +44,8 @@ __export(index_exports, {
   fromBigQueryTable: () => fromBigQueryTable,
   fromCSV: () => fromCSV,
   fromConnection: () => fromConnection,
+  fromConnectionSQL: () => fromConnectionSQL,
+  fromDuckDBSQL: () => fromDuckDBSQL,
   fromDuckDBTable: () => fromDuckDBTable,
   generateMalloyQueries: () => generateMalloyQueries,
   generateQueryPlan: () => generateQueryPlan,
@@ -6534,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__") {
@@ -8758,7 +8763,7 @@ function formatAggregateName(measure, aggregation) {
     return aggregation === "count" ? "N" : aggregation;
   }
   if (aggregation === "count") {
-    return "N";
+    return `${measure} N`;
   }
   return `${measure} ${aggregation}`;
 }
@@ -9842,6 +9847,21 @@ function findDimensions(stmt) {
   collectFromAxis(stmt.colAxis);
   return Array.from(dims);
 }
+function buildFromClause(source, dialect) {
+  if (source.type === "sql") {
+    return `(${source.query}) _src`;
+  }
+  if (dialect === "duckdb") {
+    return `'${source.path}'`;
+  }
+  return `\`${source.path}\``;
+}
+function tableSource(path2) {
+  return { type: "table", path: path2 };
+}
+function sqlSource(query) {
+  return { type: "sql", query };
+}
 function generatePercentileWindowFunction(measure, quantile, partitionColumns, dialect) {
   const partitionClause = partitionColumns.length > 0 ? `PARTITION BY ${partitionColumns.join(", ")}` : "";
   if (dialect === "duckdb") {
@@ -10020,7 +10040,7 @@ function collectDimensionsFromGroup(group, dims) {
     }
   }
 }
-function analyzeAndGeneratePercentileConfig(stmt, tablePath, sourceName, dialect, originalTPL) {
+function analyzeAndGeneratePercentileConfig(stmt, source, sourceName, dialect, originalTPL) {
   const percentiles = findPercentileAggregations(stmt);
   if (percentiles.length === 0) {
     return {
@@ -10039,7 +10059,7 @@ function analyzeAndGeneratePercentileConfig(stmt, tablePath, sourceName, dialect
     (max, level) => level.dimensions.length > max.dimensions.length ? level : max
   );
   const derivedSQL = generateMultiLevelPercentileSQL(
-    tablePath,
+    source,
     percentiles,
     partitionLevels,
     dialect,
@@ -10063,7 +10083,8 @@ function analyzeAndGeneratePercentileConfig(stmt, tablePath, sourceName, dialect
     transformedTPL
   };
 }
-function generateMultiLevelPercentileSQL(tablePath, percentiles, partitionLevels, dialect, whereClause) {
+function generateMultiLevelPercentileSQL(source, percentiles, partitionLevels, dialect, whereClause) {
+  const sourceRef = typeof source === "string" ? tableSource(source) : source;
   const windowFunctions = [];
   for (const level of partitionLevels) {
     for (const p of percentiles) {
@@ -10078,11 +10099,7 @@ function generateMultiLevelPercentileSQL(tablePath, percentiles, partitionLevels
     }
   }
   const wherePart = whereClause ? ` WHERE ${whereClause}` : "";
-  if (dialect === "duckdb") {
-    return `SELECT *, ${windowFunctions.join(", ")} FROM '${tablePath}'${wherePart}`;
-  } else {
-    return `SELECT *, ${windowFunctions.join(", ")} FROM \`${tablePath}\`${wherePart}`;
-  }
+  return `SELECT *, ${windowFunctions.join(", ")} FROM ${buildFromClause(sourceRef, dialect)}${wherePart}`;
 }
 
 // packages/compiler/dimension-utils.ts
@@ -10192,6 +10209,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",
@@ -10274,7 +10302,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;
@@ -10306,7 +10334,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>");
@@ -10523,23 +10551,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;
@@ -10641,14 +10659,20 @@ async function createConnection(options) {
 }
 async function createBigQueryConnection(options) {
   const { BigQueryConnection } = await loadBigQuery();
-  const credentialsPath = options.credentialsPath ?? "./config/dev-credentials.json";
-  const credentials = JSON.parse(fs.readFileSync(credentialsPath, "utf-8"));
-  const projectId = options.projectId ?? credentials.project_id;
-  process.env.GOOGLE_APPLICATION_CREDENTIALS = path.resolve(credentialsPath);
+  const credentialsPath = options.credentialsPath ?? (fs.existsSync("./config/dev-credentials.json") ? "./config/dev-credentials.json" : void 0);
+  let projectId = options.projectId;
+  if (credentialsPath) {
+    const credentials = JSON.parse(fs.readFileSync(credentialsPath, "utf-8"));
+    projectId = projectId ?? credentials.project_id;
+    process.env.GOOGLE_APPLICATION_CREDENTIALS = path.resolve(credentialsPath);
+  }
+  projectId = projectId ?? process.env.BIGQUERY_PROJECT_ID ?? process.env.GOOGLE_CLOUD_PROJECT ?? process.env.GCLOUD_PROJECT;
+  const config = { location: options.location ?? "US" };
+  if (projectId) config.projectId = projectId;
   const connection = new BigQueryConnection(
     "bigquery",
     {},
-    { projectId, location: options.location ?? "US" }
+    config
   );
   connectionInstance = connection;
   currentConnectionType = "bigquery";
@@ -10719,9 +10743,11 @@ source: names is duckdb.table('${csvPath}') extend {
 }
 `;
   }
+  const bqTable = process.env.BIGQUERY_TEST_TABLE || "bigquery-public-data.usa_names.usa_1910_current";
   return `
-source: names is bigquery.table('slite-development.tpl_test.test_usa_names') extend {
+source: names is bigquery.table('${bqTable}') extend {
   dimension:
+    births is number
     population is floor(births * 37.5)
   measure:
     total_births is births.sum()
@@ -10867,11 +10893,44 @@ function fromConnection(options) {
     dialect
   });
 }
+function fromConnectionSQL(options) {
+  validateSQL(options.sql);
+  const dialect = options.dialect ?? "bigquery";
+  const connType = dialect === "duckdb" ? "duckdb" : "bigquery";
+  setConnection(options.connection, connType);
+  const sourceName = "data";
+  const prefix = dialect === "duckdb" ? "duckdb" : "bigquery";
+  const model = `source: ${sourceName} is ${prefix}.sql("""${options.sql}""")`;
+  return new EasyTPL(model, sourceName, {
+    ...options,
+    sourceSQL: options.sql,
+    dialect
+  });
+}
+function fromDuckDBSQL(sql, options = {}) {
+  validateSQL(sql);
+  setPendingConnection({ type: "duckdb" });
+  const sourceName = "data";
+  const model = `source: ${sourceName} is duckdb.sql("""${sql}""")`;
+  return new EasyTPL(model, sourceName, {
+    ...options,
+    sourceSQL: sql,
+    dialect: "duckdb"
+  });
+}
+function validateSQL(sql) {
+  if (sql.includes('"""')) {
+    throw new Error(
+      `SQL source cannot contain triple-quotes (""") as they conflict with Malloy's SQL embedding syntax.`
+    );
+  }
+}
 var EasyTPL = class _EasyTPL {
   tpl;
   model;
   sourceName;
   tablePath;
+  sourceSQL;
   dialect;
   dimensionMap;
   orderingProvider;
@@ -10880,6 +10939,7 @@ var EasyTPL = class _EasyTPL {
     this.model = model;
     this.sourceName = sourceName;
     this.tablePath = options.tablePath;
+    this.sourceSQL = options.sourceSQL;
     this.dialect = options.dialect;
     this.dimensionMap = options.dimensionMap || /* @__PURE__ */ new Map();
     this.orderingProvider = options.orderingProvider;
@@ -10900,11 +10960,12 @@ var EasyTPL = class _EasyTPL {
    * ```
    */
   async query(tplSource) {
-    if (this.tablePath && this.dialect) {
+    const sourceRef = this.getSourceRef();
+    if (sourceRef && this.dialect) {
       const stmt = parse2(tplSource);
       const percentileConfig = analyzeAndGeneratePercentileConfig(
         stmt,
-        this.tablePath,
+        sourceRef,
         this.sourceName,
         this.dialect,
         tplSource
@@ -10926,7 +10987,7 @@ var EasyTPL = class _EasyTPL {
           whereClause = rawWhere;
         }
         const derivedSQL = generateMultiLevelPercentileSQL(
-          this.tablePath,
+          sourceRef,
           percentileConfig.percentiles,
           mappedPartitionLevels,
           this.dialect,
@@ -11011,15 +11072,7 @@ ${processedMalloy}`;
    * ```
    */
   extend(malloyExtend) {
-    const extendedModel = this.model.replace(
-      /^(source: \w+ is [^)]+\))$/,
-      `$1 extend {
-${malloyExtend}
-}`
-    );
-    const finalModel = extendedModel === this.model ? this.model.replace(/}$/, `
-${malloyExtend}
-}`) : extendedModel;
+    const finalModel = this.addExtendBlock(malloyExtend);
     const newMappings = parseDimensionMappings(malloyExtend);
     const mergedMap = new Map(this.dimensionMap);
     for (const [dim, col] of newMappings) {
@@ -11042,6 +11095,7 @@ ${malloyExtend}
     }
     return new _EasyTPL(modelWithAutoDims, this.sourceName, {
       tablePath: this.tablePath,
+      sourceSQL: this.sourceSQL,
       dialect: this.dialect,
       dimensionMap: mergedMap,
       orderingProvider
@@ -11063,6 +11117,10 @@ ${malloyExtend}
   getDimensionMap() {
     return new Map(this.dimensionMap);
   }
+  /** Get the source SQL (if this is a SQL-backed source) */
+  getSourceSQL() {
+    return this.sourceSQL;
+  }
   /** Get dimension→raw column mapping (for backward compatibility) */
   getDimensionToColumnMap() {
     const result = /* @__PURE__ */ new Map();
@@ -11071,6 +11129,56 @@ ${malloyExtend}
     }
     return result;
   }
+  /**
+   * Build a SourceRef for percentile SQL generation.
+   * Prefers sourceSQL (wrapped as subquery) over tablePath.
+   */
+  getSourceRef() {
+    if (this.sourceSQL) {
+      return sqlSource(this.sourceSQL);
+    }
+    if (this.tablePath) {
+      return tableSource(this.tablePath);
+    }
+    return void 0;
+  }
+  /**
+   * Add an extend block to the model string.
+   * Handles both table-based models (single closing paren) and
+   * SQL-based models (triple-quoted SQL with embedded parentheses).
+   */
+  addExtendBlock(malloyExtend) {
+    if (this.model.includes(" extend {")) {
+      return this.model.replace(/}\s*$/, `
+${malloyExtend}
+}`);
+    }
+    const sqlSourceMatch = this.model.match(
+      /^(source:\s+\w+\s+is\s+\w+\.sql\("""[\s\S]*?"""\))$/
+    );
+    if (sqlSourceMatch) {
+      return `${sqlSourceMatch[1]} extend {
+${malloyExtend}
+}`;
+    }
+    const tableSourceMatch = this.model.match(
+      /^(source:\s+\w+\s+is\s+\w+\.table\('[^']*'\))$/
+    );
+    if (tableSourceMatch) {
+      return `${tableSourceMatch[1]} extend {
+${malloyExtend}
+}`;
+    }
+    const genericMatch = this.model.match(/^([\s\S]*\))$/);
+    if (genericMatch) {
+      return `${genericMatch[1]} extend {
+${malloyExtend}
+}`;
+    }
+    return `${this.model} extend {
+${malloyExtend}
+}`;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -11088,6 +11196,8 @@ ${malloyExtend}
   fromBigQueryTable,
   fromCSV,
   fromConnection,
+  fromConnectionSQL,
+  fromDuckDBSQL,
   fromDuckDBTable,
   generateMalloyQueries,
   generateQueryPlan,

package/dist/index.d.ts

@@ -214,12 +214,65 @@ export declare function fromConnection(options: {
     table: string;
     dialect?: SqlDialect;
 } & TPLOptions): EasyTPL;
+/**
+ * Query any SQL query result using a pre-built Malloy connection.
+ * Use this when your data comes from a SQL query (e.g., a JOIN) rather than a single table.
+ *
+ * The SQL is used as Malloy's `bigquery.sql("""...""")` or `duckdb.sql("""...""")` source,
+ * which supports schema introspection and querying without creating views or temp tables.
+ *
+ * @example
+ * ```typescript
+ * import { BigQueryConnection } from '@malloydata/db-bigquery';
+ * import { fromConnectionSQL } from 'tplm-lang';
+ *
+ * const connection = new BigQueryConnection('bigquery', undefined, {
+ *   projectId: 'my-project',
+ *   credentials: { client_email, private_key },
+ * });
+ *
+ * const tpl = fromConnectionSQL({
+ *   connection,
+ *   sql: `
+ *     SELECT a.revenue, a.product_category, b.region
+ *     FROM \`p.d.sales\` a
+ *     JOIN \`p.d.customers\` b ON a.customer_id = b.customer_id
+ *   `,
+ *   dialect: 'bigquery',
+ * });
+ * const { html } = await tpl.query('TABLE ROWS region * revenue.sum COLS product_category;');
+ * ```
+ */
+export declare function fromConnectionSQL(options: {
+    connection: Connection;
+    sql: string;
+    dialect?: SqlDialect;
+} & TPLOptions): EasyTPL;
+/**
+ * Query a DuckDB SQL result directly.
+ * Use this when your data comes from a SQL query rather than a file.
+ *
+ * @example
+ * ```typescript
+ * import { fromDuckDBSQL } from 'tplm-lang';
+ *
+ * const tpl = fromDuckDBSQL(`
+ *   SELECT a.*, b.region
+ *   FROM 'sales.csv' a
+ *   JOIN 'regions.csv' b ON a.region_id = b.id
+ * `);
+ * const { html } = await tpl.query('TABLE ROWS region * revenue.sum;');
+ * ```
+ */
+export declare function fromDuckDBSQL(sql: string, options?: TPLOptions): EasyTPL;
 /**
  * Extended options for EasyTPL that include percentile support metadata.
  */
 interface EasyTPLOptions extends TPLOptions {
     /** Path to the source table (for percentile support) */
     tablePath?: string;
+    /** Raw SQL source (alternative to tablePath, for SQL-backed sources) */
+    sourceSQL?: string;
     /** SQL dialect (for percentile support) */
     dialect?: SqlDialect;
     /** Mapping from computed dimension names to dimension info (for percentile partitioning) */
@@ -230,7 +283,8 @@ interface EasyTPLOptions extends TPLOptions {
 import { type DimensionInfo } from './compiler/dimension-utils.js';
 /**
  * Simplified TPL API for direct table queries.
- * Created by fromDuckDBTable, fromCSV, or fromBigQueryTable.
+ * Created by fromDuckDBTable, fromCSV, fromBigQueryTable, fromConnection,
+ * fromConnectionSQL, or fromDuckDBSQL.
  *
  * Supports percentile aggregations (p25, p50/median, p75, p90, p95, p99)
  * by automatically generating derived SQL sources with window functions.
@@ -240,6 +294,7 @@ export declare class EasyTPL {
     private model;
     private sourceName;
     private tablePath?;
+    private sourceSQL?;
     private dialect?;
     private dimensionMap;
     private orderingProvider?;
@@ -290,6 +345,19 @@ export declare class EasyTPL {
     getDialect(): SqlDialect | undefined;
     /** Get the dimension info map (for percentile partitioning) */
     getDimensionMap(): Map<string, DimensionInfo>;
+    /** Get the source SQL (if this is a SQL-backed source) */
+    getSourceSQL(): string | undefined;
     /** Get dimension→raw column mapping (for backward compatibility) */
     getDimensionToColumnMap(): Map<string, string>;
+    /**
+     * Build a SourceRef for percentile SQL generation.
+     * Prefers sourceSQL (wrapped as subquery) over tablePath.
+     */
+    private getSourceRef;
+    /**
+     * Add an extend block to the model string.
+     * Handles both table-based models (single closing paren) and
+     * SQL-based models (triple-quoted SQL with embedded parentheses).
+     */
+    private addExtendBlock;
 }

package/dist/index.js

@@ -124,7 +124,7 @@ export function createBigQueryTPL(options = {}) {
 // EASY CONNECTORS - Skip Malloy, just query your data
 // ============================================================================
 // Import percentile utilities for EasyTPL
-import { analyzeAndGeneratePercentileConfig, postProcessMalloyForPercentiles, generateMultiLevelPercentileSQL, } from './compiler/percentile-utils.js';
+import { analyzeAndGeneratePercentileConfig, postProcessMalloyForPercentiles, generateMultiLevelPercentileSQL, sqlSource, tableSource, } from './compiler/percentile-utils.js';
 /**
  * Query a DuckDB-compatible file (CSV, Parquet) directly.
  * No Malloy knowledge required - just point to your file and query.
@@ -220,11 +220,90 @@ export function fromConnection(options) {
         dialect,
     });
 }
+/**
+ * Query any SQL query result using a pre-built Malloy connection.
+ * Use this when your data comes from a SQL query (e.g., a JOIN) rather than a single table.
+ *
+ * The SQL is used as Malloy's `bigquery.sql("""...""")` or `duckdb.sql("""...""")` source,
+ * which supports schema introspection and querying without creating views or temp tables.
+ *
+ * @example
+ * ```typescript
+ * import { BigQueryConnection } from '@malloydata/db-bigquery';
+ * import { fromConnectionSQL } from 'tplm-lang';
+ *
+ * const connection = new BigQueryConnection('bigquery', undefined, {
+ *   projectId: 'my-project',
+ *   credentials: { client_email, private_key },
+ * });
+ *
+ * const tpl = fromConnectionSQL({
+ *   connection,
+ *   sql: `
+ *     SELECT a.revenue, a.product_category, b.region
+ *     FROM \`p.d.sales\` a
+ *     JOIN \`p.d.customers\` b ON a.customer_id = b.customer_id
+ *   `,
+ *   dialect: 'bigquery',
+ * });
+ * const { html } = await tpl.query('TABLE ROWS region * revenue.sum COLS product_category;');
+ * ```
+ */
+export function fromConnectionSQL(options) {
+    validateSQL(options.sql);
+    const dialect = options.dialect ?? 'bigquery';
+    const connType = dialect === 'duckdb' ? 'duckdb' : 'bigquery';
+    setConnection(options.connection, connType);
+    const sourceName = 'data';
+    const prefix = dialect === 'duckdb' ? 'duckdb' : 'bigquery';
+    const model = `source: ${sourceName} is ${prefix}.sql("""${options.sql}""")`;
+    return new EasyTPL(model, sourceName, {
+        ...options,
+        sourceSQL: options.sql,
+        dialect,
+    });
+}
+/**
+ * Query a DuckDB SQL result directly.
+ * Use this when your data comes from a SQL query rather than a file.
+ *
+ * @example
+ * ```typescript
+ * import { fromDuckDBSQL } from 'tplm-lang';
+ *
+ * const tpl = fromDuckDBSQL(`
+ *   SELECT a.*, b.region
+ *   FROM 'sales.csv' a
+ *   JOIN 'regions.csv' b ON a.region_id = b.id
+ * `);
+ * const { html } = await tpl.query('TABLE ROWS region * revenue.sum;');
+ * ```
+ */
+export function fromDuckDBSQL(sql, options = {}) {
+    validateSQL(sql);
+    setPendingConnection({ type: 'duckdb' });
+    const sourceName = 'data';
+    const model = `source: ${sourceName} is duckdb.sql("""${sql}""")`;
+    return new EasyTPL(model, sourceName, {
+        ...options,
+        sourceSQL: sql,
+        dialect: 'duckdb',
+    });
+}
+/**
+ * Validate that SQL doesn't contain triple-quotes which would break Malloy's SQL embedding.
+ */
+function validateSQL(sql) {
+    if (sql.includes('"""')) {
+        throw new Error('SQL source cannot contain triple-quotes (""") as they conflict with Malloy\'s SQL embedding syntax.');
+    }
+}
 // Import dimension utilities from compiler
 import { parseDimensionMappings, detectDimensionOrdering, } from './compiler/dimension-utils.js';
 /**
  * Simplified TPL API for direct table queries.
- * Created by fromDuckDBTable, fromCSV, or fromBigQueryTable.
+ * Created by fromDuckDBTable, fromCSV, fromBigQueryTable, fromConnection,
+ * fromConnectionSQL, or fromDuckDBSQL.
  *
  * Supports percentile aggregations (p25, p50/median, p75, p90, p95, p99)
  * by automatically generating derived SQL sources with window functions.
@@ -234,6 +313,7 @@ export class EasyTPL {
     model;
     sourceName;
     tablePath;
+    sourceSQL;
     dialect;
     dimensionMap;
     orderingProvider;
@@ -242,6 +322,7 @@ export class EasyTPL {
         this.model = model;
         this.sourceName = sourceName;
         this.tablePath = options.tablePath;
+        this.sourceSQL = options.sourceSQL;
         this.dialect = options.dialect;
         this.dimensionMap = options.dimensionMap || new Map();
         this.orderingProvider = options.orderingProvider;
@@ -262,11 +343,13 @@ export class EasyTPL {
      * ```
      */
     async query(tplSource) {
-        // Check if we can handle percentiles (need tablePath and dialect)
-        if (this.tablePath && this.dialect) {
+        // Resolve the source reference for percentile support
+        const sourceRef = this.getSourceRef();
+        // Check if we can handle percentiles (need a source and dialect)
+        if (sourceRef && this.dialect) {
             // Parse the TPL to detect percentiles
             const stmt = parse(tplSource);
-            const percentileConfig = analyzeAndGeneratePercentileConfig(stmt, this.tablePath, this.sourceName, this.dialect, tplSource);
+            const percentileConfig = analyzeAndGeneratePercentileConfig(stmt, sourceRef, this.sourceName, this.dialect, tplSource);
             if (percentileConfig.hasPercentiles && percentileConfig.transformedTPL) {
                 // Map partition levels to use SQL expressions (CASE statements for computed dimensions)
                 // This ensures percentiles are computed per computed dimension value, not per raw column value
@@ -287,7 +370,7 @@ export class EasyTPL {
                     }
                     whereClause = rawWhere;
                 }
-                const derivedSQL = generateMultiLevelPercentileSQL(this.tablePath, percentileConfig.percentiles, mappedPartitionLevels, this.dialect, whereClause || undefined);
+                const derivedSQL = generateMultiLevelPercentileSQL(sourceRef, percentileConfig.percentiles, mappedPartitionLevels, this.dialect, whereClause || undefined);
                 // Generate Malloy source with derived SQL
                 const connectionPrefix = this.dialect === 'bigquery' ? 'bigquery' : 'duckdb';
                 let derivedMalloySource = `source: ${this.sourceName} is ${connectionPrefix}.sql("""${derivedSQL}""")`;
@@ -374,12 +457,8 @@ export class EasyTPL {
      * ```
      */
     extend(malloyExtend) {
-        // Remove the closing source and add extend block
-        const extendedModel = this.model.replace(/^(source: \w+ is [^)]+\))$/, `$1 extend {\n${malloyExtend}\n}`);
-        // If no match (already has extend), append to existing extend block
-        const finalModel = extendedModel === this.model
-            ? this.model.replace(/}$/, `\n${malloyExtend}\n}`)
-            : extendedModel;
+        // Add extend block to the model, handling both table and SQL source patterns
+        const finalModel = this.addExtendBlock(malloyExtend);
         // Parse the extend text to extract dimension→column mappings
         const newMappings = parseDimensionMappings(malloyExtend);
         // Merge with existing mappings (new mappings take precedence)
@@ -409,6 +488,7 @@ export class EasyTPL {
         }
         return new EasyTPL(modelWithAutoDims, this.sourceName, {
             tablePath: this.tablePath,
+            sourceSQL: this.sourceSQL,
             dialect: this.dialect,
             dimensionMap: mergedMap,
             orderingProvider,
@@ -430,6 +510,10 @@ export class EasyTPL {
     getDimensionMap() {
         return new Map(this.dimensionMap);
     }
+    /** Get the source SQL (if this is a SQL-backed source) */
+    getSourceSQL() {
+        return this.sourceSQL;
+    }
     /** Get dimension→raw column mapping (for backward compatibility) */
     getDimensionToColumnMap() {
         const result = new Map();
@@ -438,4 +522,47 @@ export class EasyTPL {
         }
         return result;
     }
+    /**
+     * Build a SourceRef for percentile SQL generation.
+     * Prefers sourceSQL (wrapped as subquery) over tablePath.
+     */
+    getSourceRef() {
+        if (this.sourceSQL) {
+            return sqlSource(this.sourceSQL);
+        }
+        if (this.tablePath) {
+            return tableSource(this.tablePath);
+        }
+        return undefined;
+    }
+    /**
+     * Add an extend block to the model string.
+     * Handles both table-based models (single closing paren) and
+     * SQL-based models (triple-quoted SQL with embedded parentheses).
+     */
+    addExtendBlock(malloyExtend) {
+        // If model already has an extend block, append to it
+        if (this.model.includes(' extend {')) {
+            return this.model.replace(/}\s*$/, `\n${malloyExtend}\n}`);
+        }
+        // For SQL sources: match triple-quoted pattern which may contain parens
+        // e.g. source: data is bigquery.sql("""SELECT ... FROM (subq) ...""")
+        const sqlSourceMatch = this.model.match(/^(source:\s+\w+\s+is\s+\w+\.sql\("""[\s\S]*?"""\))$/);
+        if (sqlSourceMatch) {
+            return `${sqlSourceMatch[1]} extend {\n${malloyExtend}\n}`;
+        }
+        // For table sources: match up to closing paren
+        // e.g. source: data is duckdb.table('file.csv')
+        const tableSourceMatch = this.model.match(/^(source:\s+\w+\s+is\s+\w+\.table\('[^']*'\))$/);
+        if (tableSourceMatch) {
+            return `${tableSourceMatch[1]} extend {\n${malloyExtend}\n}`;
+        }
+        // Fallback: try the original generic pattern (for any model ending with ")")
+        const genericMatch = this.model.match(/^([\s\S]*\))$/);
+        if (genericMatch) {
+            return `${genericMatch[1]} extend {\n${malloyExtend}\n}`;
+        }
+        // If nothing matched, just append
+        return `${this.model} extend {\n${malloyExtend}\n}`;
+    }
 }

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;

package/package.json

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