Did you mean errors

Author: matt-aitken

internal-packages/tsql/src/query/printer.test.ts

@@ -2205,6 +2205,22 @@ describe("Unknown column blocking", () => {
       }).toThrow(QueryError);
     });
 
+    it("should suggest TSQL column name when user types ClickHouse column name", () => {
+      // The schema exposes 'created' but the internal ClickHouse column is 'created_at'
+      // When user types 'created_at', we should suggest 'created'
+      const schema = createSchemaRegistry([runsSchema]);
+      const ctx = createPrinterContext({
+        organizationId: "org_test",
+        projectId: "proj_test",
+        environmentId: "env_test",
+        schema,
+      });
+
+      expect(() => {
+        printQuery("SELECT id, created_at FROM runs", ctx);
+      }).toThrow(/Did you mean "created"/);
+    });
+
     it("should throw error for unknown qualified column (table.column)", () => {
       expect(() => {
         printQuery("SELECT task_runs.unknown_column FROM task_runs");
@@ -2221,9 +2237,7 @@ describe("Unknown column blocking", () => {
 
     it("should throw error for unknown column in complex WHERE", () => {
       expect(() => {
-        printQuery(
-          "SELECT id FROM task_runs WHERE status = 'completed' AND unknown_column > 10"
-        );
+        printQuery("SELECT id FROM task_runs WHERE status = 'completed' AND unknown_column > 10");
       }).toThrow(QueryError);
     });
   });

internal-packages/tsql/src/query/printer.ts

@@ -2221,6 +2221,12 @@ export class ClickHousePrinter {
     // This is a security issue - block access to unknown columns
     if (this.tableContexts.size > 0) {
       // Only throw if we have tables in context (otherwise might be subquery)
+      // Check if the user typed a ClickHouse column name instead of the TSQL name
+      const suggestion = this.findTSQLNameForClickHouseName(columnName);
+      if (suggestion) {
+        throw new QueryError(`Unknown column "${columnName}". Did you mean "${suggestion}"?`);
+      }
+
       const availableColumns = this.getAvailableColumnNames();
       throw new QueryError(
         `Unknown column "${columnName}". Available columns: ${availableColumns.join(", ")}`
@@ -2242,18 +2248,47 @@ export class ClickHousePrinter {
     return [...new Set(columns)].sort();
   }
 
+  /**
+   * Find the TSQL column name for a given ClickHouse column name.
+   * This is used to provide helpful suggestions when users accidentally
+   * use internal ClickHouse column names instead of TSQL names.
+   *
+   * @returns The TSQL column name if found, null otherwise
+   */
+  private findTSQLNameForClickHouseName(clickhouseName: string): string | null {
+    for (const tableSchema of this.tableContexts.values()) {
+      for (const [tsqlName, columnSchema] of Object.entries(tableSchema.columns)) {
+        if (columnSchema.clickhouseName === clickhouseName) {
+          return tsqlName;
+        }
+      }
+    }
+    return null;
+  }
+
   /**
    * Resolve a column name to its ClickHouse name using the table schema
    *
    * @throws QueryError if the column is not found in the table schema
    */
-  private resolveColumnName(tableSchema: TableSchema, columnName: string, tableAlias?: string): string {
+  private resolveColumnName(
+    tableSchema: TableSchema,
+    columnName: string,
+    tableAlias?: string
+  ): string {
     const columnSchema = tableSchema.columns[columnName];
     if (columnSchema) {
       return columnSchema.clickhouseName || columnSchema.name;
     }
 
     // Column not in schema - this is a security issue, block access
+    // Check if the user typed a ClickHouse column name instead of the TSQL name
+    for (const [tsqlName, colSchema] of Object.entries(tableSchema.columns)) {
+      if (colSchema.clickhouseName === columnName) {
+        throw new QueryError(`Unknown column "${columnName}". Did you mean "${tsqlName}"?`);
+      }
+    }
+
     const availableColumns = Object.keys(tableSchema.columns).sort().join(", ");
     const tableName = tableAlias || tableSchema.name;
     throw new QueryError(

internal-packages/tsql/src/query/schema.test.ts

@@ -615,6 +615,17 @@ describe("Error message sanitization", () => {
       expect(sanitized).toBe("SELECT run_id, triggered_at FROM table");
     });
 
+    it("should NOT replace column names in 'Did you mean' error messages", () => {
+      // When a user types an internal ClickHouse column name, we show "Did you mean X?"
+      // The sanitizer should NOT replace the column name in this case, as it would
+      // turn "Unknown column 'created_at'. Did you mean 'triggered_at'?" into
+      // "Unknown column 'triggered_at'. Did you mean 'triggered_at'?" which is confusing
+      const error = 'Unknown column "created_at". Did you mean "triggered_at"?';
+      const sanitized = sanitizeErrorMessage(error, [runsSchema]);
+      // Should preserve both the original column name AND the suggestion
+      expect(sanitized).toBe('Unknown column "created_at". Did you mean "triggered_at"?');
+    });
+
     it("should prioritize longer matches (table.column before standalone column)", () => {
       // This tests that we replace "trigger_dev.task_runs_v2.friendly_id" as a unit,
       // not "trigger_dev.task_runs_v2" and then "friendly_id" separately

internal-packages/tsql/src/query/schema.ts

@@ -857,10 +857,17 @@ export function sanitizeErrorMessage(message: string, schemas: TableSchema[]): s
   }
 
   // Step 5: Replace standalone column names (for unqualified references)
-  // Sort by length descending to replace longer names first
-  const sortedColumnNames = [...columnNameMap.entries()].sort((a, b) => b[0].length - a[0].length);
-  for (const [clickhouseName, { tsqlName }] of sortedColumnNames) {
-    result = replaceAllOccurrences(result, clickhouseName, tsqlName);
+  // Skip column replacement for "Did you mean" errors - these already have the correct names
+  // and replacing would turn "Unknown column 'created_at'. Did you mean 'triggered_at'?"
+  // into "Unknown column 'triggered_at'. Did you mean 'triggered_at'?" which is confusing
+  if (!result.includes('Did you mean "')) {
+    // Sort by length descending to replace longer names first
+    const sortedColumnNames = [...columnNameMap.entries()].sort(
+      (a, b) => b[0].length - a[0].length
+    );
+    for (const [clickhouseName, { tsqlName }] of sortedColumnNames) {
+      result = replaceAllOccurrences(result, clickhouseName, tsqlName);
+    }
   }
 
   // Step 6: Remove redundant column aliases like "run_id AS run_id"