Annotation Type Temporal

@Retention(CLASS) @Target(FIELD) public @interface Temporal

Stores a java.util.Date, java.time.Instant, LocalDate or LocalDateTime field in a native date or timestamp column instead of the portable default, a number in an integer column: epoch milliseconds, or epoch days for a LocalDate. A LocalDate takes DATE and the other java.time types take TIMESTAMP; a LocalDateTime is written as its wall clock, with no zone applied.

Opt-in, because the two are different columns: an existing integer column keeps its milliseconds and an existing native one needs this annotation. Neither is converted into the other. A mapping that disagrees with the column it finds is reported by Session.schemaReport() as unsupported, and a backend refuses to start on it.

@Temporal(TemporalType.TIMESTAMP)
private Date createdAt;

Semantics, the same on every engine:

  • Values are written and read in UTC. The backend pins its own connections to UTC, so the server's or the column's time zone setting does not change what is stored. A TIMESTAMP WITH TIME ZONE column is read with the offset the server sends.
  • Precision is the millisecond, which is all a Date holds. A column with finer precision has the extra digits dropped on read; one with coarser precision rounds or truncates on write, as that engine does.
  • On SQLite, which has no native date type, the value is text in the form 2026-10-16 09:30:00.000, which sorts in time order. Rows written in a different textual form are read when they are ISO 8601, but compare as text in queries.

Applies to entity fields only; identifier, version and element collection values keep the portable storage, and the annotation cannot be combined with Convert.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    TemporalType
    value
    The native column type.

  • Element Details

    • value

      TemporalType value
      The native column type.
      Returns:
      TIMESTAMP or DATE
      Default:
      TIMESTAMP