All XML mappings should declare the XML namespace shown. The actual schema definition may be found in the src\nhibernate-mapping.xsd file in the NHibernate distribution.

Tip: to enable IntelliSense for mapping and configuration files, copy the appropriate .xsd files as part of any project in your solution, (Build Action can be "None") or as "Solution Files" or in your "Lib" folder and then add it to the Schemas property of the xml file. You can copy it in <VS installation directory>\Xml\Schemas, take care because you will have to deal with different version of the xsd for different versions of NHibernate.

This element has several optional attributes. The schema and catalog attributes specify that tables referred to by this mapping belong to the named schema and/or catalog. If they are specified, table names will be qualified by the given schema and/or catalog name. If they are missing, table names will be unqualified. The default-cascade attribute specifies what cascade style should be assumed for properties and collections which do not specify a cascade attribute. The auto-import attribute lets us use unqualified class names in the query language, by default. The assembly and namespace attributes specify the assembly where persistent classes are located and the namespace they are declared in.

<hibernate-mapping
    schema="schemaName"                               (1)
    catalog="catalogName"                             (2)
    default-cascade="none|save-update..."             (3)
    auto-import="true|false"                          (4)
    assembly="Eg"                                     (5)
    namespace="Eg"                                    (6)
    default-access="field|property|field.camelcase..."(7)
    default-lazy="true|false"                         (8)
 />

If you are not using assembly and namespace attributes, you have to specify fully-qualified class names, including the name of the assembly that classes are declared in.

If you have two persistent classes with the same (unqualified) name, you should set auto-import="false". NHibernate will throw an exception if you attempt to assign two classes to the same "imported" name.

The hibernate-mapping element allows you to nest several persistent <class> mappings, as shown above. It is, however, good practice to map only a single persistent class, or a single class hierarchy, in one mapping file and name it after the persistent super-class. For example, Cat.hbm.xml, Dog.hbm.xml, or if using inheritance, Animal.hbm.xml.

You may declare a persistent class using the class element:

<class
    name="className"                                  (1)
    table="tableName"                                 (2)
    discriminator-value="discriminatorValue"          (3)
    mutable="true|false"                              (4)
    schema="owner"                                    (5)
    catalog="catalog"                                 (6)
    proxy="proxyInterface"                            (7)
    dynamic-update="true|false"                       (8)
    dynamic-insert="true|false"                       (9)
    select-before-update="true|false"                 (10)
    polymorphism="implicit|explicit"                  (11)
    where="arbitrary sql where condition"             (12)
    persister="persisterClass"                        (13)
    batch-size="N"                                    (14)
    optimistic-lock="none|version|dirty|all"          (15)
    lazy="true|false"                                 (16)
    abstract="true|false"                             (17)
    entity-name="entityName"                          (18)
    check="arbitrary sql check condition"             (19)
    subselect="SQL expression"                        (20)
    schema-action="none|drop|update|export|validate|all|commaSeparatedValues"  (21)
    rowid="unused"                                    (22)
    node="unused"                                     (23)
/>

It is perfectly acceptable for the named persistent class to be an interface. You would then declare implementing classes of that interface using the <subclass> element. You may persist any inner class. You should specify the class name using the standard form ie. Eg.Foo+Bar, Eg. Due to an HQL parser limitation inner classes can not be used in queries in NHibernate, unless assigning to them an entity-name without the + character.

Changes to immutable classes, mutable="false", will not be persisted. This allows NHibernate to make some minor performance optimizations.

The optional proxy attribute enables customization of the generated proxy for lazy initialization of persistent instances of the class: by default, the proxy derives from the class. Specifying an interface causes the proxy to implement it and to use System.Object as its base class. This enables proxifying a sealed class or a class having non virtual members. The specified interface should declare all the public members of the persistent class. On ISession.Load and on many-to-one associations, NHibernate will initially return proxies. The actual persistent object will be loaded when a method or property of the proxy is invoked. See Section 21.1.4, “Initializing collections and proxies”.

Implicit polymorphism means that instances of the class will be returned by a query that names any superclass or implemented interface or the class and that instances of any subclass of the class will be returned by a query that names the class itself. Explicit polymorphism means that class instances will be returned only be queries that explicitly name that class and that queries that name the class will return only instances of subclasses mapped inside this <class> declaration as a <subclass> or <joined-subclass>. For most purposes the default, polymorphism="implicit", is appropriate. Explicit polymorphism is useful when two different classes are mapped to the same table (this allows a "lightweight" class that contains a subset of the table columns).

