Hint

This article is generated by AI translation.

Table Mapping

Example 1: class name as table name (default)

@Table
public class Users {      // Maps to Users table
    private Integer id;   // Maps to id column
    private String  name; // Maps to name column
    private Integer age;  // Maps to age column

    // getters and setters omitted
}

Example 2: specify table name

@Table("admin_users")
public class AdminUsers {       // Maps to admin_users table
    private Integer id;         // Maps to id column
    private String  name;       // Maps to name column
    private Integer age;        // Maps to age column
    @Column("create_time")
    private Date    createTime; // Maps to create_time column

    // getters and setters omitted
}

Example 3: specify catalog/schema

@Table(catalog = "co", 
       schema  = "example", 
       table   = "admin_users")
public class AdminUsers {       // Maps to co.example.admin_users
    private Integer id;         // Maps to id column
    private String  name;       // Maps to name column
    private Integer age;        // Maps to age column

    // getters and setters omitted
}

Example 4: annotation-only mapping

@Table(table = "admin_users", autoMapping = false)
public class AdminUsers {       // Maps to admin_users table
    private Integer id;         // Not mapped
    private String  name;       // Not mapped
    @Column
    private Integer age;        // Maps to age column
    @Column("create_time")
    private Date    createTime; // Maps to create_time column

    // getters and setters omitted
}

Example 5: ignore a property

@Table(table = "admin_users")
public class AdminUsers {       // Maps to admin_users table
    private Integer id;         // Maps to id column
    private String  name;       // Maps to name column
    private Integer age;        // Maps to age column
    @Ignore
    private Date    modifyTime; // Ignored from column mapping
}

@Table attributes

Attribute	Description
catalog	可选 Catalog name. Default empty.
schema	可选 Schema name. Default empty.
table	可选 Table name; defaults to class name when empty. Tip: value is equivalent; when all defaults are used you can omit the attribute name as in Example 2.
value	可选 Same as table; defaults to class name when empty. Tip: value is equivalent; when all defaults are used you can omit the attribute name as in Example 2.
autoMapping	可选 Auto mapping on by default. When false, every mapped column must be annotated with @Column.
useDelimited	可选 Wrap table/column names in delimiters to handle reserved words. Default false.
caseInsensitive	可选 Case-insensitive table/column names when true (default). Applies when reading result sets.
mapUnderscoreToCamelCase	可选 Convert camel-case names to underscore in table/column names. Off by default.
ddlAuto	可选 Auto DDL mode: none, create, add, update, create-drop (auto DDL not yet supported).

@Table inheritance behavior

In an entity inheritance hierarchy, annotations like @Column and @Ignore on parent class fields are correctly inherited by subclasses, but @Table is a class-level annotation and is NOT inherited from the parent class. Therefore, attributes like autoMapping are determined solely by the @Table declaration on the actual registered entity (leaf class) itself.

Parent autoMapping=false does not affect child

@Table(value = "user_info", autoMapping = false)
public class ParentEntity {
    @Column(primary = true)
    private Integer id;        // Has @Column → child will also map
    private Integer age;       // No @Column → mapping depends on child's autoMapping
}

@Table(value = "user_info", autoMapping = true)
public class ChildEntity extends ParentEntity {
    private String email;      // No @Column → auto-mapped (child autoMapping=true takes effect)
}
// ChildEntity registered: id, age, email — all three fields are mapped
// ParentEntity's autoMapping=false has no effect on ChildEntity

Conversely: parent autoMapping=true also does not affect child

@Table(value = "user_info", autoMapping = true)
public class ParentEntity {
    @Column(primary = true)
    private Integer id;        // Has @Column → always mapped
    private Integer age;       // No @Column → mapping depends on child's autoMapping
}

@Table(value = "user_info", autoMapping = false)
public class ChildEntity extends ParentEntity {
    private String email;      // No @Column → not mapped (child autoMapping=false takes effect)
}
// ChildEntity registered: only id is mapped (the only field with @Column)
// age and email are not mapped because child autoMapping=false

@Column Attributes

Attribute	Description
name	可选 Column name; defaults to the property name.
value	可选 Column name; defaults to the property name.
jdbcType	可选 jdbcType to use; default is Types.JAVA_OBJECT.
specialJavaType	可选 For abstract properties, specify the concrete implementation type.
typeHandler	可选 TypeHandler to read/write the column.
keyType	可选 Applies to Fluent API. Data generator when the value is null. See Key generator.
primary	可选 Whether this is a primary key. Default false.
insert	可选 For Fluent API: whether to include in insert. See Write policy.
update	可选 For Fluent API: whether to include in update. See Write policy.
selectTemplate	可选 For Fluent API: column expression in SELECT. Empty = column name. See Statement templates.
insertTemplate	可选 For Fluent API: argument expression in INSERT, default ?. See Statement templates.
setValueTemplate	可选 For Fluent API: argument expression in UPDATE SET, default ?. See Statement templates.
whereColTemplate	可选 For Fluent API: column expression in WHERE (update/delete). Empty = column name. See Statement templates.
whereValueTemplate	可选 For Fluent API: argument expression in WHERE (update/delete), default ?. See Statement templates.
orderByColTemplate	可选 For Fluent API: column expression in ORDER BY. Empty = column name. See Statement templates.

@Primary Annotation

Note: distinguish @Column(primary=true) from @Primary

These two concepts have similar names but completely different meanings. Please note the distinction.

@Column(primary = true) — indicates that the property's corresponding column is a database primary key. Used to determine the WHERE condition during INSERT/UPDATE/DELETE operations.

@Table("user_info")
public class UserInfo {
    @Column(primary = true)
    private Integer id;    // Marks the id column as database primary key
    private String name;
}

@Primary — when the same column maps to multiple properties, marks which property is the preferred property. The preferred property can be retrieved via the getPrimaryPropertyByColumn method.

@Table("user_info")
public class UserInfo {
    @Column(primary = true)
    private Integer id;

    @Column("name")
    private String aliasName;   // Property aliasName maps to the name column

    @Primary
    @Column("name")
    private String primaryName; // Property primaryName also maps to the name column, and is the preferred one
}

In the example above, both aliasName and primaryName map to the database's name column. getPropertyByColumn("name") returns both properties, while getPrimaryPropertyByColumn("name") returns only the primaryName annotated with @Primary.

Usage notes:

• Among multiple properties mapped to the same column, at most one can be annotated with @Primary; otherwise an IllegalStateException is thrown.
• If none of the properties for the same column are annotated with @Primary, getPrimaryPropertyByColumn returns null.
• @Primary can be placed on fields or getter/setter methods.
• @Primary and @Column(primary=true) can be used together without conflict: the former resolves "which property to choose among multiple", while the latter declares "this is a primary key column".