apache/shardingsphere · error · UnsupportedSQLOperationException

unsupported CommonExpressionSegment

Error message

unsupported CommonExpressionSegment

What it means

While converting a parsed ShardingSphere expression tree into Apache Calcite SqlNodes for SQL federation, ExpressionConverter has no conversion for CommonExpressionSegment (a raw, unparsed expression fragment) and throws UnsupportedSQLOperationException. It is a marked TODO: expression shapes the parser kept as common text cannot be compiled by the federation compiler.

Source

Thrown at kernel/sql-federation/compiler/src/main/java/org/apache/shardingsphere/sqlfederation/compiler/sql/ast/converter/segment/expression/ExpressionConverter.java:99

public final class ExpressionConverter {
    
    /**
     * Convert expression segment to SQL node.
     *
     * @param segment expression segment
     * @return SQL node
     * @throws UnsupportedSQLOperationException unsupported SQL operation exception
     */
    public static Optional<SqlNode> convert(final ExpressionSegment segment) {
        if (null == segment) {
            return Optional.empty();
        }
        if (segment instanceof LiteralExpressionSegment) {
            return LiteralExpressionConverter.convert((LiteralExpressionSegment) segment, null);
        }
        if (segment instanceof CommonExpressionSegment) {
            // TODO
            throw new UnsupportedSQLOperationException("unsupported CommonExpressionSegment");
        }
        if (segment instanceof ListExpression) {
            return ListExpressionConverter.convert((ListExpression) segment);
        }
        if (segment instanceof BinaryOperationExpression) {
            return Optional.of(BinaryOperationExpressionConverter.convert((BinaryOperationExpression) segment));
        }
        if (segment instanceof ColumnSegment) {
            return Optional.of(ColumnConverter.convert((ColumnSegment) segment));
        }
        if (segment instanceof ExistsSubqueryExpression) {
            return Optional.of(ExistsSubqueryExpressionConverter.convert((ExistsSubqueryExpression) segment));
        }
        if (segment instanceof SubqueryExpressionSegment) {
            return Optional.of(SubqueryExpressionConverter.convert((SubqueryExpressionSegment) segment));
        }
        if (segment instanceof InExpression) {
            return Optional.of(InExpressionConverter.convert((InExpression) segment));

View on GitHub (pinned to e952770a21)

Solutions

  1. Rewrite the query to use standard SQL expressions the parser fully decomposes (avoid the construct that lands in CommonExpressionSegment).
  2. Turn off SQL federation for this statement/rule (sql_federation execution mode NONE / rule-level disable) so it executes via normal routing.
  3. Upgrade ShardingSphere — federation converter coverage grows over releases.
  4. Extract the problematic expression into application-side computation if federation is otherwise required.
Defensive patterns

Strategy: fallback

Try / catch

try {
    rs = federationEngine.executeQuery(...);
} catch (final UnsupportedSQLOperationException ex) {
    // retry with federation disabled so the query routes normally
    rs = routedExecute(sql, params);
}

Prevention

When it happens

Trigger: A federated query contains an expression the SQL parser did not decompose into a known segment type (function calls, operators, or dialect-specific syntax kept verbatim), so the converter hits CommonExpressionSegment and fails during plan compilation.

Common situations: Federated SELECTs with uncommon scalar functions or operator syntax; queries relying on dialect-specific expressions; parser versions that fall back to common-expression capture for constructs they cannot fully parse.

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/00f437b85651e0db. Report an issue: GitHub.