The persister attribute lets you customize the persistence strategy used for the class. You may, for example, specify your own subclass of NHibernate.Persister.EntityPersister or you might even provide a completely new implementation of the interface NHibernate.Persister.IClassPersister that implements persistence via, for example, stored procedure calls, serialization to flat files or LDAP. See NHibernate.DomainModel.CustomPersister for a simple example (of "persistence" to a Hashtable).

Note that the dynamic-update and dynamic-insert settings are not inherited by subclasses and so may also be specified on the <subclass> or <joined-subclass> elements. These settings may increase performance in some cases, but might actually decrease performance in others. Use judiciously.

Use of select-before-update will usually decrease performance. It is very useful to prevent a database update trigger being called unnecessarily if you reattach a graph of detached instances to an ISession.

If you enable dynamic-update, you will have a choice of optimistic locking strategies:

We very strongly recommend that you use version/timestamp columns for optimistic locking with NHibernate. This is the optimal strategy with respect to performance and is the only strategy that correctly handles modifications made outside of the session (ie. when ISession.Update() is used).

Beginning with NHibernate 1.2.0, version numbers start with 1, not 0 as in previous versions. This was done to allow using 0 as unsaved-value for the version property.

An alternative to mapping a class to table or view columns is to map a query. For that, we use the <subselect> element, which is mutually exclusive with <subclass>, <joined-subclass> and <union-subclass>. The subselect may also be specified as a <class> attribute. The content of the subselect element is a SQL query:

<subselect>
    <![CDATA[
    SELECT cat.ID, cat.NAME, cat.SEX, cat.MATE FROM cat
    ]]>
</subselect>

Usually, when mapping a query using subselect you will want to mark the class as not mutable (mutable="false"), unless you specify custom SQL for performing the UPDATE, DELETE and INSERT operations.

Also, it makes sense to force synchronization of the tables affected by the query, using one or more <synchronize> entries:

<subselect>
    <![CDATA[
    SELECT cat.ID, cat.NAME, cat.SEX, cat.MATE FROM cat
    ]]>
</subselect>
<synchronize table="cat"/>

This ensures that auto-flush happens correctly and that queries against the derived entity do not return stale data.

You then still have to declare the class id and properties.

Mapped classes must declare the primary key column of the database table. Most classes will also have a property holding the unique identifier of an instance. The <id> element defines the mapping from that property to the primary key column.

<id
    name="propertyName"                               (1)
    type="typeName"                                   (2)
    length="typeLength"                               (3)
    column="columnName"                               (4)
    unsaved-value="any|none|null|undefined|idValue"   (5)
    access="field|property|nosetter|className"        (6)
    generator="generatorClass">                       (7)

    <generator class="generatorClass"/>
</id>

If the name attribute is missing, it is assumed that the class has no identifier property.

The unsaved-value attribute is almost never needed in NHibernate.

There is an alternative <composite-id> declaration to allow access to legacy data with composite keys. We strongly discourage its use for anything else.

<id name="Id" type="Int64" column="uid">
    <generator class="NHibernate.Id.TableHiLoGenerator">
        <param name="table">uid_table</param>
        <param name="column">next_hi_value_column</param>
    </generator>
</id>

<id name="Id" type="Int64" column="uid" generator="native" />

<id name="Id" type="Int64" column="cat_id">
    <generator class="hilo">
        <param name="table">tableName</param>
        <param name="column">columnName</param>
        <param name="schema">schemaName</param>
        <param name="catalog">catalogName</param>
        <param name="max_lo">100</param>
        <param name="where">arbitraryWhereClause</param>
    </generator>
</id>

<id name="Id" type="Int64" column="cat_id">
    <generator class="seqhilo">
        <param name="sequence">hi_value</param>hibernate_sequence
        <param name="schema">schemaName</param>
        <param name="catalog">catalogName</param>
        <param name="max_lo">100</param>
        <param name="parameters">arbitrarySqlFragment</param>
    </generator>
</id>

<id name="Id" type="String" column="cat_id">
    <generator class="uuid.hex">
        <param name="format">format_value</param>
        <param name="separator">separator_value</param>
    </generator>
</id>

<id name="Id" type="Int64" column="uid">
    <generator class="sequence">
        <param name="sequence">uid_sequence</param>
    </generator>
</id>

