SQL 标签

文档标签主要由以下构成：

<select> 标签，用于配置 SELECT 语句。
<update> 标签、<delete> 标签，用于配置 UPDATE 和 DELETE 语句。
<insert> 标签，用于配置 INSERT 语句。
<selectKey> 标签，在 <insert> 标签内可以使用 <selectKey> 标签执行额外查询并回填主键。
<execute> 标签，可以用来执行任意的 SQL 语句。
<sql> 标签，定义 SQL 片段。

命令执行

这些标签也可以承载数据源的原生命令，不要求命令必须是 SQL。加载 Mapper 文件后，可通过 namespace.statementId 调用其中的语句；用法见调用文件 Mapper。

执行选项

statementType 选择执行方式，timeout 设置超时，fetchSize 提供读取批次提示，resultSetType 选择结果集类型。查询默认使用预编译语句；需要滚动结果时，驱动也必须支持相应的 resultSetType。

各标签可配置的属性见下文。fetchSize 是读取批次提示，不是返回记录的总数限制。

select 标签

<select> 标签等同于 @Query 注解，用于配置 SELECT 语句，对于简单的情况只需要具体的 SQL 语句即可。例如:

例1：简单案例
<select id="queryListByAge">
    select * from users where age = #{age}
</select>

例2：使用 resultType 属性将查询结果映射到类型
<select id="queryById" resultType="com.example.dto.UserBean">
    select 
        id, name, age, create_time
    from
        users
    where
        id = #{id}
</select>

标签属性

属性名	描述
id	必选用于标识查询命令。
statementType	可选表示查询类型，表示 JDBC 查询使用何种方式。默认值为 `PREPARED` - `STATEMENT` 对应 `java.sql.Statement` - `PREPARED` 对应 `java.sql.PreparedStatement` - `CALLABLE` 对应 `java.sql.CallableStatement`
timeout	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setQueryTimeout(int)` 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 `-1`
fetchSize	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setFetchSize(int)`，用于为 JDBC 驱动程序提供一个提示。它提示此查询生成的 ResultSet 对象需要更多行时应该从数据库获取的行数。默认值是 `256`
resultMap	可选引用 <resultMap> 或 <entity> 标签配置的映射。 - 可以使用 `resultMap` 和 `resultType` 其中一个属性但不应同时使用它们。如果都没有配置将会参照映射的接口返回值类型决定。
resultType	可选将返回的预期类型的完全限定类名或类型别名。提示：在集合的情况下，这应该是集合的元素类型，而不是集合本身的类型。 - 可以使用 `resultMap` 和 `resultType` 其中一个属性但不应同时使用它们。如果都没有配置将会参照映射的接口返回值类型决定。
resultSetType	可选当通过 `java.sql.Connection` 创建查询 statement 时候，该值决定了 `resultSetType` 参数的具体值。 - 可选值列表： `FORWARD_ONLY`、`SCROLL_INSENSITIVE`、`SCROLL_SENSITIVE` 和 `DEFAULT`。默认值为 `DEFAULT` 相当于未设置。 - statementType 为 `STATEMENT` 时对应 `java.sql.Connection.createStatement(int, int)` 方法第一个参数。 - statementType 为 `PREPARED` 时对应 `java.sql.Connection.prepareStatement(java.lang.String, int, int)`方法第二个参数。 - statementType 为 `CALLABLE` 时对应 `java.sql.Connection.prepareCall(java.lang.String, int, int)`方法第二个参数。
resultSetExtractor	可选可为查询配置一个 ResultSetExtractor 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
resultRowCallback	可选可为查询配置一个 RowCallbackHandler 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
resultRowMapper	可选可为查询配置一个 RowMapper 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
resultTypeHandler	可选可为该方法配置一个 TypeHandler 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
bindOut	可选当 Query 中使用了多值或者存储过程调用，使用 bindOut 参数可以绑定其中的输出参数。请注意：一旦使用了该参数那么接口返回值类型必须为 Map<String,Object> 类型。

存储过程调用

调用存储过程时设置 statementType="CALLABLE"，通过参数中的 mode 声明 IN、OUT 或 INOUT，使用 bindOut 选择输出。输出参数及游标的写法见存储过程调用。数据库和 JDBC 驱动需要提供对应能力。

update 和 delete 标签

<update> 标签等同于 @Update 注解、<delete> 标签等同于 @Delete 注解。用于配置对应的 UPDATE、DELETE 语句。

<update id="updateAge">
    update users set age = #{age} where id = #{id}
</update>

<delete id="deleteById">
    delete from users where id = #{id}
</delete>

标签属性

