Mapping Tables

Use either <resultMap> or <entity> to map query results:

• <resultMap>: map SQL result sets.
• <entity>: map a concrete table.

When to Use entity

Scenario	Is entity recommended?
Java type and database table map directly	Recommended
BaseMapper or LambdaTemplate needs table mapping	Recommended
You want XML mapping instead of annotations	Recommended
Query result comes from JOINs or function columns	Prefer resultMap

How to choose between resultMap and entity?

• For the same table with different query shapes, entity is good when columns all come from one table; resultMap when columns span multiple tables.
• Using the Builder API requires entity or Object Mapping annotations.
• If the SELECT uses aliases, functions, CASE, or columns from multiple tables, resultMap is safer.

entity tag

Define and use entity

<entity id="user_resultMap" table="users" type="com.example.dto.UserBean">
    <id column="id" property="id"/>
    <mapping column="name" property="name"/>
    <mapping column="age" property="age"/>
    <mapping column="create_time" property="createTime"/>
</entity>

<select id="queryById" resultMap="user_resultMap">
    select
        id, name, age, create_time
    from
        users
    where
        id = #{id}
</select>

Attributes

entity tag

Property	Description
id	Optional Identifier; if empty, type is used.
catalog	Optional Catalog of the mapped table.
schema	Optional Schema of the mapped table.
table	Optional Table name.
type	Required Fully qualified Java type to map to.
caseInsensitive	Optional Case-insensitive mapping for column/property names. Default true.
autoMapping	Optional Whether to perform auto-mapping. Default true.
mapUnderscoreToCamelCase	Optional With auto-mapping, convert camelCase property names to snake_case columns (e.g., createTime → create_time). Default false.
useDelimited	Optional Force quoting/delimiters on table/column names when generating SQL. Default false.
character-set	Optional Table character set (available via TableDescription).
collation	Optional Table collation (TableDescription).
comment	Optional Table comment (TableDescription).
other	Optional Other table options (TableDescription).
ddlAuto	Optional Auto DDL strategy: none, create, add, update, create-drop (auto DDL not yet supported).

id tag and mapping tag

Property	Description
column	Required Column name in the result set.
property	Required Property name in the target type.
javaType	Optional Usually inferred; specify when the property is abstract or an interface.
jdbcType	Optional Overrides the default Java↔JDBC mapping.
typeHandler	Optional Override the type handler to use.
keyType	Optional For Builder API only. Key generation strategy when the value is null. See key generator.
insert	Optional For Builder API only. Whether it participates in insert. See write policy.
update	Optional For Builder API only. Whether it participates in update. See write policy.
selectTemplate	Optional For Builder API only. Column expression when used in SELECT. Default empty (column name). See templates.
insertTemplate	Optional For Builder API only. Argument expression for INSERT. Default ?. See templates.
setValueTemplate	Optional For Builder API only. Argument expression in UPDATE SET. Default ?. See templates.
whereColTemplate	Optional For Builder API only. Column expression in WHERE for update/delete. Default empty (column name). See templates.
whereValueTemplate	Optional For Builder API only. Argument expression in WHERE for update/delete. Default ?. See templates.
orderByColTemplate	Optional For Builder API only. Column expression in ORDER BY. Default empty (column name). See templates.
sqlType	Optional Column data type (TableDescription).
length	Optional Column length (TableDescription).
precision	Optional Numeric precision (TableDescription).
scale	Optional Numeric scale (TableDescription).
character-set	Optional Column character set (TableDescription).
collation	Optional Column collation (TableDescription).
nullable	Optional Whether the column allows NULL; for <id> this is always false and cannot be set (TableDescription).
default	Optional Column default value (TableDescription).
comment	Optional Column comment (TableDescription).
other	Optional Other column options (TableDescription).