{"record":{"id":"523bcfd0520b8b24","repo":"apache/beam","slug":"specifying-alignment-offset-is-not-supported-for-session","errorCode":null,"errorMessage":"Specifying alignment (offset) is not supported for session windows","messagePattern":"Specifying alignment \\(offset\\) is not supported for session windows","errorType":"exception","errorClass":"java.lang.UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rule/BeamAggregationRule.java","lineNumber":189,"sourceCode":"        if (parameters.size() == 4) {\n          slidingWindows = slidingWindows.withOffset(durationParameter(parameters, 3));\n        }\n\n        return slidingWindows;\n      case SESSION:\n\n        // Session windows, for example:\n        //   aggregate events after a gap of 1 minute of no events;\n        //\n        // SQL Syntax:\n        //   SESSION(monotonic_field, session_gap)\n        //\n        // Example:\n        //   SESSION(event_timestamp_field, INTERVAL '1' MINUTE)\n\n        Sessions sessions = Sessions.withGapDuration(durationParameter(parameters, 1));\n        if (parameters.size() == 3) {\n          throw new UnsupportedOperationException(\n              \"Specifying alignment (offset) is not supported for session windows\");\n        }\n\n        return sessions;\n      default:\n        return null;\n    }\n  }\n\n  private static Duration durationParameter(List<RexNode> parameters, int parameterIndex) {\n    return Duration.millis(longValue(parameters.get(parameterIndex)));\n  }\n\n  private static long longValue(RexNode operand) {\n    if (operand instanceof RexLiteral) {\n      // @TODO: this can be simplified after CALCITE-2837\n      return ((Number) RexLiteral.value(operand)).longValue();\n    } else {","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rule/BeamAggregationRule.java#L171-L207","documentation":"Beam SQL SESSION windowing (BeamAggregationRule.createWindowFn) accepts only the gap-duration parameter. Unlike Tumble/Hop, Sessions windows have no alignment offset, so a third parameter triggers this UnsupportedOperationException at query translation time.","triggerScenarios":"Writing SESSION(event_ts, INTERVAL '1' MINUTE, <offset>) with three parameters; createWindowFn sees parameters.size()==3 and throws.","commonSituations":"Copy-pasting a TUMBLE(ts, INTERVAL '1' HOUR, INTERVAL '0' SECOND)-style call pattern to SESSION, or porting SQL from engines (e.g. some ZetaSQL/other dialects) where session windows accept an offset.","solutions":["Remove the third (offset) argument and call SESSION with only the timestamp descriptor and gap duration.","Compute the desired alignment in a pre-transform (e.g. shift timestamps) since session windows are gap-driven and alignment doesn't apply.","Use TUMBLE or HOP instead if you specifically need window alignment/offset.","Validate the SQL against the Beam SQL windowing docs for supported parameter counts before running."],"exampleFix":"-- before\nSELECT ... GROUP BY SESSION(ts, INTERVAL '1' MINUTE, INTERVAL '30' SECOND)\n-- after\nSELECT ... GROUP BY SESSION(ts, INTERVAL '1' MINUTE)","handlingStrategy":"validation","validationCode":"if (functionName.equalsIgnoreCase(\"SESSION\") && parameters.size() > 2) { throw new IllegalArgumentException(\"SESSION accepts only descriptor and gap duration\"); }","typeGuard":"boolean sessionArityOk = !\"SESSION\".equalsIgnoreCase(fnName) || parameters.size() == 2;","tryCatchPattern":"try { result = pipeline.apply(SqlTransform.query(sql)); } catch (UnsupportedOperationException e) { if (e.getMessage().contains(\"alignment (offset) is not supported for session windows\")) { /* drop the offset argument */ } else { throw e; } }","preventionTips":["Call SESSION with exactly two arguments: descriptor and gap duration","Do not copy TUMBLE/HOP 3-arg call patterns to SESSION","Lint user SQL for SESSION TVF arity before submission","Consult Beam SQL windowing docs for per-TVF parameter lists"],"tags":["sql","windowing","session-window","unsupported"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}