Document Tags

Document tags consist of the following:

<select>: configure SELECT.
<update> / <delete>: configure UPDATE and DELETE.
<insert>: configure INSERT.
<selectKey>: inside <insert> to execute an additional key query and fill the key property.
<execute>: run arbitrary SQL.
<sql>: define reusable SQL fragments.

Command Execution

These tags also accept native datasource commands, not only SQL. After loading a Mapper file, invoke its statements by namespace.statementId; see Call File Mapper.

Execution Options

statementType selects the execution style, timeout sets the timeout, fetchSize provides a fetch-size hint, and resultSetType selects the result-set type. Queries use prepared statements by default. Scrollable results also require driver support for the requested resultSetType.

The available attributes for each tag are listed below. fetchSize is a fetch-size hint, not a limit on the total number of returned records.

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	Required Identifier for the statement.
statementType	Optional How JDBC executes the query. Default `PREPARED`. - `STATEMENT` → `java.sql.Statement` - `PREPARED` → `java.sql.PreparedStatement` - `CALLABLE` → `java.sql.CallableStatement`
timeout	Optional If >0 sets `java.sql.Statement.setQueryTimeout(int)` in seconds. Default `-1`.
fetchSize	Optional If >0 sets `java.sql.Statement.setFetchSize(int)` as a hint for how many rows to fetch per round trip. Default `256`.
resultMap	Optional 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	Optional 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	Optional 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	Optional Configure a ResultSetExtractor for result handling (ignored if `bindOut` is set).
resultRowCallback	Optional Configure a RowCallbackHandler for result handling (ignored if `bindOut` is set).
resultRowMapper	Optional Configure a RowMapper for result handling (ignored if `bindOut` is set).
resultTypeHandler	Optional Configure a TypeHandler for result handling (ignored if `bindOut` is set).
bindOut	Optional Bind output params when using Multiple Results or Stored Procedures. Requires mapper return type Map<String,Object>.

Stored Procedure Calls

Set statementType="CALLABLE" for stored procedures. Declare IN, OUT, or INOUT with the parameter's mode, and use bindOut to select outputs. See Stored Procedure Calls for output and cursor syntax. The database and JDBC driver must support the requested capability.

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	Required Identifier for the statement.
statementType	Optional JDBC execution style. Default `PREPARED`. - `STATEMENT` → `java.sql.Statement` - `PREPARED` → `java.sql.PreparedStatement` - `CALLABLE` → `java.sql.CallableStatement`
timeout	Optional 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	Required Identifier for the statement.
statementType	Optional JDBC execution style. Default `PREPARED`. - `STATEMENT` → `java.sql.Statement` - `PREPARED` → `java.sql.PreparedStatement` - `CALLABLE` → `java.sql.CallableStatement`
timeout	Optional If >0 sets `java.sql.Statement.setQueryTimeout(int)` in seconds. Default `-1`.
useGeneratedKeys	Optional Whether to use JDBC generated keys. Ignored if `SelectKeySql`/`@SelectKey` is also configured.
keyProperty	Optional Bean property to fill when `useGeneratedKeys` is true. Ignored if `@SelectKey` is configured.
keyColumn	Optional Result-set column used when `useGeneratedKeys` is true. Ignored if `@SelectKey` is configured.

Key Strategies

Assigned keys: bind a caller-supplied key directly in INSERT.
Generated keys: use useGeneratedKeys, keyProperty, and keyColumn to receive keys returned by the database.
Query-based keys: use selectKey before or after INSERT to query a value and fill the parameter property.

Use useGeneratedKeys, keyProperty, and keyColumn on <insert> to configure key backfill. Key-return behavior differs across databases; see Data Source Differences for specific usage and Generated Keys for general configuration.

selectKey tag

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

<selectKey> executes an additional query and fills the parameter object's key property, so application code does not need to query and assign it manually. It also supports custom key generation.

The following MySQL example generates a UUID string; id must be a string column that holds 36 characters and a Java String property.

<insert id="insertUser">
    <selectKey keyProperty="id" order="BEFORE">
        SELECT UUID()
    </selectKey>
    insert into `test_user` (
        `id`, `name`, `age`, `create_time`
    ) values (
        #{id}, #{name}, #{age}, #{createTime}
    )
</insert>

Attributes

Property	Description
keyProperty	Required Bean property to receive the generated key.
keyColumn	Optional Column name used to read the generated key.
order	Required `BEFORE` or `AFTER`: when to run the key SQL relative to the INSERT.
statementType	Optional JDBC execution style. Default `PREPARED`. - `STATEMENT` → `java.sql.Statement` - `PREPARED` → `java.sql.PreparedStatement` - `CALLABLE` → `java.sql.CallableStatement`
timeout	Optional If >0 sets `java.sql.Statement.setQueryTimeout(int)` in seconds. Default `-1`.
fetchSize	Optional If >0 sets `java.sql.Statement.setFetchSize(int)` as a hint for how many rows to fetch per round trip. Default `256`.
resultSetType	Optional 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	Required Identifier for the statement.
statementType	Optional JDBC execution style. Default `PREPARED`. - `STATEMENT` → `java.sql.Statement` - `PREPARED` → `java.sql.PreparedStatement` - `CALLABLE` → `java.sql.CallableStatement`
timeout	Optional If >0 sets `java.sql.Statement.setQueryTimeout(int)` in seconds. Default `-1`.
bindOut	Optional 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	Required Identifier for the fragment.

Command Execution​

Execution Options​

select tag​

Attributes​

Stored Procedure Calls​

update and delete tags​

Attributes​

insert tag​

Attributes​

Key Strategies​

selectKey tag​

Attributes​

execute tag​

Attributes​

sql tag​

Attributes​

Command Execution

Execution Options

select tag

Attributes

Stored Procedure Calls

update and delete tags

Attributes

insert tag

Attributes

Key Strategies

selectKey tag

Attributes

execute tag

Attributes

sql tag

Attributes