Fields (OLAP)

[Table of Contents](https://github.com/dell-oss/Doradus/wiki/OLAP Databases: Table-of-Contents) | Previous | Next
OLAP Data Model: Fields

---

All fields other than `_ID` are user-defined. Every field has a _type_, which determines the type of values it holds. Field types fall into three categories: _scalar_, _link_, and _group_.

Scalar Fields

Scalar fields store simple data such as numbers or text. A single-valued (SV) scalar field stores a single value per object. Multi-valued (MV) scalar fields, also called scalar collections, can store multiple values per object. The scalar field types supported by Doradus are summarized below:

• Text: An arbitrary length string of Unicode characters.
• Boolean: A logical true or false value.
• Integer and Long: A signed 64-bit integer value. These two types are synonyms.
• Float: A 32-bit floating-point value.
• Double: A 64-bit floating-point value.
• Timestamp: A date/time value with millisecond precision. Doradus treats all timestamp values as occurring in the UTC time zone. Timestamp values must be given in the format:

yyyy-MM-dd HH:mm:ss.SSS

where:

• yyyy is a 4-digit year between 0000 and 9999
• MM is a 1- or 2-digit month between 1 and 12
• dd is a 1- or 2-digit day-of-month between 1 and 31
• HH is a 1- or 2-digit hour between 0 and 23
• mm is a 1- or 2-digit minute between 0 and 59
• ss is a 1- or 2-digit second between 0 and 59
• SSS is a 1-to-3 digit millisecond between 0 and 999

Only the year component is required. All other components can be omitted (along with their preceding separator character) in right-to-left order. Omitted time elements default to 0; omitted date elements default to 1. Hence, the following timestamp values are all valid:

2011-02-01 08:50:01.123

2011-02-01 08:50:01	    // same as 2011-02-01 08:50:01.000

2011-02-01 08:50	      // same as 2011-02-01 08:50:00.000

2011-02-01 08			 // same as 2011-02-01 08:00:00.000

2011-02-01			    // same as 2011-02-01 00:00:00.000

2011-02				   // same as 2011-02-01 00:00:00.000

2011				     // same as 2011-01-01 00:00:00.000

• Binary: An arbitrary length sequence of bytes. A binary field definition includes an encoding (Base64 or Hex) that defines how values are encoded when sent to or returned by Doradus.

When type names are used in schema definitions, they are case-insensitive (e.g., integer or INTEGER). Example field definitions in XML are shown below:

<fields>
	<field name="SendDate" type="TIMESTAMP"/>
	<field name="Size" type="INTEGER"/>
	<field name="Subject" type="TEXT"/>
	<field name="IsInternal" type="BOOLEAN"/>
</fields>

By default, scalar fields are SV. Assigning an SV scalar field for an existing object replaces the existing value, if present. A scalar field can be declared MV by setting its collection property to true. Example:

<field name="Tags" collection="true" type="TEXT"/>

MV scalar field values are added and removed individually and treated as a set: duplicate values are not stored. This preserves idempotent update semantics: adding the same value twice is a no-op.

Link Fields

Link fields are pointers that create inter-object relationships. All relationships are bi-directional, therefore every link has an inverse link that defines the same relationship from the opposite direction. A link and its inverse link can be in the same table or they can reside in different tables. An example link declaration in XML is shown below:

<table name="Participant">
	<fields>
		<field name="MessageAddress" table="Address" type="LINK" inverse="Messages"/>
		...
	</fields>
</table>

In this example, the link field MessageAddress is owned by the Participant table and points to the Address table, whose inverse link is called Messages. The table to which a link points is called the link's extent.

Link fields are always MV: the collection property, if set, is ignored. A link's values are IDs of objects that belong to its extent table. Relationships are created or deleted by adding IDs to or removing IDs from the link field. Like MV scalar fields, link values are sets, hence duplicates are ignored.

Because relationships are bi-directional, when a link is updated, its inverse link is automatically updated at the same time. For example, if an object ID is added to MessageAddress, connecting the owning participant object to a specific Address object, the Messages link for that address object is updated to point back to the same participant.

One side-effect of this referential integrity behavior is that objects can be implicitly created: if an object ID is added to MessageAddress and the corresponding person doesn't exist, it is created. An implicitly-created object will only have an \_ID and automatically-updated link field value(s).

If a link's owner and extent are the same table, the relationship is reflexive. An example reflexive relationship is the Manager/DirectReports relationship in the Person table:

<table name="Person">
	<fields>
		<field name="DirectReports" table="Person" type="LINK" inverse="Manager"/>
		<field name="Manager" table="Person" type="LINK" inverse="DirectReports"/>
		...
	</fields>
</table>

A link can also be its own inverse: such relationships are called self-reflexive. For example, we could define spouse and friends as self-reflexive relationships (though some may argue friendship is not always reciprocal).

Group Fields

A group field is a named field that contains one or more other fields. The contained fields are called nested fields and may be scalar, link, or group fields. The group field itself does not hold any values; values are stored by the contained leaf scalar and link fields. Note that all field names within a table must be unique, even for those contained within a group field. An example group field is shown below:

<table name="Person">
	<fields>                    <!-- fields belonging to Person -->
		<field name="Location">
			<fields>             <!-- fields belong to Location -->
				<field name="Department" type="TEXT"/>
				<field name="Office" type="TEXT"/>
			</fields>
		</field>
		...
	</fields>
</table>

Here, the group field Location contains the nested text fields Department and Office. In a query, the values of both nested fields are returned when the group field Location is requested. Below is another example consisting of link fields:

<table name="Message">
	<fields>
		<field name="Participants">
			<fields>
				<field name="Sender" type="LINK" table="Participant" inverse="MessageAsSender"/>
				<field name="Recipients">
					<fields>
						<field name="ExternalRecipients" type="link" table="Participant" inverse="MessageAsExternalRecipient"/>
						<field name="InternalRecipients" type="link" table="Participant" inverse="MessageAsInternalRecipient"/>
					</fields>
				</field>
			</fields>
		</field>
		...
	</fields>
</table>

In this example, the group field Participants contains a link called Sender and a nested group called Recipients, which has two additional links ExternalRecipients and InternalRecipients. The values of all three link fields can be retrieved by requesting the Participants in a query.