<id name="Id" type="Int64" column="uid">
    <generator class="identity"/>
</id>

<id name="id" type="long" column="person_id">
    <generator class="select">
        <param name="key">socialSecurityNumber</param>
    </generator>
</id>

<composite-id
    name="propertyName"
    class="className"
    unsaved-value="any|none"
    access="field|property|nosetter|className"
    mapped="true|false">

    <key-property name="propertyName" type="typeName" column="columnName"/>
    <key-many-to-one name="propertyName class="className" column="columnName"/>
    ...
</composite-id>

For a table with a composite key, you may map multiple properties of the class as identifier properties. The <composite-id> element accepts <key-property> property mappings and <key-many-to-one> mappings as child elements.

<composite-id>
    <key-property name="MedicareNumber"/>
    <key-property name="Dependent"/>
</composite-id>

Your persistent class must override Equals() and GetHashCode() to implement composite identifier equality. It must also be marked with the Serializable attribute.

Unfortunately, this approach to composite identifiers means that a persistent object is its own identifier. There is no convenient "handle" other than the object itself. You must instantiate an instance of the persistent class itself and populate its identifier properties before you can Load() the persistent state associated with a composite key. We call this approach an embedded composite identifier, and discourage it for serious applications.

A much more convenient approach is to implement the composite identifier as a separate class, as in Section 8.4, “Components as composite identifiers”. The attributes described below apply only to this alternative approach:

The second approach, an identifier component, is recommended for almost all applications.

The <discriminator> element is required for polymorphic persistence using the table-per-class-hierarchy mapping strategy and declares a discriminator column of the table. The discriminator column contains marker values that tell the persistence layer what subclass to instantiate for a particular row. A restricted set of types may be used: String, Char, Int32, Byte, Short, Boolean, YesNo, TrueFalse.

<discriminator
    column="discriminatorColumn"                      (1)
    type="discriminatorType"                          (2)
    length="typeLength"                               (3)
    not-null="true|false"                             (4)
    force="true|false"                                (5)
    insert="true|false"                               (6)
    formula="arbitrary SQL expression"                (7)
/>

Actual values of the discriminator column are specified by the discriminator-value attribute of the <class> and <subclass> elements.

The force attribute is only useful if the table contains rows with "extra" discriminator values that are not mapped to a persistent class. This will not usually be the case.

Using the formula attribute, you can declare an arbitrary SQL expression that will be used to evaluate the type of a row:

<discriminator
    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
    type="Int32"/>

The <version> element is optional and indicates that the table contains versioned data. This is particularly useful if you plan to use long transactions (see Section 12.4, “Optimistic concurrency control”).

<version
    column="versionColumn"                            (1)
    name="propertyName"                               (2)
    type="typeName"                                   (3)
    access="field|property|nosetter|className"        (4)
    unsaved-value="null|negative|undefined|value"     (5)
    generated="never|always"                          (6)
    insert="false|true"                               (7)
/>

Version may be of type Int64, Int32, Int16, Ticks, Timestamp, TimeSpan, datetimeoffset, ... (or their nullable counterparts in .NET 2.0 and higher). Any type implementing IVersionType is usable as a version.

The optional <timestamp> element indicates that the table contains timestamped data. This is intended as an alternative to versioning. Timestamps are by nature a less safe implementation of optimistic locking. However, sometimes the application might use the timestamps in other ways.

<timestamp
    column="timestampColumn"                          (1)
    name="propertyName"                               (2)
    access="field|property|nosetter|className"        (3)
    unsaved-value="null|undefined"                    (4)
    generated="never|always"                          (5)
    source="vm|db"                                    (6)
/>

Note that <timestamp> is equivalent to <version type="datetime">, and <timestamp source="db"> is equivalent to <version type="dbtimestamp">.

The <property> element declares a persistent property of the class.

<property
    name="propertyName"                               (1)
    column="columnName"                               (2)
    type="typeName"                                   (3)
    update="true|false"                               (4)
    insert="true|false"                               (4)
    formula="arbitrary SQL expression"                (5)
    access="field|property|className"                 (6)
    optimistic-lock="true|false"                      (7)
    generated="never|insert|always"                   (8)
    lazy="true|false"                                 (9)
    not-null="true|false"                             (10)
    unique="true|false"                               (11)
    unique-key="uniqueKeyName"                        (12)
    index="indexName"                                 (13)
    length="L"                                        (14)
    precision="P"                                     (15)
    scale="S"                                         (16)
