Try and avoid SELECT *, through warnings and training the AI

Author: matt-aitken

apps/webapp/app/v3/querySchemas.ts

@@ -42,6 +42,7 @@ export const runsSchema: TableSchema = {
           "A unique ID for a run. They always start with `run_`, e.g., run_cm1a2b3c4d5e6f7g8h9i",
         customRenderType: "runId",
         example: "run_cm1a2b3c4d5e6f7g8h9i",
+        coreColumn: true,
       }),
     },
     environment: {
@@ -87,6 +88,7 @@ export const runsSchema: TableSchema = {
         valueMap: runStatusTitleFromStatus,
         customRenderType: "runStatus",
         example: "Completed",
+        coreColumn: true,
       }),
     },
     is_finished: {
@@ -103,7 +105,11 @@ export const runsSchema: TableSchema = {
     // Task & queue
     task_identifier: {
       name: "task_identifier",
-      ...column("String", { description: "Task identifier/slug", example: "my-background-task" }),
+      ...column("String", {
+        description: "Task identifier/slug",
+        example: "my-background-task",
+        coreColumn: true,
+      }),
     },
     queue: {
       name: "queue",
@@ -182,6 +188,7 @@ export const runsSchema: TableSchema = {
       ...column("DateTime64", {
         description: "When the run was triggered.",
         example: "2024-01-15 09:30:00.000",
+        coreColumn: true,
       }),
     },
     queued_at: {
@@ -419,7 +426,7 @@ export const querySchemas: TableSchema[] = [runsSchema];
 /**
  * Default query for the query editor
  */
-export const defaultQuery = `SELECT *
+export const defaultQuery = `SELECT run_id, task_identifier, triggered_at, status
 FROM runs
 ORDER BY triggered_at DESC
 LIMIT 100`;

apps/webapp/app/v3/services/aiQueryService.server.ts

@@ -258,10 +258,23 @@ export class AIQueryService {
         parts.push(table.description);
       }
       parts.push("");
+
+      // Identify core columns
+      const coreColumns = Object.values(table.columns)
+        .filter((col) => col.coreColumn === true)
+        .map((col) => col.name);
+      if (coreColumns.length > 0) {
+        parts.push(`Core columns (use these as defaults): ${coreColumns.join(", ")}`);
+        parts.push("");
+      }
+
       parts.push("Columns:");
 
       for (const col of Object.values(table.columns)) {
         let colDesc = `- ${col.name} (${col.type})`;
+        if (col.coreColumn) {
+          colDesc += " [CORE]";
+        }
         if (col.description) {
           colDesc += `: ${col.description}`;
         }
@@ -350,13 +363,16 @@ HAVING cnt > 10
 
 ## Important Rules
 
-1. ALWAYS use the validateTSQLQuery tool to check your query before returning it
-2. If validation fails, fix the issues and try again (up to 3 attempts)
-3. Use column names exactly as defined in the schema (case-sensitive)
-4. For enum columns like status, use the allowed values shown in the schema
-5. Always include a LIMIT clause (default to 100 if not specified)
-6. Use meaningful column aliases with AS for aggregations
-7. Format queries with proper indentation for readability
+1. NEVER use SELECT * - ClickHouse is a columnar database where SELECT * has very poor performance
+2. Always select only the specific columns needed for the request
+3. When column selection is ambiguous, use the core columns marked [CORE] in the schema
+4. ALWAYS use the validateTSQLQuery tool to check your query before returning it
+5. If validation fails, fix the issues and try again (up to 3 attempts)
+6. Use column names exactly as defined in the schema (case-sensitive)
+7. For enum columns like status, use the allowed values shown in the schema
+8. Always include a LIMIT clause (default to 100 if not specified)
+9. Use meaningful column aliases with AS for aggregations
+10. Format queries with proper indentation for readability
 
 ## Response Format
 
@@ -431,13 +447,15 @@ HAVING cnt > 10
 
 ## Important Rules
 
-1. ALWAYS use the validateTSQLQuery tool to check your modified query before returning it
-2. If validation fails, fix the issues and try again (up to 3 attempts)
-3. Use column names exactly as defined in the schema (case-sensitive)
-4. For enum columns like status, use the allowed values shown in the schema
-5. Always include a LIMIT clause (default to 100 if not specified)
-6. Preserve the user's existing query structure and style where possible
-7. Only make the changes specifically requested by the user
+1. NEVER use SELECT * - ClickHouse is a columnar database where SELECT * has very poor performance
+2. If the existing query uses SELECT *, replace it with specific columns (use core columns marked [CORE] as defaults)
+3. ALWAYS use the validateTSQLQuery tool to check your modified query before returning it
+4. If validation fails, fix the issues and try again (up to 3 attempts)
+5. Use column names exactly as defined in the schema (case-sensitive)
+6. For enum columns like status, use the allowed values shown in the schema
+7. Always include a LIMIT clause (default to 100 if not specified)
+8. Preserve the user's existing query structure and style where possible
+9. Only make the changes specifically requested by the user
 
 ## Response Format
 

internal-packages/tsql/src/index.ts

@@ -64,6 +64,8 @@ export {
   findColumn,
   findTable,
   getAllowedUserValues,
+  // Core column utilities
+  getCoreColumns,
   getExternalValue,
   getInternalValue,
   getInternalValueFromMapping,

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

@@ -133,6 +133,23 @@ export interface ColumnSchema {
    * ```
    */
   example?: string;
+  /**
+   * Whether this is a core column that should be included in default queries.
+   *
+   * Core columns represent the essential information for a table and are suggested
+   * as alternatives when users attempt to use SELECT * (which has poor performance
+   * in columnar databases like ClickHouse).
+   *
+   * @example
+   * ```typescript
+   * {
+   *   name: "run_id",
+   *   type: "String",
+   *   coreColumn: true,
+   * }
+   * ```
+   */
+  coreColumn?: boolean;
   /**
    * Name of the runtime field mapping to use for value translation.
    * When set, values are translated using the mapping provided at query time.
@@ -683,6 +700,21 @@ export function getAllTableNames(schema: SchemaRegistry): string[] {
   return Object.keys(schema.tables);
 }
 
+/**
+ * Get the names of core columns for a table.
+ *
+ * Core columns are the essential columns that should be used when users
+ * need a default set of columns (e.g., as an alternative to SELECT *).
+ *
+ * @param table - The table schema
+ * @returns Array of core column names, empty if none are marked as core
+ */
+export function getCoreColumns(table: TableSchema): string[] {
+  return Object.values(table.columns)
+    .filter((col) => col.coreColumn === true)
+    .map((col) => col.name);
+}
+
 // ============================================================
 // Error Message Sanitization
 // ============================================================

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

@@ -20,7 +20,7 @@ import type {
   ArithmeticOperation,
 } from "./ast.js";
 import type { TableSchema, ColumnSchema } from "./schema.js";
-import { getAllowedUserValues, isValidUserValue } from "./schema.js";
+import { getAllowedUserValues, getCoreColumns, isValidUserValue } from "./schema.js";
 import { CompareOperationOp, ArithmeticOperationOp } from "./ast.js";
 
 /**
@@ -37,7 +37,7 @@ export interface ValidationIssue {
   /** Severity of the issue */
   severity: ValidationSeverity;
   /** The type of issue */
-  type: "unknown_column" | "unknown_table" | "invalid_enum_value";
+  type: "unknown_column" | "unknown_table" | "invalid_enum_value" | "select_star";
   /** Optional: the column name that caused the issue */
   columnName?: string;
   /** Optional: the table name that caused the issue */
@@ -46,6 +46,8 @@ export interface ValidationIssue {
   invalidValue?: string;
   /** Optional: list of allowed values */
   allowedValues?: string[];
+  /** Optional: suggested columns to use instead (for select_star) */
+  suggestedColumns?: string[];
 }
 
 /**
@@ -170,6 +172,19 @@ function validateSelectSetQuery(node: SelectSetQuery, context: ValidationContext
   }
 }
 
+/**
+ * Check if an expression is a SELECT * (asterisk)
+ */
+function isSelectStar(expr: Expression): boolean {
+  if ((expr as Field).expression_type !== "field") return false;
+  const field = expr as Field;
+  // SELECT * or SELECT table.*
+  return (
+    (field.chain.length === 1 && field.chain[0] === "*") ||
+    (field.chain.length === 2 && field.chain[1] === "*")
+  );
+}
+
 /**
  * Validate a SELECT query
  */
@@ -183,6 +198,34 @@ function validateSelectQuery(node: SelectQuery, context: ValidationContext): voi
     extractTablesFromJoin(node.select_from, context);
   }
 
+  // Check for SELECT * and emit warning
+  if (node.select) {
+    const hasSelectStar = node.select.some(isSelectStar);
+    if (hasSelectStar) {
+      // Collect core columns from all tables in context
+      const coreColumns: string[] = [];
+      for (const tableSchema of context.tables.values()) {
+        const tableCoreColumns = getCoreColumns(tableSchema);
+        coreColumns.push(...tableCoreColumns);
+      }
+
+      // Build suggestion message
+      let suggestionMsg = "SELECT * will be far slower than selecting specific columns. ";
+      if (coreColumns.length > 0) {
+        suggestionMsg += `Consider selecting specific columns, e.g.: ${coreColumns.join(", ")}`;
+      } else {
+        suggestionMsg += "Consider selecting only the columns you need.";
+      }
+
+      context.issues.push({
+        message: suggestionMsg,
+        severity: "warning",
+        type: "select_star",
+        suggestedColumns: coreColumns.length > 0 ? coreColumns : undefined,
+      });
+    }
+  }
+
   // Extract column aliases from SELECT clause before validation
   // This allows ORDER BY and HAVING to reference aliased columns
   if (node.select) {