Hint

This article is generated by AI translation.

@Query Annotation

Marks an interface method to execute a query that returns a result set.

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: query a user list

@SimpleMapper
public interface UserMapper {
    @Query("select * from users where id > #{id}")    // 1. SQL definition
    List<User> listUsers(@Param("id") long searchId); // 2. id argument, User return type
}

Pagination

Add a Page pagination argument to the method parameters to enable pagination (Page can appear at any position in the parameter list).

Return List

@SimpleMapper
public interface UserMapper {
    @Query("select * from users where id > #{id}")
    List<User> listUsers(@Param("id") long searchId, Page page);
}

Return PageResult (with total count and total pages)

@SimpleMapper
public interface UserMapper {
    @Query("select * from users where id > #{id}")
    PageResult<User> listUsers(@Param("id") long searchId, Page page);
}

• PageResult includes the data list as well as original paging info, total count, and total pages.

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.
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.
resultSetExtractor	可选 Optionally configure a ResultSetExtractor for result processing. Ignored if bindOut is set.
resultRowCallback	可选 Optionally configure a RowCallbackHandler for per-row processing. Ignored if bindOut is set.
resultRowMapper	可选 Optionally configure a RowMapper for result set processing. Ignored if bindOut is set.
resultTypeHandler	可选 Optionally configure a TypeHandler. Ignored if bindOut is set.
bindOut	可选 When using Multiple Results or Stored Procedure, bindOut lets you bind output arguments. Once configured, the method return type must be Map<String,Object>.