MyBatis(3.2.3) - Dynamic SQL

Sometimes, static SQL queries may not be sufficient for application requirements. We may have to build queries dynamically, based on some criteria.
For example, in web applications there could be search screens that provide one or more input options and perform searches based on the chosen criteria. While implementing this kind of search functionality, we may need to build a dynamic query based on the selected options. If the user provides any value for input criteria, we'll need to add that field in the WHERE clause of the query.

MyBatis provides first-class support for building dynamic SQL queries using elements such as <if>, <choose>, <where>, <foreach>, and <trim>.

The If condition

The <if> element can be used to conditionally embed SQL snippets. If the test condition is evaluated to true, then only the SQL snippet will be appended to the query.

Assume we have a Search Courses Screen that has a Tutor dropdown, the CourseName text field, and the StartDate and End Date input fields as the search criteria.

Assume that Tutor is a mandatory field and that the rest of the fields are optional.

When the user clicks on the search button, we need to display a list of courses that meet the following criteria:

• Courses by the selected Tutor
• Courses whose name contain the entered course name; if nothing has been provided, fetch all the courses
• Courses whose start date and end date are in between the provided StartDate and EndDate input fields

We can create the mapped statement for searching the courses as follows:

<resultMap type="Course" id="CourseResult">
    <id column="course_id" property="courseId"/>
    <result column="name" property="name"/>
    <result column="description" property="description"/>
    <result column="start_date" property="startDate"/>
    <result column="end_date" property="endDate"/>
</resultMap>
<select id="searchCourses" parameterType="hashmap" resultMap="CourseResult">
<![CDATA[
    SELECT * FROM COURSES WHERE TUTOR_ID = #{tutorId}
    <if test="courseName != null">
        AND NAME LIKE #{courseName}
    </if>
    <if test="startDate != null">
        AND START_DATE >= #{startDate}
    </if>
    <if test="endDate != null">
        AND END_DATE <= #{endDate}
    </if>
]]>
</select>

public interface CourseMapper {
    List<Course> searchCourses(Map<String, Object> map);
}

public void searchCourses() {
    Map<String, Object> map = new HashMap<String, Object>();
    map.put("tutorId", 1);
    map.put("courseName", "%java%");
    map.put("startDate", new Date());
    CourseMapper mapper = sqlSession.getMapper(CourseMapper.class);
    List<Course> courses = mapper.searchCourses(map);
    for (Course course : courses) {
        System.out.println(course);
    }
}

This will generate the query SELECT * FROM COURSES WHERE TUTOR_ID= ? AND NAME like ? AND START_DATE >= ?. This will come in handy while preparing a dynamic SQL query based on the given criteria.

MyBatis uses OGNL (Object Graph Navigation Language) expressions for building dynamic queries.

The choose, when, and otherwise conditions

Sometimes, search functionality could be based on the search type. First, the user needs to choose whether he wants to search by Tutor or Course Name or Start Dates and End Dates, and then based on the selected search type, the input field will appear. In such scenarios, we should apply only one of the conditions. MyBatis provides the <choose> element to support this kind of dynamic SQL preparation.

Now let us write a SQL mapped statement to get the courses by applying the search criteria. If no search criteria is selected, the courses starting from today onwards should be fetched as follows:

<select id="searchCourses" parameterType="hashmap" resultMap="CourseResult">
    SELECT * FROM COURSES
    <choose>
        <when test="searchBy == 'Tutor'">
            WHERE TUTOR_ID= #{tutorId}
        </when>
        <when test="searchBy == 'CourseName'">
            WHERE name like #{courseName}
        </when>
        <otherwise>
            WHERE TUTOR start_date &gt;= now()
        </otherwise>
    </choose>
</select>

MyBatis evaluates the <choose> test conditions and uses the clause with the first condition that evaluates to TRUE. If none of the conditions are true, the <otherwise> clause will be used.

The where condition

At times, all the search criteria might be optional. In cases where at least one of the search conditions needs to be applied, then only the WHERE clause should be appended. Also, we need to append AND or OR to the conditions only if there are multiple conditions. MyBatis provides the <where> element to support building these kinds of dynamic SQL statements.

