Hint

This article is generated by AI translation.

@Insert Annotation

Marks an interface method to execute an INSERT statement.

info

If you pass a string array, the elements are concatenated with a single space between them.
String arrays make it easy to manage multi-line SQL.

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

Sometimes you need the generated primary key immediately after inserting a row for subsequent business logic. @SelectKeySql allows executing an additional SQL before or after the INSERT to retrieve the key value and write it back to the parameter object.

This annotation must be used together with @Insert.

Example: retrieve MySQL auto-increment ID after INSERT

//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 retrieve the auto-increment ID and write it back to the id property
    @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(); // Auto-increment ID has been written back

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.