ResultMap vs ResultType - When It Matters

ResultType maps each row to a Java type when column names match property names (or with global mapUnderscoreToCamelCase). ResultMap explicitly defines column-to-property mapping and supports nested objects, collections, constructors, and discriminators. Use ResultMap when you have associations, collections, or column names that do not match. This article explains when to use each with examples and a comparison table.

Overview

• ResultType: Best for single-table queries with straightforward column-to-property mapping. One row maps to one object; no nesting. Simple and concise.
• ResultMap: Use when you need nested objects (e.g. Order has User), collections (e.g. Order has List<OrderItem>), column names that do not match properties, or multiple tables in one query. Reusable, extendable, and easier to maintain for complex mappings.
• Choice: Simple single-table → ResultType. Associations, nesting, column mismatch, or multi-table JOIN building one entity → ResultMap.

Example

Example 1: ResultType — single table, columns match

XMLCopy
<select id="selectById" resultType="com.example.entity.User">
  SELECT id, user_name, email FROM user WHERE id = #{id}
</select>

• With mapUnderscoreToCamelCase, user_name maps to userName. Otherwise use a column alias user_name AS userName or ResultMap.

Example 2: ResultMap — column names differ from properties

XMLCopy
<resultMap id="UserMap" type="User">
  <id column="id" property="id"/>
  <result column="user_name" property="userName"/>
  <result column="created_at" property="createdAt"/>
</resultMap>
<select id="selectById" resultMap="UserMap">
  SELECT id, user_name, created_at FROM user WHERE id = #{id}
</select>

• Explicit column-to-property mapping; does not depend on global config.

Example 3: ResultMap — nested object (one-to-one)

XMLCopy
<resultMap id="OrderWithUser" type="Order" autoMapping="true">
  <id column="order_id" property="id"/>
  <association property="user" javaType="User" autoMapping="true">
    <id column="user_id" property="id"/>
  </association>
</resultMap>
<select id="selectOrderWithUser" resultMap="OrderWithUser">
  SELECT o.id AS order_id, o.amount, u.id AS user_id, u.user_name
  FROM orders o JOIN user u ON o.user_id = u.id WHERE o.id = #{id}
</select>

• One row maps to an Order with a nested User. Use distinct aliases (order_id, user_id) to avoid column clashes.

Example 4: ResultMap — collection (one-to-many)

XMLCopy
<resultMap id="OrderWithItems" type="Order" autoMapping="true">
  <id column="order_id" property="id"/>
  <collection property="items" ofType="OrderItem" autoMapping="true">
    <id column="item_id" property="id"/>
  </collection>
</resultMap>
<select id="selectOrderWithItems" resultMap="OrderWithItems">
  SELECT o.id AS order_id, o.amount, i.id AS item_id, i.product_id, i.qty
  FROM orders o LEFT JOIN order_item i ON i.order_id = o.id WHERE o.id = #{id}
</select>

• Multiple rows with the same order_id are grouped into one Order with a List<OrderItem>. Avoids N+1 (see N+1 Query).

Example 5: Comparison

Need	Use	Notes
Single table, columns match	ResultType	Simplest
Column names differ	ResultMap	Explicit column→property
Nested object/collection, multi-table JOIN	ResultMap	association / collection
Reuse, extend, discriminator	ResultMap	extend, discriminator

Core Mechanism / Behavior

• ResultType: MyBatis creates one instance per row and sets properties by column name (or camelCase). Cannot express "this column belongs to a nested object" or "multiple rows form a collection."
• ResultMap: Builds objects from <id>, <result>, <association>, and <collection>. Rows with the same parent id are grouped and collections are filled. Requires unique aliases for parent/child columns.

Key Rules

• Use ResultType for simple single-table mappings. Use ResultMap for nesting, collections, or column mismatch.
• With ResultMap, use distinct aliases (e.g. order_id, item_id) and correct column attributes to avoid assembly errors.
• One-to-many: use collection with a single JOIN or two queries (IN) to avoid N+1. One-to-one: use association.

What's Next

See N+1 Query for collection usage. See Dynamic SQL for reusing ResultMap with different conditions.