Hint

This article is generated by AI translation.

@Insert Annotation

Marks an interface method and accepts a string or string array that represents an INSERT statement.

Example: insert a user record

@SimpleMapper
public interface UserMapper {
    @Insert({ "insert into users (",                       // 1. SQL definition
              "    id, name, age, create_time",            //
              ") values (",                                //
              "    #{id}, #{name}, #{age}, #{createTime})",//
              ")" })
    int saveUser(UserDTO user);                             // 2. User object argument
}

Properties

Property	Description
value	必选 SQL to execute.
statementType	可选 Determines which JDBC statement type to use. Default is PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If set to a value greater than 0, the value is applied to java.sql.Statement.setQueryTimeout(int) to enforce a timeout in seconds. Default is -1.
useGeneratedKeys	可选 Whether to use auto-generated keys. If @SelectKeySql is also present, this flag is ignored.
keyProperty	可选 When useGeneratedKeys is true, specifies the bean property to receive the generated key. Ignored if @SelectKeySql is present.
keyColumn	可选 When useGeneratedKeys is true, specifies the result-set column whose value is written back. Ignored if @SelectKeySql is present.

Tip

If keyColumn is empty, the first column of the returned result set is used.

@SelectKeySql Annotation

Description

Sometimes you need the generated primary key immediately after inserting a row. @SelectKeySql lets you fetch the auto-increment value (or generate a custom key) without issuing a separate query. Use it together with @Insert.

Example: insert a user record

//create table users (
//  id          bigint auto_increment primary key,
//  name        varchar(255),
//  age         int,
//  create_time datetime
//);

@SimpleMapper
public interface UserMapper {
    @Insert({ "insert into users (",                // 1. SQL definition
              "    name, age, create_time",         //
              ") values (",                         //
              "    #{name}, #{age}, #{createTime})",//
              ")" })
    // After the insert executes, use MySQL last_insert_id() to fetch the generated id
    @SelectKeySql(value = "select last_insert_id()", keyProperty = "id", order = Order.After)
    int saveUser(UserDTO user);
}

UserMapper mapper = ...;
UserDTO user = ...

mapper.saveUser(user);

long afterId = user.getId();

Properties

Property	Description
value	必选 SQL that retrieves the generated key.
keyProperty	必选 Bean property that receives the generated key.
keyColumn	可选 Result-set column whose value is written back.
order	必选 Whether the key SQL runs Before or After the INSERT.
statementType	可选 Determines which JDBC statement type to use. Default is PREPARED. - STATEMENT → java.sql.Statement - PREPARED → java.sql.PreparedStatement - CALLABLE → java.sql.CallableStatement
timeout	可选 If set to a value greater than 0, the value is applied to java.sql.Statement.setQueryTimeout(int) to enforce a timeout in seconds. Default is -1.
fetchSize	可选 If set to a value greater than 0, the value is applied to java.sql.Statement.setFetchSize(int) as a hint to the JDBC driver. Default is 256.
resultSetType	可选 Controls the resultSetType argument when the statement is created. Options: FORWARD_ONLY, SCROLL_INSENSITIVE, SCROLL_SENSITIVE, DEFAULT (no override). - For STATEMENT, maps to Connection.createStatement(int, int) argument 1. - For PREPARED, maps to Connection.prepareStatement(String, int, int) argument 2. - For CALLABLE, maps to Connection.prepareCall(String, int, int) argument 2.