Mapping Result Sets

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

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

When to Use resultMap

Scenario	Is resultMap recommended?
Query results come from JOINs or multiple tables	Recommended
Query columns include aliases, functions, or CASE expressions	Recommended
Return type is a DTO rather than a table entity	Recommended
Query result is the complete set of columns from one table	entity or object mapping may be enough

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.

resultMap tag

Define and use resultMap

<resultMap id="user_resultMap" type="com.example.dto.UserBean">
    <result column="id" property="id"/>
    <result column="name" property="name"/>
    <result column="age" property="age"/>
    <result column="create_time" property="createTime"/>
</resultMap>

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

Attributes

resultMap tag

Property	Description
id	Optional Identifier; if empty, type is used.
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.

result 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.