Ordered_union_data

Relational functions ordered_union_data

syntax

definition

ordered_union_data(domain unit, a, b, .. n) is the variant of Union_data with which the modeller states that all values of all unioned attributes are non-decreasing: monotone increasing, but not strictly, so equal successive values are allowed.

Apart from that statement the result is the same as that of Union_data: a new Attribute with as Domain unit the first Argument (domainunit), containing the values of the data items a, b, .., n.

description

The statement is about the concatenation, not about each argument separately: within each argument the values must not descend, and the last value of each argument must not exceed the first value of the next argument.

The GeoDMS records the stated order on the resulting attribute and uses it to skip work that is only needed for unordered data: functions such as Rlookup and Unique and the counting of values then take a sorted-merge path instead of first building a sort index.

Because a wrong statement would not raise an error further downstream but would silently produce wrong results, the stated order is verified when the result is calculated. As soon as a value is found that is less than its predecessor, the calculation fails with a data error that reports where the descent occurs and which two values are involved, for example:

ordered_union_data: the concatenation of the argument values is not non-decreasing.
Element 3 of the result, which is element 0 of argument 3: /ZHCity/limit, has value 20, which is less than the value 250 of its predecessor.
Use union_data if the values of the arguments are not guaranteed to be ordered.

Use Union_data when the values are not known to be ordered.

The GeoDMS also generates ordered_union_data itself: the calculation rule that it derives for an attribute whose values are already known to be sorted unions the individual values with ordered_union_data rather than with Union_data, so that the sortedness survives storing and restoring that rule. Such generated rules can show up in the Calculation rule of an item in the Detail pages.

applies to

  • Unit domainunit with Value type from the group CanBeDomainUnit
  • data items a, b, … n with a numeric value type: uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32 or float64

Unlike Union_data, ordered_union_data is not available for point, sequence, bool, uint2, uint4 and string value types; use Union_data for those.

conditions

  • The values unit of data items a, b, … n must match.
  • The concatenation of the values of a, b, … n must be non-decreasing; each value must be greater than or equal to its predecessor.

performance

O(n₁ + n₂ + … + nₖ) where nᵢ = number of elements in data item i, the same single pass as Union_data, with one extra comparison per element for the order check.

When ordered_union_data is called with a single data item that already has the resulting domain unit, Union_data adopts that data item without reading it; ordered_union_data reads it once to verify the stated order.

example 

unit<uint32> HollandLimit := union_unit(NHLimit, ZHLimit)
{
   attribute<uint32> limit := ordered_union_data(., NHLimit/limit, ZHLimit/limit);
}
HollandLimit/limit
0
100
250
250
1000

domain HollandLimit, nr of rows = 5

NHLimit/limit
0
100
250

domain NHLimit, nr of rows = 3

ZHLimit/limit
250
1000

domain ZHLimit, nr of rows = 2

Note that the value 250 occurs twice in a row, across the boundary of the two arguments: that is allowed, as the required order is non-decreasing and not strictly increasing. Had ZHLimit/limit started with 20 instead of 250, the calculation of HollandLimit/limit would have failed with the error shown above.

see also