feat(results): render EXPLAIN raw by default (unless an explicit FORMAT is given)

EXPLAIN output is plan text; as a one-column table it loses its indentation and
reads poorly. Default EXPLAIN to the raw text view as plain TabSeparated (no
header noise) so the plan shows verbatim; an explicit trailing FORMAT clause
still wins (detectSqlFormat is checked first). runQuery now passes a raw format
name through as default_format (instead of always JSONCompact) — that's what
lets the implicit EXPLAIN format request plain TabSeparated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QGBS74oUsXarGkCRQKEFLu

Author: BorisTyshkevich

src/core/format.js

@@ -74,6 +74,12 @@ export function detectSqlFormat(sql) {
   return m ? m[1] : null;
 }
 
+/** True if the statement is an EXPLAIN (leading keyword). EXPLAIN output is plan
+ *  text, so the caller renders it raw unless the user gave an explicit FORMAT. Pure. */
+export function isExplain(sql) {
+  return /^\s*EXPLAIN\b/i.test(String(sql || ''));
+}
+
 /**
  * Derive a short display name for a saved query: "Query · <table>" when a
  * FROM clause is present, else the first 48 chars of the collapsed SQL.

src/net/ch-client.js

@@ -236,11 +236,14 @@ export async function loadEntityDoc(ctx, name, sqlString) {
 export async function runQuery(ctx, sql, o = {}) {
   const fmt = o.format || 'Table';
   const isStreaming = fmt === 'Table';
+  // Streaming gets the progress-bearing JSON; raw mode sends the requested format
+  // verbatim as default_format (a real ClickHouse format name from a FORMAT clause
+  // or an implicit EXPLAIN). 'TSV' keeps its with-names-and-types expansion.
   const fmtParam = isStreaming
     ? 'JSONStringsEachRowWithProgress'
     : fmt === 'TSV'
       ? 'TabSeparatedWithNamesAndTypes'
-      : 'JSONCompact';
+      : fmt;
   const url = chUrl(ctx.origin, {
     format: fmtParam,
     // wait_end_of_query buffers the whole response server-side so the HTTP

src/ui/app.js

@@ -11,7 +11,7 @@ import {
 } from '../state.js';
 import { saveJSON, saveStr } from '../core/storage.js';
 import { decodeJwtPayload, isTokenExpired } from '../core/jwt.js';
-import { sqlString, inferQueryName, shortVersion, userShortName, withStatementBreak, detectSqlFormat } from '../core/format.js';
+import { sqlString, inferQueryName, shortVersion, userShortName, withStatementBreak, detectSqlFormat, isExplain } from '../core/format.js';
 import { resolveTarget } from '../core/target.js';
 import { toTSV, toCSV } from '../core/export.js';
 import { newResult, applyStreamLine } from '../core/stream.js';
@@ -378,9 +378,10 @@ export function createApp(env = {}) {
     await ensureConfig();
     if (!(await getToken())) { chCtx.onSignedOut(); return; }
 
-    // Default to structured streaming (Table); if the user ends their SQL with a
-    // FORMAT clause, run raw and show ClickHouse's response verbatim (#format).
-    const fmt = detectSqlFormat(tab.sql) || 'Table';
+    // Default to structured streaming (Table); an explicit FORMAT clause runs raw
+    // and shows ClickHouse's response verbatim, and so does EXPLAIN (its plan text
+    // reads far better raw than as a one-column table) unless a FORMAT was given.
+    const fmt = detectSqlFormat(tab.sql) || (isExplain(tab.sql) ? 'TabSeparated' : 'Table');
     const t0 = now();
     tab.result = newResult(fmt);
     app.state.resultSort = { col: null, dir: 'asc' };

tests/unit/app.test.js

@@ -349,6 +349,23 @@ describe('query run', () => {
     expect(app.activeTab().result.rawText).toBe('a\tb');
     expect(app.activeTab().result.rawFormat).toBe('TabSeparatedWithNames'); // label for the raw tab
   });
+  it('runs EXPLAIN raw (plan text) when no explicit FORMAT is given', async () => {
+    const { app } = appForRun([
+      [(u, sql) => /EXPLAIN/.test(sql), resp({ text: 'Expression\n  ReadFromTable' })],
+    ]);
+    app.activeTab().sql = 'EXPLAIN SELECT 1';
+    await app.actions.run();
+    expect(app.activeTab().result.rawText).toBe('Expression\n  ReadFromTable');
+    expect(app.activeTab().result.rawFormat).toBe('TabSeparated'); // plain TS → no header noise
+  });
+  it('an explicit FORMAT on an EXPLAIN still wins over the raw default', async () => {
+    const { app } = appForRun([
+      [(u, sql) => /EXPLAIN/.test(sql), resp({ text: '{"plan":[]}' })],
+    ]);
+    app.activeTab().sql = 'EXPLAIN SELECT 1 FORMAT JSON';
+    await app.actions.run();
+    expect(app.activeTab().result.rawFormat).toBe('JSON'); // FORMAT clause, not the EXPLAIN default
+  });
 });
 
 describe('formatQuery', () => {

tests/unit/format.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import {
-  clamp, formatRows, formatBytes, timeAgo, sqlString, inferQueryName, isNumericType, shortVersion, userShortName, withStatementBreak, detectSqlFormat,
+  clamp, formatRows, formatBytes, timeAgo, sqlString, inferQueryName, isNumericType, shortVersion, userShortName, withStatementBreak, detectSqlFormat, isExplain,
 } from '../../src/core/format.js';
 
 describe('clamp', () => {
@@ -101,6 +101,20 @@ describe('detectSqlFormat', () => {
   });
 });
 
+describe('isExplain', () => {
+  it('detects a leading EXPLAIN (any variant), ignoring leading whitespace/case', () => {
+    expect(isExplain('EXPLAIN SELECT 1')).toBe(true);
+    expect(isExplain('  explain pipeline SELECT 1')).toBe(true);
+    expect(isExplain('EXPLAIN AST SELECT 1')).toBe(true);
+  });
+  it('is false for non-EXPLAIN statements', () => {
+    expect(isExplain('SELECT 1')).toBe(false);
+    expect(isExplain('SELECT explain FROM t')).toBe(false); // EXPLAIN not the leading keyword
+    expect(isExplain('')).toBe(false);
+    expect(isExplain(null)).toBe(false);
+  });
+});
+
 describe('inferQueryName', () => {
   it('uses FROM table when present', () => {
     expect(inferQueryName('SELECT * FROM system.tables')).toBe('Query · system.tables');