Failed to analyze SQL complexity using EXPLAIN, fallback to

Error message

Failed to analyze SQL complexity using EXPLAIN, fallback to default true. e: {}

What it means

ClickhouseProxy.isComplexSql runs an EXPLAIN (ESTIMATE) query against ClickHouse to decide whether the SQL is 'complex' (needing special handling). Any exception during this analysis logs this warning with the exception message and falls back to returning true (treated as complex).

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/util/ClickhouseProxy.java:537

                    if (explainLine.contains("JOIN")
                            || explainLine.contains("UNION")
                            || explainLine.contains("GROUP BY")
                            || explainLine.contains("LIMIT")
                            || explainLine.contains("Sorting")
                            || explainLine.contains("Aggregating")
                            || explainLine.contains("Merging")
                            || explainLine.contains("subquery")) {

                        log.info("Complex SQL detected, explain line: {}", explainLine);

                        return true;
                    }
                }
                return false;
            }
        } catch (Exception e) {
            log.warn(
                    "Failed to analyze SQL complexity using EXPLAIN, fallback to default true. e: {}",
                    e.getMessage());
            return true;
        }
    }

    public void close() {
        if (this.client != null) {
            this.client.close();
        }
        shardToDataSource.values().forEach(ClickHouseClient::close);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Check the logged exception message; upgrade ClickHouse or the connector if EXPLAIN ESTIMATE is unsupported.
Grant the user permission to run EXPLAIN queries.
Accept the safe fallback (treated as complex) if the resulting behavior is acceptable.

Defensive patterns

Strategy: fallback

Validate before calling

// pre-flight check
try (Statement st = conn.createStatement()) {
    st.execute("EXPLAIN ESTIMATE " + sql);
}

Try / catch

try {
    boolean complex = proxy.isComplexSql(sql);
} catch (Exception e) {
    // connector falls back to true (complex); acceptable default
}

Prevention

Verify EXPLAIN ESTIMATE support on your ClickHouse version
Grant EXPLAIN privileges to the query user
Run the pre-flight EXPLAIN check during deployment

When it happens

Trigger: isComplexSql executes EXPLAIN on the connection and an Exception is thrown — syntax not supported by the ClickHouse version, connection failure, or permission issues.

Common situations: Older ClickHouse versions lacking EXPLAIN ESTIMATE; read-only user without EXPLAIN privileges; SQL dialect differences after version upgrades.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/4293814e9cc14c49. Report an issue: GitHub.