In the example Search Courses screen, we assume that all the search criteria is optional. So, the WHERE clause should be there only if any of the search criteria has been provided.

<select id="searchCourses" parameterType="hashmap" resultMap="CourseResult">
    SELECT * FROM COURSES
    <where>
        <if test=" tutorId != null ">
            TUTOR_ID= #{tutorId}
        </if>
        <if test="courseName != null">
            AND name like #{courseName}
        </if>
        <if test="startDate != null">
            AND start_date &gt;= #{startDate}
        </if>
        <if test="endDate != null">
            AND end_date &lt;= #{endDate}
        </if>
    </where>
</select>

The <where> element inserts WHERE only if any content is returned by the inner conditional tags. Also, it removes the AND or OR prefixes if the WHERE clause begins with AND or OR.

In the preceding example, if none of the <if> conditions are True, <where> won't insert the WHERE clause. If at least one of the <if> conditions is True, <where> will insert the WHERE clause followed by the content returned by the <if> tags.

If the tutor_id parameter is null and the courseName parameter is not null, <where> will take care of stripping out the AND prefix and adding NAME like #{courseName}.

The trim condition

The <trim> element works similar to <where> but provides additional flexibility on what prefix/suffix needs to be prefixed/suffixed and what prefix/suffix needs to be stripped off.

<select id="searchCourses" parameterType="hashmap" resultMap="CourseResult">
    SELECT * FROM COURSES
    <trim prefix="WHERE" prefixOverrides="AND | OR">
        <if test="tutorId != null">
            TUTOR_ID= #{tutorId}
        </if>
        <if test="courseName != null">
            AND name like #{courseName}
        </if>
    </trim>
</select>

Here <trim> will insert WHERE if any of the <if> conditions are true and remove the AND or OR prefixes just after WHERE.

The foreach loop

Another powerful dynamic SQL builder tag is <foreach>. It is a very common requirement for iterating through an array or list and for building AND/OR conditions or an IN clause.

Suppose we want to find out all the courses taught by the tutors whose tutor_id IDs are 1, 3, and 6. We can pass a list of tutor_id IDs to the mapped statement and build a dynamic query by iterating through the list using <foreach>.

<select id="searchCoursesByTutors" parameterType="map" resultMap="CourseResult">
    SELECT * FROM COURSES
    <if test="tutorIds != null">
        <where>
            <foreach item="tutorId" collection="tutorIds">
                OR tutor_id=#{tutorId}
            </foreach>
        </where>
    </if>
</select>

public interface CourseMapper {
    List<Course> searchCoursesByTutors(Map<String, Object> map);
}

public void searchCoursesByTutors() {
    Map<String, Object> map = new HashMap<String, Object>();
    List<Integer> tutorIds = new ArrayList<Integer>();
    tutorIds.add(1);
    tutorIds.add(3);
    tutorIds.add(6);
    map.put("tutorIds", tutorIds);
    CourseMapper mapper =
    sqlSession.getMapper(CourseMapper.class);
    List<Course> courses = mapper.searchCoursesByTutors(map);
    for (Course course : courses) {
        System.out.println(course);
    }
}

Let us see how to use <foreach> to generate the IN clause:

<select id="searchCoursesByTutors" parameterType="map" resultMap="CourseResult">
    SELECT * FROM COURSES
    <if test="tutorIds != null">
        <where>
            tutor_id IN
            <foreach item="tutorId" collection="tutorIds" open="(" separator="," close=")">
                #{tutorId}
            </foreach>
        </where>
    </if>
</select>

The set condition

The <set> element is similar to the <where> element and will insert SET if any content is returned by the inner conditions.

<update id="updateStudent" parameterType="Student">
    update students
    <set>
        <if test="name != null">name=#{name},</if>
        <if test="email != null">email=#{email},</if>
        <if test="phone != null">phone=#{phone},</if>
    </set>
    where stud_id=#{id}
</update>

Here, <set> inserts the SET keyword if any of the <if> conditions return text and also strips out the tailing commas at the end.

In the preceding example, if phone != null, <set> will take care of removing the comma after phone=#{phone}.