{"record":{"id":"5da6f15cf4ef0780","repo":"hibernate/hibernate-orm","slug":"native-is-not-a-legal-field-for-extract","errorCode":null,"errorMessage":"NATIVE is not a legal field for extract()","messagePattern":"NATIVE is not a legal field for extract\\(\\)","errorType":"exception","errorClass":"SemanticException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/dialect/function/ExtractFunction.java","lineNumber":98,"sourceCode":"\t\tfinal String pattern = dialect.extractPattern( unit );\n\t\tnew PatternRenderer( pattern ).render( sqlAppender, sqlAstArguments, walker );\n\t}\n\n\t@Override\n\tprotected <T> SelfRenderingSqmFunction generateSqmFunctionExpression(\n\t\t\tList<? extends SqmTypedNode<?>> arguments,\n\t\t\tReturnableType<T> impliedResultType,\n\t\t\tQueryEngine queryEngine) {\n\t\tfinal SqmExtractUnit<?> field = (SqmExtractUnit<?>) arguments.get( 0 );\n\t\tfinal SqmExpression<?> originalExpression = (SqmExpression<?>) arguments.get( 1 );\n\t\tfinal boolean compositeTemporal = SqmExpressionHelper.isCompositeTemporal( originalExpression );\n\t\tfinal SqmExpression<?> expression = SqmExpressionHelper.getOffsetAdjustedExpression( originalExpression );\n\n\t\tswitch ( field.getUnit() ) {\n\t\t\tcase NANOSECOND:\n\t\t\t\treturn extractNanoseconds( expression, queryEngine );\n\t\t\tcase NATIVE:\n\t\t\t\tthrow new SemanticException(\"NATIVE is not a legal field for extract()\");\n\t\t\tcase OFFSET:\n\t\t\t\tif ( compositeTemporal ) {\n\t\t\t\t\tfinal SqmPath<Object> offsetPath = ( (SqmPath<?>) originalExpression ).get(\n\t\t\t\t\t\t\tZONE_OFFSET_NAME\n\t\t\t\t\t);\n\t\t\t\t\treturn new SelfRenderingSqmFunction<>(\n\t\t\t\t\t\t\tthis,\n\t\t\t\t\t\t\t(sqlAppender, sqlAstArguments, returnType, walker) -> sqlAstArguments.get( 0 ).accept( walker ),\n\t\t\t\t\t\t\tCollections.singletonList( offsetPath ),\n\t\t\t\t\t\t\tnull,\n\t\t\t\t\t\t\tnull,\n\t\t\t\t\t\t\tStandardFunctionReturnTypeResolvers.useArgType( 1 ),\n\t\t\t\t\t\t\texpression.nodeBuilder(),\n\t\t\t\t\t\t\t\"extract\"\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\t// use format(arg, 'xxx') to get the offset","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/dialect/function/ExtractFunction.java#L80-L116","documentation":"TemporalUnit.NATIVE is an internal marker used by dialects for dialect-specific extract fields (like Oracle's timezone_* parts); it is never a valid user-facing field. The ANSI ExtractFunction throws SemanticException as soon as an SQM extract() unit resolves to NATIVE, because there is no generic SQL rendering for it.","triggerScenarios":"HQL 'select extract(native from e.timestamp)' or criteria API extract(TemporalUnit.NATIVE, ...) reaching a dialect that uses the generic ExtractFunction rather than interpreting native units; also misusing an enum-mapped field whose name maps onto NATIVE in custom TemporalUnit extensions.","commonSituations":"Curiosity-driven or generated queries using unsupported fields; custom dialect work where TemporalUnit.NATIVE constants leak into user-visible criteria; upgrading from Hibernate 5 where some units were silently ignored.","solutions":["Use a legal field: year, month, day, hour, minute, second, or the dialect-supported ones (quarter, week, epoch, day_of_week, ...)","For dialect-specific parts, write a native query (e.g. Oracle EXTRACT(TIMEZONE_ABBR ...)) or register a custom function","If you maintain a custom dialect, map native fields via a dedicated function descriptor instead of exposing NATIVE through extract()"],"exampleFix":"// before\nInteger y = session.createQuery(\"select extract(native from e.ts) from Event e\", Integer.class)...;\n\n// after\nInteger y = session.createQuery(\"select extract(year from e.ts) from Event e\", Integer.class)...;","handlingStrategy":"validation","validationCode":"Set<TemporalUnit> LEGAL = EnumSet.range(YEAR, SECOND); // plus dialect extras\nif (unit == TemporalUnit.NATIVE) throw new IllegalArgumentException(\"extract(native ...) is invalid\");","typeGuard":"boolean isLegalExtractUnit(TemporalUnit u) { return u != TemporalUnit.NATIVE; }","tryCatchPattern":"catch (SemanticException e) {\n    if (e.getMessage().contains(\"NATIVE\")) {\n        throw new IllegalArgumentException(\"Rewrite query: use a supported extract field\", e);\n    }\n    throw e;\n}","preventionTips":["Validate extract() units against a whitelist when queries are built dynamically","Use native queries for dialect-specific date parts","Do not expose TemporalUnit.NATIVE through public query-builder APIs"],"tags":["hibernate","hql","extract-function","temporal-unit","semantic-error"],"backgroundTag":"unsupported-temporal-unit","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}