Documentation Review Process

When reviewing troubleshooting error pages, follow this systematic approach:

You'll be given a single page to review, along with some suggestions that you should take with a grain of salt. Follow carefully.

  1. Identify Restricted Commands: Look for ClickHouse commands that aren't available in Tinybird:

    • DESCRIBE, SHOW TABLES, SHOW COLUMNS, SHOW FUNCTIONS
    • Replace with system table queries: system.columns, system.tables, system.functions

  2. Validate Error Scenarios: Actually run, and test all code examples to ensure they produce the expected errors. A dummy clickhouse server instance is being ran at port 9000 for this case, connect to it doing so:

    clickhouse-client --port 9000 --database docs -q "the query goes here"
    • Create test tables and data
    • Run each example to verify error codes and messages
    • Check if examples actually cause the documented error type

  3. Update System Table References: Replace all restricted commands with Tinybird-compatible alternatives:

    • DESCRIBE table → SELECT * FROM system.columns WHERE table = 'table_name'
    • SHOW TABLES → SELECT * FROM system.tables
    • SHOW FUNCTIONS LIKE '%pattern%' → SELECT * FROM system.functions WHERE name LIKE '%pattern%'

  4. Test Error Accuracy: Verify that examples actually throw the documented error type:

    • Table existence errors typically throw UNKNOWN_TABLE (code 60), not UNKNOWN_IDENTIFIER
    • Function/column errors throw UNKNOWN_IDENTIFIER (code 47)
    • Check for helpful error suggestions from ClickHouse

  5. Apply Corrections: Update documentation based on actual ClickHouse behavior to ensure users get accurate, actionable guidance.

If you detect a code example produces an error code that belongs to another error-specific page, move it there.

This process ensures troubleshooting documentation reflects real ClickHouse behavior and provides correct error resolution steps.

If you cannot reproduce an error, add the page name to __cannot-reprodue.md.

Updated