Version-exact ClickHouse reference documentation in Workbench

[BorisTyshkevich]

Summary

Provide version-exact ClickHouse reference documentation inside SQL Browser, sourced from the connected server rather than the public website.

Implementation is split into three sequenced child issues:

1. Docs Phase 1: rich function reference in CM6 hover and docs pane #313 — rich function and aggregate-function docs in CM6 hover and a non-modal docs pane;
2. Docs Phase 2: structured reference for formats, engines, and data types #314 — structured docs for formats, table/database engines, and data types;
3. Docs Phase 3: broad system.documentation reference and safe Markdown rendering #315 — broad system.documentation coverage and safe Markdown rendering.

Version and capability policy

Version and capability checks serve different purposes and must not be conflated.

Structured sources: capability is authoritative

system.functions, system.formats, engine tables, and data-type tables exist across different ClickHouse releases and expose different documentation columns depending on version, build, registration, and privileges.

For #313 and #314:

• do not use a fixed serverVersion >= 26.6 gate;
• inspect actual table and column availability once per connection;
• build queries only from confirmed columns;
• degrade missing optional fields independently;
• use usable structured metadata even on pre-26.6 servers;
• do not assume complete support merely because a server is 26.6+;
• cache denied/missing/incompatible capabilities for the connection;
• keep transient auth/network failures retryable.

system.documentation: version short-circuit plus capability probe

system.documentation is a ClickHouse 26.6 feature.

For #315:

1. When the parsed server version is below 26.6, mark the source unavailable without querying or probing system.documentation.
2. When the version is 26.6 or later, probe the table and all four required columns once per connection.
3. When the version is unavailable or unparsable, perform one silent capability probe.
4. Even on 26.6+, table/column availability remains authoritative because privileges and custom builds may differ.

A version check is therefore a negative optimization, not proof of capability.

Reconnect/invalidate clears all version-derived and probed capability state. Tests must cover pre-26.6 no-request behavior, 26.6+ probing, unknown-version probing, partial structured schemas, denied access, and custom-build differences.

Product goals

• Documentation matches the connected ClickHouse binary and registered features.
• Air-gapped/self-contained deployments remain functional.
• Hover stays compact; depth opens in a persistent reference pane.
• No documentation query runs on the ordinary keystroke path.
• Older servers and denied system.* privileges degrade silently.
• One normalized documentation model serves CM6, completion info, schema actions, and future callers.
• Server text is untrusted and rendered without innerHTML.

Source-of-truth policy

Preferred source order:

1. structured per-kind system tables when supported;
2. system.documentation for breadth, complete Markdown bodies, or structured-source fallback;
3. current built-in/static reference data.

A safely derived latest-doc link may be secondary. SQL Browser must not fetch the public site to populate the pane.

Do not hard-code row counts, entity counts, or a closed server type enum.

Current architecture

Extend the current post-CM6 architecture:

