Hint

This article is generated by AI translation.

Doc Elements

in mapper XML is built from these elements:

• <select>: configure SELECT.
• <update> / <delete>: configure UPDATE and DELETE.
• <insert>: configure INSERT.
• <selectKey>: inside <insert> to fetch generated keys without another query.
• <execute>: run arbitrary SQL.
• <sql>: define reusable SQL fragments.

select tag

<select> equals @Query. For simple cases just write the SQL:

Example 1: simple

<select id="queryListByAge">
    select * from users where age = #{age}
</select>

Example 2: map results via resultType

<select id="queryById" resultType="com.example.dto.UserBean">
    select 
        id, name, age, create_time
    from
        users
    where
        id = #{id}
</select>

Attributes

Property	Description
id	必选 Identifier for the statement.
statementType	可选 How JDBC executes the query. Default PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If >0 sets java.sql.Statement.setQueryTimeout(int) in seconds. Default -1.
fetchSize	可选 If >0 sets java.sql.Statement.setFetchSize(int) as a hint for how many rows to fetch per round trip. Default 256.
resultMap	可选 Reference a mapping defined by <resultMap> or <entity>. Use either resultMap or resultType, not both. If neither is set, the mapper method return type is used.
resultType	可选 Fully qualified type or type alias for the result. For collections, use the element type, not the collection. Use either resultMap or resultType, not both. If neither is set, the mapper method return type is used.
resultSetType	可选 Value passed as resultSetType when creating the statement. Options: FORWARD_ONLY, SCROLL_INSENSITIVE, SCROLL_SENSITIVE, DEFAULT (default). - With STATEMENT: maps to Connection.createStatement(int, int) first arg. - With PREPARED: maps to Connection.prepareStatement(String, int, int) second arg. - With CALLABLE: maps to Connection.prepareCall(String, int, int) second arg.
resultSetExtractor	可选 Configure a ResultSetExtractor for result handling (ignored if bindOut is set).
resultRowCallback	可选 Configure a RowCallbackHandler for result handling (ignored if bindOut is set).
resultRowMapper	可选 Configure a RowMapper for result handling (ignored if bindOut is set).
resultTypeHandler	可选 Configure a TypeHandler for result handling (ignored if bindOut is set).
bindOut	可选 Bind output params when using Multiple Results or Stored Procedures. Requires mapper return type Map<String,Object>.

update and delete tags

<update> equals @Update; <delete> equals @Delete. Configure UPDATE / DELETE SQL.

<update id="updateAge">
    update users set age = #{age} where id = #{id}
</update>

<delete id="deleteById">
    delete from users where id = #{id}
</delete>

Attributes

Property	Description
id	必选 Identifier for the statement.
statementType	可选 JDBC execution style. Default PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If >0 sets java.sql.Statement.setQueryTimeout(int) in seconds. Default -1.

insert tag

<insert> equals @Insert to configure INSERT.

<insert id="insertUser">
    insert into users (
        id,    name,    age,    create_time
    ) values (
        #{id}, #{name}, #{age}, #{createTime}
    )
</insert>

Attributes

Property	Description
id	必选 Identifier for the statement.
statementType	可选 JDBC execution style. Default PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If >0 sets java.sql.Statement.setQueryTimeout(int) in seconds. Default -1.
useGeneratedKeys	可选 Whether to use JDBC generated keys. Ignored if SelectKeySql/@SelectKey is also configured.
keyProperty	可选 Bean property to fill when useGeneratedKeys is true. Ignored if @SelectKey is configured.
keyColumn	可选 Result-set column used when useGeneratedKeys is true. Ignored if @SelectKey is configured.

selectKey tag

<selectKey> works with <insert>, same as @SelectKeySql.

Use <selectKey> to fetch generated keys (or custom-generated keys) without an extra query when inserting.

<insert id="insertUser">
    <selectKey keyProperty="id" resultType="int" order="BEFORE">
        SELECT CONCAT('1', CEILING(RAND() * 1000 + 1000))
    </selectKey>
    insert into `test_user` (
        `id`, `name`, `age`, `create_time`
    ) values (
        #{id}, #{name}, #{age}, #{createTime}
    )
</insert>

Attributes

Property	Description
keyProperty	必选 Bean property to receive the generated key.
keyColumn	可选 Column name used to read the generated key.
order	必选 BEFORE or AFTER: when to run the key SQL relative to the INSERT.
statementType	可选 JDBC execution style. Default PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If >0 sets java.sql.Statement.setQueryTimeout(int) in seconds. Default -1.
fetchSize	可选 If >0 sets java.sql.Statement.setFetchSize(int) as a hint for how many rows to fetch per round trip. Default 256.
resultSetType	可选 Value passed as resultSetType when creating the statement. Options: FORWARD_ONLY, SCROLL_INSENSITIVE, SCROLL_SENSITIVE, DEFAULT (default). - With STATEMENT: maps to Connection.createStatement(int, int) first arg. - With PREPARED: maps to Connection.prepareStatement(String, int, int) second arg. - With CALLABLE: maps to Connection.prepareCall(String, int, int) second arg.

execute tag

<execute> equals @Execute and runs arbitrary SQL.

<execute id="updateAge">
    update users set age = #{age} where id = #{id}
</execute>

Attributes

Property	Description
id	必选 Identifier for the statement.
statementType	可选 JDBC execution style. Default PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If >0 sets java.sql.Statement.setQueryTimeout(int) in seconds. Default -1.
bindOut	可选 Filter output arguments; only the specified ones are accepted. If set, mapper return type must be Map<String,Object>.

sql tag

Define SQL fragments and reuse them in the same mapper file (e.g., column lists).

<sql id="testuser_columns">
    name,age,create_time
</sql>

<insert id="insertUser">
    insert into `test_user` (
        <include refid="testuser_columns"/>
    ) values (
        #{name}, #{age}, now()
    )
</insert>

Attributes

Property	Description
id	必选 Identifier for the fragment.