Column descriptions

apps/webapp/app/components/code/TSQLResultsTable.tsx

@@ -23,6 +23,7 @@ import { Paragraph } from "../primitives/Paragraph";
 import { TextLink } from "../primitives/TextLink";
 import { v3RunPathFromFriendlyId } from "~/utils/pathBuilder";
 import { SimpleTooltip } from "../primitives/Tooltip";
+import { InformationCircleIcon } from "@heroicons/react/20/solid";
 
 /**
  * Check if a ClickHouse type is a DateTime type
@@ -211,7 +212,22 @@ export function TSQLResultsTable({
       <TableHeader>
         <TableRow>
           {columns.map((col) => (
-            <TableHeaderCell key={col.name}>{col.name}</TableHeaderCell>
+            <TableHeaderCell key={col.name}>
+              {col.description ? (
+                <SimpleTooltip
+                  content={col.description}
+                  disableHoverableContent
+                  button={
+                    <span className="inline-flex items-center gap-1">
+                      {col.name}
+                      <InformationCircleIcon className="size-4 text-text-dimmed" />
+                    </span>
+                  }
+                />
+              ) : (
+                col.name
+              )}
+            </TableHeaderCell>
           ))}
         </TableRow>
       </TableHeader>

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

@@ -484,7 +484,11 @@ export class ClickHousePrinter {
 
         // Check if the column has a different clickhouseName - if so, add an alias
         // to ensure results come back with the user-facing name
-        if (outputName && sourceColumn?.clickhouseName && sourceColumn.clickhouseName !== outputName) {
+        if (
+          outputName &&
+          sourceColumn?.clickhouseName &&
+          sourceColumn.clickhouseName !== outputName
+        ) {
           sqlResult = `${visited} AS ${this.printIdentifier(outputName)}`;
         } else {
           sqlResult = visited;
@@ -507,6 +511,11 @@ export class ClickHousePrinter {
         metadata.customRenderType = sourceColumn.customRenderType;
       }
 
+      // Only add description if specified in schema (columns and virtual columns)
+      if (sourceColumn?.description) {
+        metadata.description = sourceColumn.description;
+      }
+
       this.outputColumns.push(metadata);
     }
 
@@ -655,7 +664,12 @@ export class ClickHousePrinter {
     const name = call.name.toLowerCase();
 
     // Count functions always return UInt64
-    if (name === "count" || name === "countif" || name === "countdistinct" || name === "countdistinctif") {
+    if (
+      name === "count" ||
+      name === "countif" ||
+      name === "countdistinct" ||
+      name === "countdistinctif"
+    ) {
       return "UInt64";
     }
 

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

@@ -136,6 +136,11 @@ export interface OutputColumnMetadata {
    * When set, the UI should use a custom renderer instead of the default for the ClickHouseType.
    */
   customRenderType?: string;
+  /**
+   * Description from the schema column definition, if available.
+   * Only present for columns or virtual columns defined in the table schema.
+   */
+  description?: string;
 }
 
 /**