Merge pull request #407 from duyet/feat/table-not-found-message

duyet · web-flow · commit 3d26aa577731 · 2024-11-13T17:39:31.000+07:00
feat: add helpful notes when tables are missing due to clickhouse misconfiguration
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -5,6 +5,9 @@ on:
     branches:
       - main
   pull_request:
+    branches:
+      - main
+      - 'docs/**'
   workflow_dispatch:
 
 permissions:
diff --git a/app/[host]/[query]/merges/merge-performance.ts b/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,
diff --git a/app/[host]/[query]/more/backups.ts b/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,
diff --git a/app/[host]/[query]/more/count-across-replicas.ts b/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(),
diff --git a/app/[host]/[query]/more/top-usage-columns.ts b/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,
diff --git a/app/[host]/[query]/more/top-usage-tables.ts b/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,
diff --git a/app/[host]/[query]/more/zookeeper.ts b/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,
diff --git a/app/[host]/[query]/queries/expensive-queries-by-memory.ts b/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,
diff --git a/app/[host]/[query]/queries/expensive-queries.ts b/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
diff --git a/app/[host]/[query]/queries/failed-queries.ts b/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,
diff --git a/app/[host]/[query]/queries/history-queries.ts b/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,
diff --git a/app/[host]/[query]/queries/query-cache.ts b/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,
diff --git a/app/[host]/[query]/tables/replicas.ts b/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
     `,
diff --git a/components/error-alert.cy.tsx b/components/error-alert.cy.tsx
@@ -56,33 +56,84 @@ describe('<ErrorAlert />', () => {
     cy.contains('This is the alert message').should('be.visible')
   })
 
-  it('renders with debug query', () => {
-    cy.mount(
-      <ErrorAlert
-        title="Something went wrong"
-        message={'Checking query below'}
-        query="SELECT 1"
-      />
-    )
+  describe('test `query` prop', () => {
+    it('renders with debug query', () => {
+      cy.mount(
+        <ErrorAlert
+          title="Something went wrong"
+          message={'Checking query below'}
+          query="SELECT 1"
+        />
+      )
+
+      cy.get('button[role="open-query"]').should('be.visible')
+      cy.get('button[role="open-query"]').click()
+      cy.contains('SELECT 1').should('be.visible')
+    })
 
-    cy.get('button[role="open-query"]').should('be.visible')
-    cy.get('button[role="open-query"]').click()
-    cy.contains('SELECT 1').should('be.visible')
+    it('renders with debug query and JSX message', () => {
+      cy.mount(
+        <ErrorAlert
+          title="Something went wrong"
+          message={<div className="bg-green-300 p-3">Green message</div>}
+          query="SELECT 1"
+        />
+      )
+      cy.contains('Something went wrong').should('be.visible')
+      cy.get('div').should('have.class', 'bg-green-300')
+
+      cy.get('button[role="open-query"]').should('be.visible')
+      cy.get('button[role="open-query"]').click()
+      cy.contains('SELECT 1').should('be.visible')
+    })
   })
 
-  it('renders with debug query and JSX message', () => {
-    cy.mount(
-      <ErrorAlert
-        title="Something went wrong"
-        message={<div className="bg-green-300 p-3">Green message</div>}
-        query="SELECT 1"
-      />
-    )
-    cy.contains('Something went wrong').should('be.visible')
-    cy.get('div').should('have.class', 'bg-green-300')
+  describe('test `docs` prop', () => {
+    it('renders with docs string', () => {
+      cy.mount(
+        <ErrorAlert
+          title="Something went wrong"
+          message="Error message"
+          docs="Check the documentation here"
+        />
+      )
+      cy.get('svg').should('be.visible') // NotebookPenIcon
+      cy.contains('Check the documentation here').should('be.visible')
+    })
+
+    it('renders with docs as JSX', () => {
+      cy.mount(
+        <ErrorAlert
+          title="Something went wrong"
+          message="Error message"
+          docs={
+            <a href="#" className="text-blue-500">
+              Documentation link
+            </a>
+          }
+        />
+      )
+      cy.get('svg').should('be.visible') // NotebookPenIcon
+      cy.get('a')
+        .should('have.class', 'text-blue-500')
+        .and('contain', 'Documentation link')
+    })
 
-    cy.get('button[role="open-query"]').should('be.visible')
-    cy.get('button[role="open-query"]').click()
-    cy.contains('SELECT 1').should('be.visible')
+    it('renders with all props combined', () => {
+      cy.mount(
+        <ErrorAlert
+          title="Error Title"
+          message="Error message"
+          query="SELECT * FROM users"
+          docs={<span className="docs-link">View docs</span>}
+        />
+      )
+      cy.contains('Error Title').should('be.visible')
+      cy.contains('Error message').should('be.visible')
+      cy.get('button[role="open-query"]').click()
+      cy.contains('SELECT * FROM users').should('be.visible')
+      cy.get('svg').should('be.visible') // NotebookPenIcon
+      cy.get('.docs-link').should('contain', 'View docs')
+    })
   })
 })
diff --git a/components/error-alert.tsx b/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)`}
diff --git a/components/table.tsx b/components/table.tsx
@@ -65,6 +65,7 @@ export async function Table({
         title="ClickHouse Query Error"
         message={`${error}`}
         query={queryConfig.sql}
+        docs={queryConfig.docs}
       />
     )
   }
diff --git a/docs/pages/getting-started/_meta.ts b/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',
 }
diff --git a/docs/pages/getting-started/clickhouse-enable-system-tables.mdx b/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>
-```
+```
diff --git a/lib/table-notes.ts b/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`
diff --git a/types/query-config.ts b/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'>
