Nullable Database Fields

eXtremeDB supports nullable fields, i.e. fields that have no value. Fields that are declared nullable have a null indicator associated with them which, when set, indicates that the field has no value. When a value is assigned the null indicator is cleared to indicate that the field now has a value.

C API

For C and C++ applications, APIs are generated to allow setting and clearing this null indicator. If a scalar class element (int, float, double) has been declared nullable in the database schema, the following interfaces are generated:

 
    MCO_RET classname_fieldname_indicator_get( classname *handle, uint1 *result );
     

The argument ‘result’ will have a value of 0 upon return if the field is null, otherwise ‘result’ will be 1.

     
    MCO_RET  classname_fieldname_indicator_put( classname *handle, uint1 value);
     

Pass a ‘value’ of 1 to set the null indicator, 0 to clear the null indicator.

Note that setting or clearing the null indicator has no effect on the underlying field’s value. In other words, if a nullable uint2 field has a value of 5 and classname_fieldname_indicator_put( h, 1 ) is called for the field, it will still have a value of 5 after the call.

For fields of all types, the respective forms of classname_fieldname_get() can return MCO_S_NULL_VALUE. classname_fixed_get() can also return MCO_S_NULL_VALUE, indicating that one or more constituent fields are null; a further examination with classname_fieldname_indicator_get() will be necessary to determine which fields are null.

Note also that nulls are not included into indexes. In other words, if a nullable field is indexed, and an object of the class has the null indicator set to true for that field, that object will not be included in the index. This is true whether the field is a simple index, or participates as one element in a compound index.

Therefore, take care that there is some other access method other than through an index on the nullable fields. For example, given:

 
    class xyz 
    {
        nullable uint4 avalue;
         
        tree<avalue> by_avalue;
    };
     

Any objects of class xyz with the null indicator set for avalue will be inaccessible. As soon as the null indicator is set and the transaction committed, the object will be removed from the index. With no other access method to locate the object, it becomes inaccessible.