apache/seatunnel · error · ClickhouseConnectorException

Failed to read data from sql %s, shard: %s, splitId %s, mess

Error message

Failed to read data from sql %s, shard: %s, splitId %s, message: %s

What it means

Thrown by ClickhouseValueReader.sqlBatchStrategyRead() when the SQL-based batch read fails with any Exception. The connector wraps the root cause in a ClickhouseConnectorException with QUERY_DATA_ERROR, including the executed query, shard node, split id, and underlying message. It indicates the per-batch SQL query (often a paged query using the last ordering key) could not be executed or its results consumed.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/source/ClickhouseValueReader.java:197

                            query, clickhouseSourceTable.getTablePath(), rowTypeInfo);

            String sortingKey = clickhouseSourceTable.getClickhouseTable().getSortingKey();

            if (rowBatch.isEmpty()) {
                return false;
            }
            SeaTunnelRow lastRow = rowBatch.get(rowBatch.size() - 1);

            sqlLastOrderingKeyValues = extractOrderingKeyValuesFromRow(lastRow, sortingKey);

            log.debug(
                    "lastRow: {}, extract ordering key values from row: {}",
                    lastRow,
                    sqlLastOrderingKeyValues);

            return !rowBatch.isEmpty();
        } catch (Exception e) {
            throw new ClickhouseConnectorException(
                    ClickhouseConnectorErrorCode.QUERY_DATA_ERROR,
                    String.format(
                            "Failed to read data from sql %s, shard: %s, splitId %s, message: %s",
                            query,
                            clickhouseSourceSplit.getShard().getNode(),
                            clickhouseSourceSplit.getSplitId(),
                            e.getMessage()),
                    e);
        }
    }

    public void close() {
        if (proxy != null) {
            proxy.close();
        }
        if (streamValueReader != null) {
            streamValueReader.close();
        }

View on GitHub (pinned to cf67b549a7)

Solutions

Copy the query from the error message and run it manually against the shard node to see the real server error
Verify the ordering key columns still exist and match the configured ordering key in the source config
Retry the job with checkpointing enabled to recover from transient shard/network failures
Reduce batch size / add query timeout settings if the failure is timeout-related on large reads

Example fix

// before
select * from my_table;
// after
select col1, col2 from my_table; -- explicit columns matching schema and ordering key
// validate manually: clickhouse-client --host <shard> -q "<query from error message>"

Defensive patterns

Strategy: retry

Validate before calling

// Validate the split query against the shard before the job
try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
    c.createStatement().executeQuery("SELECT 1 FROM " + table + " LIMIT 1");
    // also confirm ordering key columns exist:
    c.createStatement().executeQuery(
        "SELECT name FROM system.columns WHERE database='" + db + "' AND table='" + table + "'");
}

Try / catch

try {
    hasMore = reader.hasNext();
} catch (ClickhouseConnectorException e) {
    if (e.getErrorCode() == ClickhouseConnectorErrorCode.QUERY_DATA_ERROR
        && e.getMessage().startsWith("Failed to read data from sql")) {
        // log full query from message; retry split after backoff or fail job with context
    }
    throw e;
}

Prevention

Validate schema and ordering-key columns exist before the run; lock schema during the job
Test the generated SQL manually against the target shard
Enable checkpointing for automatic split re-reads after transient failures
Keep batch sizes moderate to avoid timeouts on wide tables

When it happens

Trigger: sqlBatchStrategyRead() runs the split's query (with ORDER BY / WHERE paging on ordering keys) and the JDBC execution or row/ordering-key extraction throws: bad SQL, connection drop, type mapping failure, or missing ordering-key column in the result.

Common situations: Query references a column dropped/renamed by a schema change; shard unavailable mid-job; ORDER BY key mismatch after table engine change; timeouts on very large batches; ClickHouse version differences in SQL support.

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/ad66a0dd6a770a07. Report an issue: GitHub.