属性名	描述
id	必选用于标识查询命令
statementType	可选表示查询类型，表示 JDBC 查询使用何种方式。默认值为 `PREPARED` - `STATEMENT` 对应 `java.sql.Statement` - `PREPARED` 对应 `java.sql.PreparedStatement` - `CALLABLE` 对应 `java.sql.CallableStatement`
timeout	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setQueryTimeout(int)` 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 `-1`

insert 标签

<insert> 标签等同于 @Insert 注解，用于配置对应的 INSERT 语句。

<insert id="insertUser">
    insert into users (
        id,    name,    age,    create_time
    ) values (
        #{id}, #{name}, #{age}, #{createTime}
    )
</insert>

标签属性

属性名	描述
id	必选用于标识查询命令
statementType	可选表示查询类型，表示 JDBC 查询使用何种方式。默认值为 `PREPARED` - `STATEMENT` 对应 `java.sql.Statement` - `PREPARED` 对应 `java.sql.PreparedStatement` - `CALLABLE` 对应 `java.sql.CallableStatement`
timeout	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setQueryTimeout(int)` 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 `-1`
useGeneratedKeys	可选是否使用自增属性。如果同时配置了 SelectKey 标签该配置将会失效。
keyProperty	可选当 useGeneratedKeys 设置为 true 后，用于回填自增后属性值的 Bean 属性名。如果同时配置了 SelectKey 注解该属性将会失效。
keyColumn	可选当 useGeneratedKeys 设置为 true 后，回填自增属性值时候选择的查询结果列名。如果同时配置了 SelectKey 注解该属性将会失效。

主键策略

手工赋值：在 INSERT 中直接绑定调用方提供的主键。
生成键回填：使用 useGeneratedKeys、keyProperty、keyColumn 接收数据库返回的生成键。
查询后回填：使用 selectKey 标签，在 INSERT 前或后执行查询，将结果写回参数属性。

<insert> 可以通过 useGeneratedKeys、keyProperty、keyColumn 声明主键回填。不同数据库的主键返回方式差异较大，具体用法请阅读数据源特性。Generated keys 的通用说明见 Generated Keys。

selectKey 标签

<selectKey> 标签需要和 <insert> 标签一起才能工作，它等同于 @SelectKeySql 注解。

新增数据后的后续逻辑经常需要使用新记录的主键。可以使用 <selectKey> 标签执行额外的主键查询，由框架回填参数对象，无需业务代码手动查询和赋值。另外有些业务需要自定义数据表的主键，这个时候也可以使用 <selectKey> 标签来实现，它可以随意的设置生成主键的方式。

以下 MySQL 示例使用字符串 UUID，要求 id 为可容纳 36 个字符的字符串列和 Java 字符串属性。

<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>

标签属性

属性名	描述
keyProperty	必选用于回填自增后属性值的 Bean 属性名。
keyColumn	可选用于回填自增属性值时候选择的查询结果列名。
order	必选可以选择 Before 或者 After，表示用于获取自增主键的 SQL 执行时机是在 INSERT 操作之前还是之后。
statementType	可选表示查询类型，表示 JDBC 查询使用何种方式。默认值为 `PREPARED` - `STATEMENT` 对应 `java.sql.Statement` - `PREPARED` 对应 `java.sql.PreparedStatement` - `CALLABLE` 对应 `java.sql.CallableStatement`
timeout	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setQueryTimeout(int)` 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 `-1`
fetchSize	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setFetchSize(int)`，用于为 JDBC 驱动程序提供一个提示。它提示此查询生成的 ResultSet 对象需要更多行时应该从数据库获取的行数。默认值是 `256`
resultSetType	可选当通过 `java.sql.Connection` 创建查询 statement 时候，该值决定了 `resultSetType` 参数的具体值。 - 可选值列表： `FORWARD_ONLY`、`SCROLL_INSENSITIVE`、`SCROLL_SENSITIVE` 和 `DEFAULT`。默认值为 `DEFAULT` 相当于未设置。 - statementType 为 `STATEMENT` 时对应 `java.sql.Connection.createStatement(int, int)` 方法第一个参数。 - statementType 为 `PREPARED` 时对应 `java.sql.Connection.prepareStatement(java.lang.String, int, int)`方法第二个参数。 - statementType 为 `CALLABLE` 时对应 `java.sql.Connection.prepareCall(java.lang.String, int, int)`方法第二个参数。

execute 标签

<execute> 标签等同于 @Execute 注解。用于配置任意 SQL 语句。

<execute id="updateAge">
    update users set age = #{age} where id = #{id}
</execute>

标签属性

属性名	描述
id	必选用于标识查询命令
statementType	可选表示查询类型，表示 JDBC 查询使用何种方式。默认值为 `PREPARED` - `STATEMENT` 对应 `java.sql.Statement` - `PREPARED` 对应 `java.sql.PreparedStatement` - `CALLABLE` 对应 `java.sql.CallableStatement`
timeout	可选通过设置一个大于 `0` 时会被设置到 `java.sql.Statement.setQueryTimeout(int)` 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 `-1`
bindOut	可选对输出参数进行过滤，用来确定哪些结果参数会被接收，如果不指定将会接收所有参数。请注意：一旦使用了该参数那么接口返回值类型必须为 Map<String,Object> 类型。

sql 标签

此标签可用于定义一段 SQL 并在同一个 Mapper 文件内进行引用，从而减少重复的 SQL 片段，例如：定义列名。

<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>

标签属性

属性名	描述
id	必选用于标识片段名称。

命令执行​

执行选项​

select 标签​

标签属性​

存储过程调用​

update 和 delete 标签​

标签属性​

insert 标签​

标签属性​

主键策略​

selectKey 标签​

标签属性​

execute 标签​

标签属性​

sql 标签​

标签属性​

命令执行

执行选项

select 标签

标签属性

存储过程调用

update 和 delete 标签

标签属性

insert 标签

标签属性

主键策略

selectKey 标签

标签属性

execute 标签

标签属性

sql 标签

标签属性