From 06f8af4c839eec0c214247a368735359607febd5 Mon Sep 17 00:00:00 2001
From: Matt Aitken <matt@mattaitken.com>
Date: Thu, 18 Dec 2025 19:15:24 +0000
Subject: [PATCH] Column descriptions

---
 .../app/components/code/TSQLResultsTable.tsx   | 18 +++++++++++++++++-
 internal-packages/tsql/src/query/printer.ts    | 18 ++++++++++++++++--
 internal-packages/tsql/src/query/schema.ts     |  5 +++++
 3 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/apps/webapp/app/components/code/TSQLResultsTable.tsx b/apps/webapp/app/components/code/TSQLResultsTable.tsx
index c954e23b7..90cc78f14 100644
--- a/apps/webapp/app/components/code/TSQLResultsTable.tsx
+++ b/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>
diff --git a/internal-packages/tsql/src/query/printer.ts b/internal-packages/tsql/src/query/printer.ts
index e8c1de7e7..0c27bb1d8 100644
--- a/internal-packages/tsql/src/query/printer.ts
+++ b/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";
     }
 
diff --git a/internal-packages/tsql/src/query/schema.ts b/internal-packages/tsql/src/query/schema.ts
index 9711cd21e..a1e0e12c4 100644
--- a/internal-packages/tsql/src/query/schema.ts
+++ b/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;
 }
 
 /**