{"record":{"id":"75755f00a1b80154","repo":"apache/seatunnel","slug":"currently-only-support-one-split-key","errorCode":null,"errorMessage":"Currently, only support one split key","messagePattern":"Currently, only support one split key","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/source/ChunkSplitter.java","lineNumber":120,"sourceCode":"        long start = System.currentTimeMillis();\n\n        // When concurrent read is disabled, skip all split analysis and return a single\n        // full-table split. This avoids expensive MIN/MAX scans on tables without proper indexes.\n        if (!config.isEnableConcurrentRead()) {\n            log.info(\n                    \"Concurrent read is disabled for table {}, using single split.\",\n                    table.getTablePath());\n            return Collections.singletonList(createSingleSplit(table));\n        }\n\n        Collection<JdbcSourceSplit> splits;\n        Optional<SeaTunnelRowType> splitKeyOptional = findSplitKey(table);\n        if (!splitKeyOptional.isPresent()) {\n            JdbcSourceSplit split = createSingleSplit(table);\n            splits = Collections.singletonList(split);\n        } else {\n            if (splitKeyOptional.get().getTotalFields() != 1) {\n                throw new UnsupportedOperationException(\"Currently, only support one split key\");\n            }\n            splits = createSplits(table, splitKeyOptional.get());\n        }\n\n        long end = System.currentTimeMillis();\n        log.info(\n                \"Split table {} into {} chunks, time cost: {}ms.\",\n                table.getTablePath(),\n                splits.size(),\n                end - start);\n        return splits;\n    }\n\n    protected abstract Collection<JdbcSourceSplit> createSplits(\n            JdbcSourceTable table, SeaTunnelRowType splitKeyType) throws SQLException, Exception;\n\n    public PreparedStatement generateSplitStatement(JdbcSourceSplit split, TableSchema schema)\n            throws SQLException {","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/source/ChunkSplitter.java#L102-L138","documentation":"ChunkSplitter.generateSplits determines the split key for a table. If a split key is found but spans more than one column (totalFields != 1), it throws UnsupportedOperationException because the range-splitting algorithm only supports single-column keys. Multi-column keys fall outside the supported split strategy.","triggerScenarios":"generateSplits is invoked during source split enumeration on a table whose detected split key (e.g. primary key) is a composite of multiple columns.","commonSituations":"Tables with composite primary keys (two or more columns) used as source; connector auto-picks the PK as split key; users assuming multi-column key splitting is supported.","solutions":["Drop or redefine the split_key config to a single column (numeric or supported type).","If no single-column key exists, remove the split key so the source reads with a single split (createSingleSplit path).","Restructure the table to have a single-column surrogate key for parallel reading."],"exampleFix":"// before\nsource {\n  Jdbc {\n    split_key = \"order_id,customer_id\"\n  }\n}\n// after\nsource {\n  Jdbc {\n    split_key = \"order_id\"\n  }\n}","handlingStrategy":"validation","validationCode":"if (splitKey != null && splitKey.split(\",\").length > 1) {\n  throw new IllegalArgumentException(\"only a single-column split key is supported\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  generateSplits(table);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"only support one split key\")) {\n    // fall back to single-split read or select a single-column key\n  }\n}","preventionTips":["Configure a single-column split key explicitly","Avoid composite-PK tables for parallel JDBC reads, or add a surrogate key","Verify split key cardinality/type before enabling parallelism"],"tags":["jdbc","splitter","composite-key","unsupported"],"backgroundTag":"unsupported-operation","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"}