{"record":{"id":"e79c8e4e745736fe","repo":"apache/seatunnel","slug":"query-table-not-support-non-merge-tree-table","errorCode":"QUERY_TABLE_NOT_SUPPORT_NON_MERGE_TREE_TABLE","errorMessage":"Query table mode not support non-MergeTree local table. Please specify sql parameter in configuration","messagePattern":"Query table mode not support non-MergeTree local table\\. Please specify sql parameter in configuration","errorType":"error_code","errorClass":"ClickhouseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/source/split/ClickhouseSourceSplitEnumerator.java","lineNumber":261,"sourceCode":"\n                clusterShardList =\n                        proxy.getClusterShardList(\n                                proxy.getClickhouseConnection(),\n                                distributedEngine.getClusterName(),\n                                distributedEngine.getDatabase(),\n                                nodes.get(0).getPort(),\n                                clickhouseSourceConfig.getUsername(),\n                                clickhouseSourceConfig.getPassword(),\n                                nodes.get(0).getOptions());\n            } else {\n                // if input is local table, generate shard list based on the input nodes\n                clusterShardList = buildClusterShardFromNodes(nodes);\n                localTableEngine = clickhouseTable.getEngine();\n            }\n\n            if (StringUtils.isEmpty(clickhouseSourceTable.getOriginQuery())\n                    && !localTableEngine.contains(\"MergeTree\")) {\n                throw new ClickhouseConnectorException(\n                        ClickhouseConnectorErrorCode.QUERY_TABLE_NOT_SUPPORT_NON_MERGE_TREE_TABLE,\n                        \"Query table mode not support non-MergeTree local table. Please specify sql parameter in configuration\");\n            }\n\n            return clusterShardList;\n        }\n    }\n\n    private List<Shard> buildClusterShardFromNodes(List<ClickHouseNode> nodes) {\n        List<Shard> shards = new ArrayList<>();\n        IntStream.range(0, nodes.size())\n                .forEach(\n                        i -> {\n                            ClickHouseNode node = nodes.get(i);\n                            Shard shard = new Shard(i, 1, node);\n                            shards.add(shard);\n                        });\n","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/source/split/ClickhouseSourceSplitEnumerator.java#L243-L279","documentation":"In query-table mode with no explicit sql, ClickhouseSourceSplitEnumerator.getClusterShardList() requires the local (non-distributed) table engine to be a MergeTree family engine so it can derive shard/parallel read ranges. Non-MergeTree local tables (e.g. Log, Memory, external engines) cannot be split this way, so the connector throws QUERY_TABLE_NOT_SUPPORT_NON_MERGE_TREE_TABLE.","triggerScenarios":"clickhouse source config has no `sql` option, table not distributed (or distributed whose local table engine string doesn't contain \"MergeTree\"), and localTableEngine.contains(\"MergeTree\") is false at ClickhouseSourceSplitEnumerator.java:261.","commonSituations":"Pointing the connector at a Log/Memory/Kafka-engine table; Distributed table whose local table is non-MergeTree; typo'd table name resolving to an unexpected table; older ClickHouse engine naming (e.g. 'ReplicatedMergeTree' works, but 'StripeLog' doesn't).","solutions":["Set the `sql` option in the ClickHouse source config to supply your own query, bypassing MergeTree-based split enumeration.","Use a MergeTree-family local table (or change the underlying table engine) if table-mode reading is required.","Verify the table/database names resolve to the intended MergeTree table.","If the table is Distributed, confirm its local table (system.tables.engine for the inner table) is MergeTree family."],"exampleFix":"// before: config without sql\nsource {\n  Clickhouse {\n    url = \"jdbc:clickhouse://localhost:8123\"\n    database = \"default\"\n    table = \"my_log_table\"\n  }\n}\n// after: provide sql explicitly\nsource {\n  Clickhouse {\n    url = \"jdbc:clickhouse://localhost:8123\"\n    sql = \"SELECT * FROM default.my_log_table\"\n  }\n}","handlingStrategy":"validation","validationCode":"// Before submitting, check local table engine\nSELECT engine FROM system.tables\nWHERE database = 'default' AND name = 'my_table';\n// must contain 'MergeTree' or config must define `sql`","typeGuard":null,"tryCatchPattern":"try {\n  runJob(config);\n} catch (ClickhouseConnectorException e) {\n  if (e.getSeaTunnelErrorCode() == ClickhouseConnectorErrorCode.QUERY_TABLE_NOT_SUPPORT_NON_MERGE_TREE_TABLE) {\n    // resubmit with `sql` option set\n  } else throw e;\n}","preventionTips":["Always provide `sql` in table mode unless the table is MergeTree family.","Check engine via system.tables before configuring table mode.","Remember Distributed tables depend on their local table's engine, not their own.","Keep table names exact; wrong names can resolve to non-MergeTree tables."],"tags":["clickhouse","mergetree","table-engine","configuration"],"backgroundTag":"unsupported-config-value","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}