• src/editor/codemirror-adapter.ts owns CM6 completion, info, hover, syntax context, and keymap;
• src/application/schema-catalog-service.ts owns reference lifecycle, lazy docs, capability state, caching, and invalidation;
• src/net/ch-client.ts owns silent system-table queries and row decoding;
• src/core/** remains pure and DOM-free;
• Workbench UI owns the non-modal pane and DOM rendering.

Do not recreate textarea-era editor overlays.

Shared documentation model

interface DocTarget {
  kind: DocKind;
  name: string;
}

type DocLookup<T> =
  | { status: 'found'; value: T }
  | { status: 'missing' }
  | { status: 'unavailable' };

• found: normalized and cacheable;
• missing: successful no-match, cacheable per connection;
• unavailable: unsupported/denied/incompatible capability, cacheable per connection;
• transient auth/network failure: retryable, not durably cached.

Cache keys include kind:name. Every request is tied to a connection generation so stale responses cannot repopulate caches or replace pane content after reconnect.

Shared loading rules

• Probe each capability at most once per connection, subject to the version policy above.
• Use system.columns or one silent optimistic probe.
• Missing tables/columns and denied access never surface query errors.
• Deduplicate concurrent lookups.
• Keep connection-time bulk reference loading small.
• Load full bodies/examples lazily.
• Never bulk-load every system.documentation body.
• Apply row and byte limits.
• Clear capability, result, pending, and pane-navigation state on connection change.

CM6 interaction

Compact hover and completion info

Show signature/kind, one-line summary, optional introduced version, optional alias notice, and accessible Open reference action. Continue syntax-tree suppression inside comments, strings, and quoted identifiers.

Hover and completion info share helpers. Async updates verify that tooltip/editor DOM is still live.

Keyboard

F1 opens documentation for the strongest target at selection.main.head.

• prevent browser default only when handled;
• return unhandled when no target resolves;
• tooltip, completion, schema actions, and F1 call one openDocEntry(DocTarget) path;
• document F1 in the shortcuts dialog.

Hover is never the sole access path.

Workbench reference pane

Use one persistent non-modal right-side pane:

• no backdrop or focus trap;
• editor remains usable;
• one instance, replacing content for a new target;
• bounded resize;
• labelled complementary region;
• close/Escape and focus restoration;
• distinct loading, missing, unavailable, transient, oversized, and fallback states;
• retry for transient failure;
• session-local navigation history only.

Do not require the schema graph's bottom pane to share this geometry.

Pure context classification

Use a pure src/core/doc-context.ts-style module receiving SQL, caret position, and optional precomputed tokens/syntax. It returns ranked targets and issues no SQL.

• Docs Phase 1: rich function reference in CM6 hover and docs pane #313: functions and aggregate functions;
• Docs Phase 2: structured reference for formats, engines, and data types #314: FORMAT, table/database ENGINE, and strong data-type positions;
• Docs Phase 3: broad system.documentation reference and safe Markdown rendering #315: settings, MergeTree settings, table functions, codecs, aggregate combinators, system tables, and index types.

Strong context wins. Weak identifiers are not guessed. Ambiguous names open disambiguation.

Rendering and safety

Structured fields render directly through DOM construction.

For Markdown:

src/core/doc-markdown.ts
  Markdown -> bounded pure AST

src/ui/doc-markdown-view.ts
  AST -> DOM nodes

Rules:

• no innerHTML or raw HTML;
• no images, scripts, styles, forms, SVG, iframes, media, or executable examples;
• safe https: links only, with noopener noreferrer;
• unsupported constructs remain escaped visible text;
• parser failure falls back to escaped plain text;
• enforce byte/node/nesting/link/code-block limits;
• SQL examples use shared CM6 ClickHouse highlighting;
• copy exact code text;
• no general Markdown runtime dependency.

Structured sources

#313

Use whichever confirmed system.functions columns exist, including optional description, syntax, arguments, parameters, returned value, examples, introduced version, categories, alias, deterministic, and higher-order metadata. Missing fields degrade independently.

#314

Use confirmed fields from system.formats, system.table_engines, system.database_engines, and system.data_type_families. system.formats has no syntax; never query or fabricate it.

#315

On eligible/probed servers, treat system.documentation as exactly:

name
type
description
source

Unknown future type values remain renderable through an unknown normalized kind while preserving the server label.

Schema-surface integration

Phases 2–3 may add explicit engine/type documentation actions. Preserve current expand/select and insertion gestures. Opening docs does not mutate editor text or close schema views.

Compatibility

• Pre-26.6 servers may still provide structured metadata and should use it.
• Parsed pre-26.6 servers never receive a system.documentation request.
• Missing rich columns degrade by field.
• Denied access produces no toast/banner or probe storm.
• User-defined/undocumented entities may show minimal or missing states.
• Unknown future kinds remain readable.
• The single-file artifact remains intact.

Child issues

#313 — Phase 1

Capability-gated function docs, target-aware catalog API, reconnect-safe cache, CM6 hover/info, F1, non-modal pane, aliases, examples, and fallback.

#314 — Phase 2

Capability-gated formats/engines/types, SQL-context expansion, schema actions, related navigation, and no nonexistent format syntax query.

#315 — Phase 3

26.6 lower-bound short-circuit, 26.6+/unknown-version capability probing, broad entity kinds, bounded Markdown, disambiguation, related navigation, and parser robustness tests.

Phases land in order.

Umbrella acceptance criteria

• Docs Phase 1: rich function reference in CM6 hover and docs pane #313, Docs Phase 2: structured reference for formats, engines, and data types #314, and Docs Phase 3: broad system.documentation reference and safe Markdown rendering #315 are complete.
• Structured sources are gated by actual capability rather than a blanket 26.6 check.
• Usable pre-26.6 structured metadata is consumed.
• Parsed pre-26.6 servers make zero system.documentation requests.
• 26.6+ and unknown-version connections still capability-probe system.documentation once.
• CM6 hover remains compact and the pane provides depth.
• F1 and explicit UI actions provide keyboard access.
• No documentation SQL runs on ordinary keystrokes.
• Capability, caching, failure, and reconnect semantics are consistent.
• Structured and Markdown content render safely.
• Older/denied/custom servers degrade silently.
• Unknown future kinds remain readable.
• Single-file build, unit, integration, CM6, fuzz/property, and browser accessibility gates pass.

Non-goals

• fetching clickhouse.com as source of truth;
• tutorials, guides, or arbitrary website search;
• replacing CM6, autocomplete, or schema architecture;
• per-keystroke documentation queries;
• large hover tooltips;
• documentation editing;
• persisted bodies or pane history;
• raw HTML, images, media, or executable examples;
• one universal geometry component for all detail surfaces.

[BorisTyshkevich]

This issue spans two layers, sequenced after CM6 (#21):

• Hover (compact signature/summary/since badge) → a CM6 hover extension in the editor.
• Right-side docs pane → as the issue says, reuse the side-drawer/detail-pane pattern. Extract a shared Drawer primitive here (cell detail + schema detail + this docs pane = its 3rd consumer) with focus/Esc/backdrop/ARIA, so the three stop being separate overlay systems.