{"record":{"id":"f2072b0a01613c53","repo":"apache/shardingsphere","slug":"unsupported-textorderbyitemsegment","errorCode":null,"errorMessage":"unsupported TextOrderByItemSegment","messagePattern":"unsupported TextOrderByItemSegment","errorType":"exception","errorClass":"UnsupportedSQLOperationException","httpStatus":null,"severity":"error","filePath":"kernel/sql-federation/compiler/src/main/java/org/apache/shardingsphere/sqlfederation/compiler/sql/ast/converter/segment/orderby/item/OrderByItemConverterUtils.java","lineNumber":56,"sourceCode":"    \n    /**\n     * Convert order by items to SQL node.\n     *\n     * @param orderByItems order by items\n     * @return SQL nodes converted by order by item\n     * @throws UnsupportedSQLOperationException unsupported SQL operation exception\n     */\n    public static Collection<SqlNode> convert(final Collection<OrderByItemSegment> orderByItems) {\n        Collection<SqlNode> result = new LinkedList<>();\n        for (OrderByItemSegment each : orderByItems) {\n            if (each instanceof ColumnOrderByItemSegment) {\n                result.add(ColumnOrderByItemConverter.convert((ColumnOrderByItemSegment) each));\n            } else if (each instanceof ExpressionOrderByItemSegment) {\n                ExpressionOrderByItemConverter.convert((ExpressionOrderByItemSegment) each).ifPresent(result::add);\n            } else if (each instanceof IndexOrderByItemSegment) {\n                IndexOrderByItemConverter.convert((IndexOrderByItemSegment) each).ifPresent(result::add);\n            } else if (each instanceof TextOrderByItemSegment) {\n                throw new UnsupportedSQLOperationException(\"unsupported TextOrderByItemSegment\");\n            }\n        }\n        return result;\n    }\n}\n","sourceCodeStart":38,"sourceCodeEnd":62,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/kernel/sql-federation/compiler/src/main/java/org/apache/shardingsphere/sqlfederation/compiler/sql/ast/converter/segment/orderby/item/OrderByItemConverterUtils.java#L38-L62","documentation":"OrderByItemConverterUtils converts ORDER BY items to Calcite SqlNodes for federation. Column, Expression, and Index order-by items have converters; TextOrderByItemSegment — an order-by item preserved as raw text — is explicitly rejected with UnsupportedSQLOperationException, because raw text cannot be translated into the federated plan.","triggerScenarios":"A federated query's ORDER BY contains an item the parser kept as text (e.g. ORDER BY with a non-standard expression, ordinal in an odd position, or dialect-specific ordering syntax) instead of a recognized column/expression/index item.","commonSituations":"ORDER BY with vendor-specific functions or collation syntax; parser fallback capturing the item as text; queries ported between dialects.","solutions":["Rewrite the ORDER BY item as an explicit column reference or standard expression (e.g. ORDER BY column name or expression, not raw vendor syntax).","Move exotic ordering logic to the application by sorting the returned result set.","Disable federation for the statement so ordering runs on the storage node."],"exampleFix":"-- before\nSELECT * FROM t ORDER BY DATE_FORMAT(created, '%Y%m'); -- may parse as text item\n-- after\nSELECT * FROM t ORDER BY created;","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    rs = executeFederated(sql);\n} catch (final UnsupportedSQLOperationException ex) {\n    if (ex.getMessage().contains(\"TextOrderByItemSegment\")) { rs = executeRouted(sqlWithoutExoticOrder); } else { throw ex; }\n}","preventionTips":["Order by explicit columns or standard expressions, not vendor-specific text.","Sort exotic orderings in application code.","Verify ORDER BY items parse to column/expression segments before enabling federation."],"tags":["sql-federation","order-by","calcite","converter"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}