/>

typeName could be:

Note that you have to specify full assembly-qualified names for all except basic NHibernate types (unless you set assembly and/or namespace attributes of the <hibernate-mapping> element).

NHibernate supports .NET 2.0 Nullable types. These types are mostly treated the same as plain non-Nullable types internally. For example, a property of type Nullable<Int32> can be mapped using type="Int32" or type="System.Int32".

If you do not specify a type, NHibernate will use reflection upon the named property to take a guess at the correct NHibernate type. NHibernate will try to interpret the name of the return class of the property getter using rules 2, 3, 4 in that order. However, this is not always enough. In certain cases you will still need the type attribute. (For example, to distinguish between NHibernateUtil.DateTime and NHibernateUtil.UtcDateTime, or to specify a custom type.)

See also Section 5.2, “NHibernate Types”.

The access attribute lets you control how NHibernate will access the value of the property at runtime. The value of the access attribute should be text formatted as access-strategy.naming-strategy. The .naming-strategy is not always required.

A powerful feature is derived properties. These properties are by definition read-only. The property value is computed at load time. You declare the computation as an SQL expression. This then translates to a SELECT clause subquery in the SQL query that loads an instance:

<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>

You can reference the entity table by not declaring an alias on a particular column. This would be customerId in the given example. You can also use the nested <formula> mapping element if you do not want to use the attribute.

The nested <column> mapping element can also be used instead of the column attribute.

An ordinary association to another persistent class is declared using a many-to-one element. The relational model is a many-to-one association. (It is really just an object reference.)

<many-to-one
    name="propertyName"                                    (1)
    column="columnName"                                    (2)
    class="className"                                      (3)
    cascade="all|none|save-update|delete|delete-orphan|all-(4)delete-orphan"
    fetch="join|select"                                    (5)
    lazy="proxy|no-proxy|false"                            (6)
    update="true|false"                                    (7)
    insert="true|false"                                    (7)
    property-ref="propertyNameFromAssociatedClass"         (8)
    access="field|property|nosetter|className"             (9)
    optimistic-lock="true|false"                           (10)
    not-found="ignore|exception"                           (11)
    entity-name="entityName"                               (12)
    formula="arbitrary SQL expression"                     (13)
    not-null="true|false"                                  (14)
    unique="true|false"                                    (15)
    unique-key="uniqueKeyName"                             (16)
    index="indexName"                                      (17)
    foreign-key="foreignKeyName"                           (18)
    outer-join="auto|true|false"                           (19)
/>

Setting a value of the cascade attribute to any meaningful value other than none will propagate certain operations to the associated object. The meaningful values are divided into three categories. First, basic operations, which include: persist, merge, delete, save-update, evict, replicate, lock and refresh; second, special values: delete-orphan; and third, all comma-separated combinations of operation names: cascade="persist,merge,evict" or cascade="all,delete-orphan". See Section 10.10, “Lifecycles and object graphs”.

Here is an example of a typical many-to-one declaration:

<many-to-one name="product" class="Product" column="PRODUCT_ID"/>

The property-ref attribute should only be used for mapping legacy data where a foreign key refers to a unique key of the associated table other than the primary key. This is a complicated and confusing relational model. For example, if the Product class had a unique serial number that is not the primary key, mapped as below:

<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>

The unique attribute controls NHibernate's DDL generation with the SchemaExport tool. Then the mapping for OrderItem might use:

<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>

This is not encouraged, however.

If the referenced unique key comprises multiple properties of the associated entity, you should map the referenced properties inside a named <properties> element.

If the referenced unique key is the property of a component, you can specify a property path:

<many-to-one name="owner" property-ref="Identity.Ssn" column="OWNER_SSN"/>

A one-to-one association to another persistent class is declared using a one-to-one element.

<one-to-one
    name="propertyName"                                    (1)
    class="className"                                      (2)
    cascade="all|none|save-update|delete|delete-orphan|all-(3)delete-orphan"
    constrained="true|false"                               (4)
    fetch="join|select"                                    (5)
    lazy="proxy|no-proxy|false"                            (6)
    property-ref="propertyNameFromAssociatedClass"         (7)
    access="field|property|nosetter|className"             (8)
    formula="any SQL expression"                           (9)
    entity-name="entityName"                               (10)
    foreign-key="foreignKeyName"                           (11)
/>

