The remapResults attribute is available on <statement>, <select>, and <procedure> mapped statements. It is an optional attribute and the default value is false.
The remapResults attribute should be set to true when a query has a variable set of return columns. For example, consider the following queries:
SELECT $fieldList$ FROM table
In this example, the list of column names is dynamic, even though the table is always the same.
SELECT * FROM $someTable$
In this example, the table could be different. Because of the usage of * in the SELECT clause, the resulting columns names could be different, as well.
Since the overhead to introspect the result set metadata is not trivial, iBATIS will remember what was returned the last time the query was run. This could create problems in situations similar to the examples above.
Let's consider what iBATIS will do for the first example depending on the usage of remapResults.
Let's say $fieldList$ is set to "fld1, fld2" the first time the query is executed, thus giving the query:
SELECT fld1, fld2 FROM table
iBATIS will try to be efficient by assuming that fld1 and fld2 will always be in the result set on each subsequent execution of the query. The application will run into trouble if the value for $fieldList$ changes, such as "fld3, fld4". Not only will iBATIS be unable to find fld1 and fld2 in the result set, thus returning improper results, iBATIS won't know about fld3 and fld4 because they weren't in the query on its initial execution.
iBATIS will introspect the result set metadata every time the query is run and will always return the proper results. This feature comes at some performance cost, so only use it if you really need it – when the columns in the result set are variable, either directly, like in the first example, or indirectly, because of a variable table.
Thanks go to Jeff Butler for posting his response on the mailing list, which was the precursor of this document.