Hint

This article is generated by AI translation.

@Query Annotation

Marks an interface method and accepts a string or string array that represents a result-producing query.

info

If you pass a string array, the elements are concatenated with a single space between them.
This makes it easy to manage SQL in a readable way.

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 argument anywhere in the method signature to enable pagination.

Use Page to paginate

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

Use PageResult to capture paging metadata

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

• PageResult includes the original paging request, 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. 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>.