{"record":{"id":"c086f4e4ece9abd1","repo":"hibernate/hibernate-orm","slug":"temporal-unit-not-supported","errorCode":null,"errorMessage":"Temporal unit not supported [{}]","messagePattern":"Temporal unit not supported \\[(.+?)\\]","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/function/DateTruncEmulation.java","lineNumber":102,"sourceCode":"\t\t\t\tbreak;\n\t\t\tcase DAY:\n\t\t\t\tpattern = \"yyyy-MM-dd\";\n\t\t\t\tliteral = \" 00:00:00\";\n\t\t\t\tbreak;\n\t\t\tcase HOUR:\n\t\t\t\tpattern = \"yyyy-MM-dd HH\";\n\t\t\t\tliteral = \":00:00\";\n\t\t\t\tbreak;\n\t\t\tcase MINUTE:\n\t\t\t\tpattern = \"yyyy-MM-dd HH:mm\";\n\t\t\t\tliteral = \":00\";\n\t\t\t\tbreak;\n\t\t\tcase SECOND:\n\t\t\t\tpattern = \"yyyy-MM-dd HH:mm:ss\";\n\t\t\t\tliteral = null;\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\tthrow new UnsupportedOperationException( \"Temporal unit not supported [\" + temporalUnit + \"]\" );\n\t\t}\n\t\tfinal var datetime = arguments.get( 0 );\n\t\tfinal var formatExpression =\n\t\t\t\tqueryEngine.getSqmFunctionRegistry()\n\t\t\t\t\t\t.getFunctionDescriptor( \"format\" )\n\t\t\t\t\t\t.generateSqmExpression(\n\t\t\t\t\t\t\t\tasList(\n\t\t\t\t\t\t\t\t\t\tdatetime,\n\t\t\t\t\t\t\t\t\t\tnew SqmFormat( pattern, nodeBuilder.getStringType(), nodeBuilder )\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\tnull,\n\t\t\t\t\t\t\t\tqueryEngine\n\t\t\t\t\t\t);\n\t\tfinal SqmExpression<?> formattedDatetime;\n\t\tif ( literal != null ) {\n\t\t\tformattedDatetime =\n\t\t\t\t\tqueryEngine.getSqmFunctionRegistry()\n\t\t\t\t\t\t\t.getFunctionDescriptor( \"concat\" )","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/function/DateTruncEmulation.java#L84-L120","documentation":"DateTruncEmulation (used by TruncFunction when the dialect lacks native date_trunc) formats the datetime with format() and pads the trailing components; it implements only YEAR, MONTH, DAY, HOUR, MINUTE and SECOND. Requesting any other TemporalUnit — WEEK, QUARTER, MILLISECOND, EPOCH, NATIVE... — hits the default branch and throws UnsupportedOperationException at query compilation.","triggerScenarios":"HQL like 'select trunc(e.ts, WEEK)' or date_trunc('week', ts) emulation on a dialect using DateTruncEmulation; extract/trunc with temporal units such as quarter, millisecond, or week on those dialects (commonly SAP HANA, which routes TruncFunction through toDateFunction emulation).","commonSituations":"Writing portable HQL on PostgreSQL (week works natively) and running the same query on HANA/other DB in CI or production; upgrading Hibernate and having previously-ignored units now validated strictly.","solutions":["Use one of the supported units (YEAR, MONTH, DAY, HOUR, MINUTE, SECOND)","Compute week/quarter truncation differently: e.g. arithmetic on extract(year/month) or a native query for that DB","Extend the dialect: subclass and register a custom date_trunc/trunc descriptor that renders week/quarter SQL for your database"],"exampleFix":"// before (HANA / emulated date_trunc)\nsession.createQuery(\"select trunc(e.ts, WEEK) from Event e\"); // -> UnsupportedOperationException\n\n// after\nsession.createQuery(\"select trunc(e.ts, DAY) from Event e\"); // supported unit","handlingStrategy":"validation","validationCode":"Set<TemporalUnit> SUPPORTED = EnumSet.of(YEAR, MONTH, DAY, HOUR, MINUTE, SECOND);\nif (!SUPPORTED.contains(unit) && dialectLacksNativeDateTrunc(dialect)) {\n    throw new IllegalArgumentException(\"date_trunc unit \" + unit + \" unsupported on \" + dialect);\n}","typeGuard":"boolean isEmulationSupportedUnit(TemporalUnit u) {\n    return u == YEAR || u == MONTH || u == DAY || u == HOUR || u == MINUTE || u == SECOND;\n}","tryCatchPattern":"catch (UnsupportedOperationException e) {\n    // fall back to a native query for exotic units on this dialect\n    return runNativeWeekTruncation(session, ts);\n}","preventionTips":["Keep a per-dialect capability matrix for temporal units in the test suite","Express week/quarter logic via arithmetic on extract() results instead of trunc()","Wrap trunc() calls behind a repository method so fallback logic lives in one place"],"tags":["hibernate","hql","date-trunc","temporal-unit","function-emulation"],"backgroundTag":"unsupported-temporal-unit","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}