C Sequence Functions

eXtremeDB provides a C library for constructing and consuming operations over sequences. The public declarations are in mcoseq.h. Stored sequence fields are opened through generated field functions; generic transformations and analytics operate on mco_seq_iterator_t.

Most iterator-producing functions take a result iterator as their first argument and one or more input iterators after it. The function initializes a lazy pipeline node. It usually does not read all input values or materialize all output values until the result iterator is consumed.

Many function families are generated for specific scalar types. For example, mco_seq_add_int4() adds two int4 input sequences. This documentation uses TYPE as a placeholder for one of the following suffixes:

int1
Signed one-byte integer
int2
Signed two-byte integer
int4
Signed four-byte integer
int8
Signed eight-byte integer
uint1
Unsigned one-byte integer
uint2
Unsigned two-byte integer
uint4
Unsigned four-byte integer
uint8
Unsigned eight-byte integer
float
Four-byte floating point
double
Eight-byte floating point
datetime
Eight-byte datetime

Thus mco_seq_add_TYPE() denotes mco_seq_add_int1(), mco_seq_add_int2(), and the other declared typed variants. The corresponding C value types are the fixed-width mco_TYPE types, for example mco_int4 and mco_datetime. Fixed-width character operations use separate _char functions and carry an element width in the iterator or function arguments.

Not every family supports every suffix, and a function's result type can differ from its input type. For example, comparisons return Boolean values and integer sums use a widened result type. Consult the function-family signature rather than inferring the result type from the input suffix.

See C Sequence Functions by Category for the individual function families.

Fixed-width character fields use a separate set of _char functions. Buffer ownership, custom allocation, binding checks, and hash cleanup are described in Iterator Resources and Global Configuration.

Common Iterator Contract

SQL Equivalents

It is useful to note that all of the public C sequence functions have SQL equivalents. These SQL equivalents return the result sequence which makes it possible to express a "pipeline" of SQL functions in a more compact form. For example, the following pipeline of four C function calls adjusts historical closing prices for the effect of splits. (To understand the code snippet, assume that sequences trade_date and closing_price contain the time series of trade dates paired with closing prices, and split_date contains the sequence of split dates for the trades of interest - for this example "IBM".)

    mco_seq_iterator_t split;
    mco_seq_iterator_t prd_split_factor;
    mco_seq_iterator_t price_adjustment;
    mco_seq_iterator_t trade_date;
    mco_seq_iterator_t split_date;
    mco_seq_iterator_t closing_price;
    mco_seq_iterator_t adjusted_price;
    ...

    rc = mco_seq_cum_agg_prd_float(&prd_split_factor, &split);
    mco_seq_reverse_double(&rev_prd_split_factor, &prd_split_factor);
    mco_seq_stretch_uint4_double(&price_adjustment, &trade_date, &split_date, &rev_prd_split_factor, 1.0);
    mco_seq_mul_double(&adjusted_price, &closing_price, &price_adjustment);

The same result sequence can be calculated using the following SQL select statement:

    SELECT seq_mul(ClosePrice, seq_stretch(TradeDate, SplitDate,
            seq_reverse(seq_cum_agg_prd(SplitFactor)))) as AdjustedClose
    FROM Security
    WHERE Security.Symbol = 'IBM'

Note the relationship between the functions in SQL and in the C API: The innermost nested function in the select statement is the first sequence function called in the series of C API functions. The next most nested function, seq_reverse(), is the second function called in the C API, and so on.

Null Values in Sequences

The generated classname_fieldname_append_nullable() and classname_fieldname_insert_nullable() functions insert element-level NULL values. A nullable sequence field can also have a separate whole-field NULL indicator.

mco_seq_get_nullable_TYPE() and mco_seq_unget_nullable_TYPE() transfer values together with a bitmap in which a set bit denotes NULL. The payload bytes corresponding to a NULL element are unspecified.

A typed mco_seq_next_TYPE() call returns MCO_E_SEQ_NULL_VALUE for a NULL element and advances past it. Element-wise operators propagate NULL according to their inputs. Aggregates generally ignore NULL elements; their empty and all-NULL behavior is documented with each aggregate family.