There are two varieties of one-to-one association:

Primary key associations don't need an extra table column; if two rows are related by the association then the two table rows share the same primary key value. So if you want two objects to be related by a primary key association, you must make sure that they are assigned the same identifier value!

For a primary key association, add the following mappings to Employee and Person, respectively.

<one-to-one name="Person" class="Person"/>

<one-to-one name="Employee" class="Employee" constrained="true"/>

Now we must ensure that the primary keys of related rows in the PERSON and EMPLOYEE tables are equal. We use a special NHibernate identifier generation strategy called foreign:

<class name="Person" table="PERSON">
    <id name="Id" column="PERSON_ID">
        <generator class="foreign">
            <param name="property">Employee</param>
        </generator>
    </id>
    ...
    <one-to-one name="Employee"
        class="Employee"
        constrained="true"/>
</class>

A newly saved instance of Person is then assigned the same primary key value as the Employee instance referred with the Employee property of that Person.

Alternatively, a foreign key with a unique constraint, from Employee to Person, may be expressed as:

<many-to-one name="Person" class="Person" column="PERSON_ID" unique="true"/>

And this association may be made bidirectional by adding the following to the Person mapping:

<one-to-one name="Employee" class="Employee" property-ref="Person"/>

<natural-id mutable="true|false"/>
    <property ... />
    <many-to-one ... />
    ...
</natural-id>

Even though we recommend the use of surrogate keys as primary keys, you should still try to identify natural keys for all entities. A natural key is a property or combination of properties that is unique and non-null. If it is also immutable, even better. Map the properties of the natural key inside the <natural-id> element. NHibernate will generate the necessary unique key and nullability constraints, and your mapping will be more self-documenting.

The <natural-id> element can only appear before the other properties, including version.

We strongly recommend that you implement Equals() and GetHashCode() to compare the natural key properties of the entity.

This mapping is not intended for use with entities with natural primary keys.

The <component> element maps properties of a child object to columns of the table of a parent class. Components may, in turn, declare their own properties, components or collections. See Chapter 8, Component Mapping.

<component
    name="propertyName"                                    (1)
    class="className"                                      (2)
    insert="true|false"                                    (3)
    update="true|false"                                    (4)
    access="field|property|nosetter|className"             (5)
    optimistic-lock="true|false"                           (6)
    lazy="true|false"                                      (7)
    unique="true|false">                                   (8)

        <property ... />
        <many-to-one ... />
        ...
</component>

The child <property> tags map properties of the child class to table columns.

The <component> element allows a <parent> sub-element that maps a property of the component class as a reference back to the containing entity.

The <dynamic-component> element allows an IDictionary, IDictionary<string, object>, or a C# dynamic to be mapped as a component. When using dictionaries, the property names refer to keys of the dictionary. See Section 8.5, “Dynamic components”.

The <properties> element allows the definition of a named, logical grouping of the properties of a class. The most important use of the construct is that it allows a combination of properties to be the target of a property-ref. It is also a convenient way to define a multi-column unique constraint. For example:

<properties
    name="logicalName"                                     (1)
    insert="true|false"                                    (2)
    update="true|false"                                    (3)
    optimistic-lock="true|false"                           (4)
    unique="true|false">                                   (5)

    <property .../>
    <many-to-one .../>
    ...
</properties>

For example, if we have the following <properties> mapping:

<class name="Person">
    <id name="personNumber" />
    <properties name="name" unique="true" update="false">
        <property name="firstName" />
        <property name="lastName" />
        <property name="initial" />
    </properties>
</class>

You might have some legacy data association that refers to this unique key of the Person table, instead of to the primary key:

<many-to-one name="owner" class="Person" property-ref="name">
    <column name="firstName" />
    <column name="lastName" />
    <column name="initial" />
</many-to-one>

The use of this outside the context of mapping legacy data is not recommended.

Polymorphic persistence requires the declaration of each subclass of the root persistent class. For the (recommended) table-per-class-hierarchy mapping strategy, the <subclass> declaration is used.

<subclass
    name="className"                                  (1)
    discriminator-value="discriminatorValue"          (2)
    extends="superclassName"                          (3)
    ...>                                              (4)

    <property ... />
    <properties ... />
    ...
</subclass>

Each subclass should declare its own persistent properties and subclasses. <version> and <id> properties are assumed to be inherited from the root class. Each subclass in a hierarchy must define a unique discriminator-value. If none is specified, the fully qualified .NET class name is used.

