{"record":{"id":"cd1ab717481a052d","repo":"hibernate/hibernate-orm","slug":"unrecognized-field","errorCode":null,"errorMessage":"Unrecognized field: ","messagePattern":"Unrecognized field: ","errorType":"exception","errorClass":"SemanticException","httpStatus":null,"severity":"error","filePath":"hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/GaussDBDialect.java","lineNumber":529,"sourceCode":"\t}\n\n\t@Override @SuppressWarnings(\"deprecation\")\n\tpublic String timestampdiffPattern(TemporalUnit unit, TemporalType fromTemporalType, TemporalType toTemporalType) {\n\t\tif ( unit == null ) {\n\t\t\treturn \"(?3-?2)\";\n\t\t}\n\t\treturn switch (unit) {\n\t\t\tcase YEAR -> \"extract(year from ?3-?2)\";\n\t\t\tcase QUARTER -> \"(extract(year from ?3-?2)*4+extract(month from ?3-?2)/3)\";\n\t\t\tcase MONTH -> \"(extract(year from ?3-?2)*12+extract(month from ?3-?2))\";\n\t\t\tcase WEEK -> \"(extract(day from ?3-?2)/7)\"; // week is not supported by extract() when the argument is a duration\n\t\t\tcase DAY -> \"extract(day from ?3-?2)\";\n\t\t\t// in order to avoid multiple calls to extract(),\n\t\t\t// we use extract(epoch from x - y) * factor for\n\t\t\t// all the following units:\n\t\t\tcase HOUR, MINUTE, SECOND, NANOSECOND, NATIVE ->\n\t\t\t\t\t\"extract(epoch from ?3-?2)\" + EPOCH.conversionFactor( unit, this );\n\t\t\tdefault -> throw new SemanticException( \"Unrecognized field: \" + unit );\n\t\t};\n\t}\n\n\t@Override\n\tpublic TimeZoneSupport getTimeZoneSupport() {\n\t\treturn TimeZoneSupport.NORMALIZE;\n\t}\n\n\t@Override\n\tpublic void initializeFunctionRegistry(FunctionContributions functionContributions) {\n\t\tsuper.initializeFunctionRegistry(functionContributions);\n\n\t\tGaussDBFunctionRegistry functionRegistry = new GaussDBFunctionRegistry( functionContributions );\n\t\tfunctionRegistry.register();\n\t}\n\n\t@Override\n\tpublic @Nullable String getDefaultOrdinalityColumnName() {","sourceCodeStart":511,"sourceCodeEnd":547,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/GaussDBDialect.java#L511-L547","documentation":"GaussDBDialect.timestampdiffPattern builds the SQL for HQL timestampdiff(unit, a, b) and for duration differences. It explicitly implements YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, NANOSECOND and NATIVE via extract() over the interval; any other TemporalUnit falls into the default branch and throws SemanticException ('Unrecognized field: <unit>'), because GaussDB's extract() cannot handle that unit over a duration.","triggerScenarios":"HQL 'timestampdiff(decade, d1, d2)' or duration unit arithmetic using units outside the supported set (e.g. decade, century, millennium, or date-part fields like day_of_week used as a diff unit), executed with the GaussDB dialect. Equivalent constructs like 'x by decade' duration literals hit the same pattern.","commonSituations":"Porting HQL written for PostgreSQLDialect, whose timestampdiffPattern covers more units, to GaussDB; queries computing long-horizon differences (decades/centuries) in reporting code; unit tests that iterate over every TemporalUnit.","solutions":["Rewrite the difference using a supported unit and convert in HQL or Java: timestampdiff(year, d1, d2) / 10 instead of decade","Compute the duration in a supported base unit (epoch seconds via SECOND or NATIVE) and derive the exotic unit in Java","Use a native query with GaussDB-compatible extract() expressions for the rare exotic-unit cases","Normalize all timestampdiff calls in shared query code to the supported unit set {year, quarter, month, week, day, hour, minute, second, nanosecond}"],"exampleFix":"// before (HQL, throws on GaussDB)\nlong decades = session.createQuery(\"select timestampdiff(decade, p.start, p.end) from Period p\", Long.class).getSingleResult();\n\n// after (supported unit + Java conversion)\nlong years = session.createQuery(\"select timestampdiff(year, p.start, p.end) from Period p\", Long.class).getSingleResult();\nlong decades = years / 10;","handlingStrategy":"validation","validationCode":"static final Set<TemporalUnit> GAUSS_DIFF_UNITS = EnumSet.of(\n    TemporalUnit.YEAR, TemporalUnit.QUARTER, TemporalUnit.MONTH, TemporalUnit.WEEK,\n    TemporalUnit.DAY, TemporalUnit.HOUR, TemporalUnit.MINUTE, TemporalUnit.SECOND,\n    TemporalUnit.NANOSECOND, TemporalUnit.NATIVE);\n\nif (!GAUSS_DIFF_UNITS.contains(unit)) {\n    unit = normalizeToSupported(unit); // decade -> year, divide by 10 afterwards\n}","typeGuard":"static boolean timestampdiffUnitSafe(Dialect d, TemporalUnit unit) {\n    return !(d instanceof GaussDBDialect) || GAUSS_DIFF_UNITS.contains(unit);\n}","tryCatchPattern":"try {\n    v = session.createQuery(\"select timestampdiff(\" + unit.name() + \", a, b) ...\", Long.class).getSingleResult();\n} catch (org.hibernate.query.SemanticException e) {\n    if (e.getMessage().startsWith(\"Unrecognized field\")) {\n        // re-express in a base unit (year/second) and convert in Java\n    } else throw e;\n}","preventionTips":["Restrict shared query code to the widely supported diff units (year..second, epoch)","Convert exotic units (decade/century) in application code, not in HQL","When porting from PostgreSQLDialect, review timestampdiff units against the GaussDB override"],"tags":["hibernate","gaussdb","hql","timestampdiff","temporal-unit","extract"],"backgroundTag":"temporal-unit-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}