feat: add helpful notes when tables are missing due to clickhouse misconfiguration

app/[host]/[query]/merges/merge-performance.ts

@@ -1,9 +1,11 @@
+import { PART_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const mergePerformanceConfig: QueryConfig = {
   name: 'merge-performance',
   description: 'Merge performance over day, avg duration, avg rows read',
+  docs: PART_LOG,
   sql: `
       SELECT
           event_date,

app/[host]/[query]/more/backups.ts

@@ -1,10 +1,12 @@
+import { BACKUP_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const backupsConfig: QueryConfig = {
   name: 'backups',
   description: `To restore a backup:
       RESTORE TABLE data_lake.events AS data_lake.events_restore FROM Disk('s3_backup', 'data_lake.events_20231212')`,
+  docs: BACKUP_LOG,
   sql: `
       SELECT *,
         formatReadableSize(total_size) as readable_total_size,

app/[host]/[query]/more/count-across-replicas.ts

@@ -1,9 +1,11 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const countAcrossReplicasConfig: QueryConfig = {
   name: 'count-across-replicas',
   description: 'All table count across replicas',
+  docs: QUERY_LOG,
   sql: `
       SELECT
           hostName(),

app/[host]/[query]/more/top-usage-columns.ts

@@ -1,9 +1,11 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const topUsageColumnsConfig: QueryConfig = {
   name: 'top-usage-columns',
   description: 'Most usage columns of table based on system.query_log',
+  docs: QUERY_LOG,
   sql: `
       SELECT
           columns as column,

app/[host]/[query]/more/top-usage-tables.ts

@@ -1,10 +1,12 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const topUsageTablesConfig: QueryConfig = {
   name: 'top-usage-tables',
   description:
     'Most usage tables, ignore system tables, based on system.query_log (top 50). Click on table name to see top usage columns.',
+  docs: QUERY_LOG,
   sql: `
       SELECT
           tables as table,

app/[host]/[query]/more/zookeeper.ts

@@ -1,10 +1,12 @@
+import { ZOOKEEPER } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const zookeeperConfig: QueryConfig = {
   name: 'zookeeper',
   description:
     'Exposes data from the Keeper cluster defined in the config. https://clickhouse.com/docs/en/operations/system-tables/zookeeper',
+  docs: ZOOKEEPER,
   sql: `
       SELECT
           replaceOne(format('{}/{}', path, name), '//', '/') AS _path,

app/[host]/[query]/queries/expensive-queries-by-memory.ts

@@ -1,9 +1,11 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const expensiveQueriesByMemoryConfig: QueryConfig = {
   name: 'expensive-queries-by-memory',
   description: 'Most expensive queries by memory finished over last 24 hours',
+  docs: QUERY_LOG,
   sql: `
       SELECT
           query,

app/[host]/[query]/queries/expensive-queries.ts

@@ -1,9 +1,11 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const expensiveQueriesConfig: QueryConfig = {
   name: 'expensive-queries',
   description: 'Most expensive queries finished over last 24 hours',
+  docs: QUERY_LOG,
   sql: `
     WITH base_metrics AS (
         SELECT

app/[host]/[query]/queries/failed-queries.ts

@@ -1,9 +1,11 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const failedQueriesConfig: QueryConfig = {
   name: 'failed-queries',
   description: "type IN ['ExceptionBeforeStart', 'ExceptionWhileProcessing']",
+  docs: QUERY_LOG,
   sql: `
     SELECT
         type,

app/[host]/[query]/queries/history-queries.ts

@@ -1,10 +1,12 @@
+import { QUERY_LOG } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const historyQueriesConfig: QueryConfig = {
   name: 'history-queries',
   description:
     'Contains information about executed queries: start time, duration of processing, error messages',
+  docs: QUERY_LOG,
   sql: `
       SELECT
           type,

app/[host]/[query]/queries/query-cache.ts

@@ -1,8 +1,12 @@
+import { QUERY_CACHE } from '@/lib/table-notes'
 import { ColumnFormat } from '@/types/column-format'
 import { type QueryConfig } from '@/types/query-config'
 
 export const queryCacheConfig: QueryConfig = {
   name: 'query-cache',
+  description:
+    'https://clickhouse.com/blog/introduction-to-the-clickhouse-query-cache-and-design',
+  docs: QUERY_CACHE,
   sql: `
       SELECT
           query,

app/[host]/[query]/tables/replicas.ts

@@ -5,8 +5,7 @@ export const replicasConfig: QueryConfig = {
   name: 'replicas',
   description: `Contains information and status for replicated tables residing on the local server`,
   sql: `
-      SELECT *,
-             (database || '.' || table) as database_table
+      SELECT *, (database || '.' || table) as database_table
       FROM system.replicas
       ORDER BY database, table
     `,

components/error-alert.tsx

@@ -11,10 +11,12 @@ import {
 } from '@/components/ui/accordion'
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
 import { Button } from '@/components/ui/button'
+import { NotebookPenIcon } from 'lucide-react'
 
 interface ErrorAlertProps {
   title?: string
   message?: string | React.ReactNode | React.ReactNode[]
+  docs?: string | React.ReactNode | React.ReactNode[]
   query?: string
   reset?: () => void
   className?: string
@@ -23,6 +25,7 @@ interface ErrorAlertProps {
 export function ErrorAlert({
   title = 'Something went wrong!',
   message = 'Checking console for more details.',
+  docs,
   query,
   reset,
   className,
@@ -76,12 +79,24 @@ export function ErrorAlert({
     </Accordion>
   )
 
+  const renderDocs = (docs: string | React.ReactNode) => (
+    <>
+      {docs ? (
+        <div className="flex items-center gap-2">
+          <NotebookPenIcon className="w-4 flex-none" />
+          {docs}
+        </div>
+      ) : null}
+    </>
+  )
+
   return (
     <Alert className={className}>
       <AlertTitle className="text-lg">{title}</AlertTitle>
       <AlertDescription>
         {renderContent(message)}
-        {query && renderAccordion('View Full Query Details', query)}
+        {Boolean(query) && renderAccordion('View Full Query Details', query)}
+        {Boolean(docs) && renderDocs(docs)}
         {reset && (
           <Button variant="outline" onClick={() => reset()}>
             Try again {countdown >= 0 && `(${countdown}s)`}

components/table.tsx

@@ -65,6 +65,7 @@ export async function Table({
         title="ClickHouse Query Error"
         message={`${error}`}
         query={queryConfig.sql}
+        docs={queryConfig.docs}
       />
     )
   }

docs/pages/getting-started/_meta.ts

@@ -1,4 +1,4 @@
 export default {
   'clickhouse-requirements': 'Clickhouse User Roles and Settings',
-  'clickhouse-enable-system-tables': 'Clickhouse Enable System Tables'
+  'clickhouse-enable-system-tables': 'Clickhouse Enable System Tables',
 }

docs/pages/getting-started/clickhouse-enable-system-tables.mdx

@@ -69,4 +69,4 @@ Create `/etc/clickhouse-server/config.d/enable_system_log_tables.xml` with the f
   </error_log>
 
 </clickhouse>
-```
+```

lib/table-notes.ts

@@ -0,0 +1,5 @@
+export const QUERY_LOG = `The required table 'query_log' may be missing. Please follow the documentation at https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#query-log and https://clickhouse.com/docs/en/operations/system-tables/query_log to ensure the necessary table is available.`
+export const QUERY_CACHE = `The required table 'query_cache' may be missing. Please follow the documentation at https://clickhouse.com/docs/en/operations/query-cache to ensure the necessary table is available.`
+export const PART_LOG = `The required table 'part_log' may be missing. Please follow the documentation at https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#part-log to ensure the necessary table is available.`
+export const BACKUP_LOG = `The required table 'backup_log' may be missing. Please follow the documentation at https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#backup_log to ensure the necessary table is available. Make sure you have at least one backup to have this table available.`
+export const ZOOKEEPER = `Make sure that ZooKeeper or clickhouse-keeper has been configured. Please follow the documentation at https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#server-settings_zookeeper`

types/query-config.ts

@@ -81,6 +81,10 @@ export interface QueryConfig {
    * ClickHouse settings to be used for this query
    */
   clickhouseSettings?: ClickHouseSettings
+  /**
+   * The documents or url to be used when query is errors. e.g. log table missing due to cluster configuration.
+   */
+  docs?: string
 }
 
 export type QueryConfigNoName = PartialBy<QueryConfig, 'name'>