For information about inheritance mappings, see Chapter 9, Inheritance Mapping.

Each subclass can also be mapped to its own table. This is called the table-per-subclass mapping strategy. An inherited state is retrieved by joining with the table of the superclass. To do this you use the <joined-subclass> element.

<joined-subclass
    name="className"                                  (1)
    table="tableName"                                 (2)
    extends="superclassName"                          (3)
    ...>                                              (4)

    <key ... />

    <property ... />
    <properties ... />
    ...
</joined-subclass>

No discriminator column is required for this mapping strategy. Each subclass must, however, declare a table column holding the object identifier using the <key> element. The mapping at the start of the chapter would be re-written as:

<?xml version="1.0"?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="Eg"
    namespace="Eg">

    <class name="Cat" table="CATS">
        <id name="Id" column="uid" type="Int64">
            <generator class="hilo"/>
        </id>
        <property name="BirthDate" type="Date"/>
        <property name="Color" not-null="true"/>
        <property name="Sex" not-null="true"/>
        <property name="Weight"/>
        <many-to-one name="Mate"/>
        <set name="Kittens">
            <key column="MOTHER"/>
            <one-to-many class="Cat"/>
        </set>
        <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
            <key column="CAT"/>
            <property name="Name" type="String"/>
        </joined-subclass>
    </class>

    <class name="Dog">
        <!-- mapping for Dog could go here -->
    </class>

</hibernate-mapping>

For information about inheritance mappings, see Chapter 9, Inheritance Mapping.

A third option is to map only the concrete classes of an inheritance hierarchy to tables, (the table-per-concrete-class strategy) where each table defines all persistent state of the class, including inherited state. In NHibernate, it is not absolutely necessary to explicitly map such inheritance hierarchies. You can simply map each class with a separate <class> declaration. However, if you wish use polymorphic associations (e.g. an association to the superclass of your hierarchy), you need to use the <union-subclass> mapping.

<union-subclass
    name="className"                                  (1)
    table="tableName"                                 (2)
    extends="superclassName"                          (3)
    ...>                                              (4)

    <property ... />
    <properties ... />
    ...
</union-subclass>

No discriminator column or key column is required for this mapping strategy.

For information about inheritance mappings, see Chapter 9, Inheritance Mapping.

Using the <join> element, it is possible to map properties of one class to several tables, when there's a 1-to-1 relationship between the tables.

<join
    table="tableName"                            (1)
    schema="owner"                               (2)
    catalog="catalog"                            (3)
    fetch="join|select"                          (4)
    inverse="true|false"                         (5)
    optional="true|false"                        (6)
    subselect="SQL expression">                  (7)

    <key ... />

    <property ... />
    ...
</join>

For example, the address information for a person can be mapped to a separate table (while preserving value type semantics for all properties):

<class name="Person" table="PERSON">
    <id name="id" column="PERSON_ID">...</id>

    <join table="ADDRESS">
        <key column="ADDRESS_ID"/>
        <property name="address"/>
        <property name="zip"/>
        <property name="country"/>
    </join>
    ...

This feature is often only useful for legacy data models, we recommend fewer tables than classes and a fine-grained domain model. However, it is useful for switching between inheritance mapping strategies in a single hierarchy, as explained later.

The <key> element has featured a few times within this guide. It appears anywhere the parent mapping element defines a join to a new table that references the primary key of the original table. It also defines the foreign key in the joined table:

<key
        column="columnName"                      (1)
        on-delete="noaction|cascade"             (2)
        property-ref="propertyName"              (3)
        not-null="true|false"                    (4)
        update="true|false"                      (5)
        unique="true|false"                      (6)
        foreign-key="foreignKeyName"             (7)
/>

For systems where delete performance is important, we recommend that all keys should be defined on-delete="cascade". NHibernate uses a database-level ON CASCADE DELETE constraint, instead of many individual DELETE statements. Be aware that this feature bypasses NHibernate's usual optimistic locking strategy for versioned data.

The not-null and update attributes are useful when mapping an unidirectional one-to-many association. If you map an unidirectional one-to-many association to a non-nullable foreign key, you must declare the key column using <key not-null="true">.

Mapping elements which accept a column attribute will alternatively accept a <column> subelement. Likewise, <formula> is an alternative to the formula attribute. For example:

