Result Maps

Parameter Maps and Inline parameters map object properties to parameters in a database query. Result Maps finish the job by mapping the result of a database query (a set of columns) to object properties. Next to Mapped Statements, the Result Map is probably one of the most commonly used and most important features to understand.

A Result Map lets you control how data is extracted from the result of a query, and how the columns are mapped to object properties. A Result Map can describe the column type, a null value replacement, and complex property mappings including Collections. The following example shows the structure of a <resultMap> element.

<resultMap id="resultMapIdentifier"
           [class="class.name"]
           [extends="[sqlMapNamespace.]resultMapId"]>

   <result property="propertyName"
           column="columnName"
           [columnIndex="columnIndex"]
           [dbType="databaseType"]
           [type="propertyCLRType"]
           [resultMapping="resultMapName"]
           [nullValue="nullValueReplacement"]
           [select="someOtherStatementName"]
           [lazyLoad="true|false"]
           [typeHandler="class.name"]
   />
   <result ... .../>
   <result ... .../>
</resultMap>

In the above example, the [brackets] indicate optional attributes. The id attribute is required and provides a name for the statement to reference. The class attribute is also required, and specifies the full name of a PHP class. This is the class that will be instantiated and populated based on the result mappings it contains.

The resultMap can contain any number of property mappings that map object properties to the columns of a result element. The property mappings are applied, and the columns are read, in the order that they are defined. Maintaining the element order ensures consistent results between different drivers and providers.

Extending resultMaps

The optional extends attribute can be set to the name of another resultMap upon which to base this resultMap. All properties of the "parent" resultMap will be included as part of this resultMap, and values from the "parent" resultMap are set before any values specified by this resultMap. The effect is similar to extending a class.