{"record":{"id":"1a156dc08335a78b","repo":"apache/beam","slug":"unable-to-convert-query-s","errorCode":null,"errorMessage":"Unable to convert query %s","messagePattern":"Unable to convert query (.+?)","errorType":"exception","errorClass":"SqlConversionException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CalciteQueryPlanner.java","lineNumber":238,"sourceCode":"              .simplify();\n      // beam physical plan\n      relNode\n          .getCluster()\n          .setMetadataProvider(\n              ChainedRelMetadataProvider.of(\n                  ImmutableList.of(\n                      NonCumulativeCostImpl.SOURCE,\n                      RelMdNodeStats.SOURCE,\n                      relNode.getCluster().getMetadataProvider())));\n\n      relNode.getCluster().setMetadataQuerySupplier(BeamRelMetadataQuery::instance);\n      RelMetadataQuery.THREAD_PROVIDERS.set(\n          JaninoRelMetadataProvider.of(relNode.getCluster().getMetadataProvider()));\n      relNode.getCluster().invalidateMetadataQuery();\n      beamRelNode = (BeamRelNode) planner.transform(0, desiredTraits, relNode);\n      LOG.info(\"BEAMPlan>\\n{}\", BeamSqlRelUtils.explainLazily(beamRelNode));\n    } catch (RelConversionException | CannotPlanException e) {\n      throw new SqlConversionException(\n          String.format(\"Unable to convert query %s\", sqlStatement), e);\n    } catch (SqlParseException | ValidationException e) {\n      throw new ParseException(String.format(\"Unable to parse query %s\", sqlStatement), e);\n    } finally {\n      planner.close();\n    }\n    return beamRelNode;\n  }\n\n  private static RelNode bindParameters(RelNode rel, RexShuttle binder) {\n    RelNode newRel = rel.accept(binder);\n    java.util.List<RelNode> newInputs = new java.util.ArrayList<>();\n    for (RelNode input : newRel.getInputs()) {\n      newInputs.add(bindParameters(input, binder));\n    }\n    return newRel.copy(newRel.getTraitSet(), newInputs);\n  }\n","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CalciteQueryPlanner.java#L220-L256","documentation":"CalciteQueryPlanner.convertToBeamRel() catches RelConversionException and CannotPlanException from Calcite's planning/optimization pipeline and rethrows them as SqlConversionException with the SQL statement. The SQL parsed but Calcite/Beam could not convert the validated relational tree into an executable BeamRelNode — typically an unsupported relational construct or a trait-conversion/planning failure. This signals a planning problem, not a syntax error.","triggerScenarios":"Calling convertToBeamRel(String sqlStatement) where the validated plan cannot be transformed to Beam traits (planner.transform(0, desiredTraits, relNode) throws RelConversionException) or cannot be produced (CannotPlanException).","commonSituations":"Queries with relational operators Beam SQL does not implement (exotic JOINs, unsupported windowing); queries referencing unsupported table expressions; hints/features Calcite cannot satisfy under Beam's convention traits.","solutions":["Rewrite the query to avoid the unsupported construct identified in the exception cause.","Simplify or split the query, computing the unsupported part outside SQL.","Check Beam SQL supported-features docs for the specific operator.","Upgrade Beam — unsupported operators are added over time."],"exampleFix":"// before\npipeline.apply(SqlTransform.query(\"SELECT * FROM t ASOF JOIN u ...\"));\n// after\npipeline.apply(SqlTransform.query(\"SELECT * FROM t JOIN u ON t.k = u.k\"));","handlingStrategy":"try-catch","validationCode":"// no direct pre-check API; keep queries within documented supported operators\n// and test complex queries against the exact Beam version in CI","typeGuard":null,"tryCatchPattern":"try {\n  BeamRelNode beamRel = planner.convertToBeamRel(sqlStatement);\n} catch (SqlConversionException e) {\n  LOG.error(\"Cannot plan query [{}]: {}\", sqlStatement, e.getCause().getMessage());\n  throw e;\n}","preventionTips":["Restrict queries to operators listed in Beam SQL supported features","Test complex queries against the actual Beam version in CI","Simplify unsupported constructs rather than layering hints","Track Beam releases for newly supported relational operators"],"tags":["sql","query-planning","beam"],"backgroundTag":"sql-query-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}