<column
        name="columnName"
        length="N"
        precision="N"
        scale="N"
        not-null="true|false"
        unique="true|false"
        unique-key="multicolumnUniqueKeyName"
        index="indexName"
        sql-type="sqlTypeName"
        check="SQL expression"
        default="SQL expression"/>

<formula>SQL expression</formula>

Most of the attributes on column provide a means of tailoring the DDL during automatic schema generation. See Section 22.1.1, “Customizing the schema”.

The column and formula elements can even be combined within the same property or association mapping to express, for example, exotic join conditions.

<many-to-one name="HomeAddress" class="Address"
        insert="false" update="false">
    <column name="person_id" not-null="true" length="10"/>
    <formula>'MAILING'</formula>
</many-to-one>

Collections are discussed in Chapter 6, Collection Mapping.

Suppose your application has two persistent classes with the same name, and you don't want to specify the fully qualified name in NHibernate queries. Classes may be "imported" explicitly, rather than relying upon auto-import="true". You may even import classes and interfaces that are not explicitly mapped.

<import class="System.Object" rename="Universe"/>

<import
    class="className"                  (1)
    rename="shortName"                 (2)
/>

There is one more type of property mapping. The <any> mapping element defines a polymorphic association to classes from multiple tables. This type of mapping requires more than one column. The first column contains the type of the associated entity. The remaining columns contain the identifier. It is impossible to specify a foreign key constraint for this kind of association. This is not the usual way of mapping polymorphic associations and you should use this only in special cases. For example, for audit logs, user session data, etc.

<any name="AnyEntity" id-type="long" meta-type="class">
    <column name="type"/>
    <column name="id"/>
</any>

The meta-type attribute allows the application to specify a custom type that maps database column values to persistent classes that have identifier properties of the type specified by id-type. If the meta-type is class, nothing else is required. The class full name will be persisted in the database as the type of the associated entity. On the other hand, if it is a basic type like int or char, you must specify the mapping from values to classes. Here is an example with string.

<any name="being" id-type="long" meta-type="string">
    <meta-value value="ANIMAL_TYPE" class="Animal"/>
    <meta-value value="HUMAN_TYPE" class="Human"/>
    <meta-value value="ALIEN_TYPE" class="Alien"/>
    <column name="type"/>
    <column name="id"/>
</any>

String types are a special case: they can be used without meta-values, in which case they will behave much like the class meta-type.

<any
    name="propertyName"                               (1)
    id-type="idTypeName"                              (2)
    meta-type="metaTypeName"                          (3)
    cascade="cascadeStyle"                            (4)
    access="field|property|className"                 (5)
    optimistic-lock="true|false"                      (6)
    lazy="true|false"                                 (7)
    update="true|false"                               (8)
    insert="true|false"                               (9)
    index="indexName">                                (10)

    <meta-value ... />
    <meta-value ... />
    ...
    <column ... />
    <column ... />
    ...
</any>

Do not confuse <meta-value> elements with <meta> elements. <meta> elements have no functionnal impact on <any>, see Section 5.8, “Meta data” for more information on them.

To understand the behaviour of various .NET language-level objects with respect to the persistence service, we need to classify them into two groups:

An entity exists independently of any other objects holding references to the entity. Contrast this with the usual .NET model where an unreferenced object is garbage collected. Entities must be explicitly saved and deleted (except that saves and deletions may be cascaded from a parent entity to its children). This is different from the ODMG model of object persistence by reachability - and corresponds more closely to how application objects are usually used in large systems. Entities support circular and shared references. They may also be versioned.

An entity's persistent state consists of references to other entities and instances of value types. Values are primitives, collections, components and certain immutable objects. Unlike entities, values (in particular collections and components) are persisted and deleted by reachability. Since value objects (and primitives) are persisted and deleted along with their containing entity they may not be independently versioned. Values have no independent identity, so they cannot be shared by two entities or collections.

All NHibernate types except collections support null semantics if the .NET type is nullable (i.e. not derived from System.ValueType).

Up until now, we've been using the term "persistent class" to refer to entities. We will continue to do that. Strictly speaking, however, not all user-defined classes with persistent state are entities. A component is a user defined class with value semantics.

The challenge is to map the .Net type system, and the developers' definition of entities and value types, to the SQL/database type system. The bridge between both systems is provided by NHibernate. For entities, <class>, <subclass> and so on are used. For value types we use <property>, <component>, etc., that usually have a type attribute. The value of this attribute is the name of a NHibernate mapping type. NHibernate provides a range of mappings for standard .Net value types out of the box. You can write your own mapping types and implement your own custom conversion strategies.

The basic types may be roughly categorized into three groups - System.ValueType types, System.Object types, and System.Object types for large objects. Just like Columns for System.ValueType types can handle null values only if the entity property is properly typed with a Nullable<T>. Otherwise null will be replaced by the default value for the type when reading, and then will be overwritten by it when persisting the entity, potentially leading to phantom updates.

String types use by default .Net default string equality, which is case sensitive and culture insensitive. When a string type is used as an identifier, if the underlying database string equality semantic differs, it may cause issues. For example, loading a children collection by a string parent key stored in a case insensitive column may cause matching children having their parent key differing by the case to be ignored by NHibernate by default.

String types comparer can be set for matching the database or column behavior. To set the default comparer for all string types, affect by code a StringComparer to AbstractStringType.DefaultComparer static property. To set the comparer used only for a specific <property> or <id>, specify its type as a sub-element and supply IgnoreCase and/or ComparerCulture parameters.

<id name="Id" generator="assigned">
    <type name="string">
        <param name="ComparerCulture">en-US</param>   (1)
        <param name="IgnoreCase">true</param>         (2)
    </type>
</id>

If you have many properties to map with these parameters, consider using <typedef>. See Section 5.2.3, “Custom value types” for more information.

These settings should be used in order to match the database or column behavior. They are not taken into account by the hbm2ddl tool for generating the database schema. (In other words, it will not generate matching collate statements for SQL-Server.)

NHibernate supports some additional type names for compatibility with Java's Hibernate (useful for those coming over from Hibernate or using some of the tools to generate hbm.xml files). A type="integer" or type="int" will map to an Int32 NHibernate type, type="short" to an Int16 NHibernateType. To see all of the conversions you can view the source of static constructor of the class NHibernate.Type.TypeFactory.

Default NHibernate types used when no type attribute is specified can be overridden by using the NHibernate.Type.TypeFactory.RegisterType static method before configuring and building session factories.

It is relatively easy for developers to create their own value types. For example, you might want to persist properties of type Int64 to VARCHAR columns. NHibernate does not provide a built-in type for this. But custom types are not limited to mapping a property (or collection element) to a single table column. So, for example, you might have a property Name { get; set; } of type String that is persisted to the columns FIRST_NAME, INITIAL, SURNAME.

To implement a custom type, implement either NHibernate.UserTypes.IUserType or NHibernate.UserTypes.ICompositeUserType and declare properties using the fully qualified name of the type. Check out NHibernate.DomainModel.DoubleStringType to see the kind of things that are possible.

<property name="TwoStrings"
    type="NHibernate.DomainModel.DoubleStringType, NHibernate.DomainModel">
    <column name="first_string"/>
    <column name="second_string"/>
</property>

Notice the use of <column> tags to map a property to multiple columns.

The IEnhancedUserType, IUserVersionType, and IUserCollectionType interfaces provide support for more specialized uses. The later is to be used with collections, see Section 6.1, “Persistent Collections”.

You may even supply parameters to an IUserType in the mapping file. To do this, your IUserType must implement the NHibernate.UserTypes.IParameterizedType interface. To supply parameters to your custom type, you can use the <type> element in your mapping files.

<property name="priority">
    <type name="MyCompany.UserTypes.DefaultValueIntegerType">
        <param name="default">0</param>
    </type>
</property>

The IUserType can now retrieve the value for the parameter named default from the IDictionary object passed to it.

If you use a certain UserType very often, it may be useful to define a shorter name for it. You can do this using the <typedef> element. Typedefs assign a name to a custom type, and may also contain a list of default parameter values if the type is parameterized.

<typedef class="MyCompany.UserTypes.DefaultValueIntegerType" name="default_zero">
    <param name="default">0</param>
</typedef>

<property name="priority" type="default_zero"/>

It is also possible to override the parameters supplied in a typedef on a case-by-case basis by using type parameters on the property mapping.

Even though NHibernate's rich range of built-in types and support for components means you will very rarely need to use a custom type, it is nevertheless considered good form to use custom types for (non-entity) classes that occur frequently in your application. For example, a MonetaryAmount class is a good candidate for an ICompositeUserType, even though it could easily be mapped as a component. One motivation for this is abstraction. With a custom type, your mapping documents would be future-proofed against possible changes in your way of representing monetary values.