eXtremeDB provides a C library for constructing and consuming operations over
sequences. The public declarations are inmcoseq.h. Stored sequence fields are opened through generated field functions; generic transformations and analytics operate onmco_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 twoint4input sequences. This documentation usesTYPEas a placeholder for one of the following suffixes:int1Signed one-byte integerint2Signed two-byte integerint4Signed four-byte integerint8Signed eight-byte integeruint1Unsigned one-byte integeruint2Unsigned two-byte integeruint4Unsigned four-byte integeruint8Unsigned eight-byte integerfloatFour-byte floating pointdoubleEight-byte floating pointdatetimeEight-byte datetimeThus
mco_seq_add_TYPE()denotesmco_seq_add_int1(),mco_seq_add_int2(), and the other declared typed variants. The corresponding C value types are the fixed-widthmco_TYPEtypes, for examplemco_int4andmco_datetime. Fixed-width character operations use separate_charfunctions 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
_charfunctions. Buffer ownership, custom allocation, binding checks, and hash cleanup are described in Iterator Resources and Global Configuration.Common Iterator Contract
- Initialize each destination iterator to zero before its first use.
- Keep all input iterators, database transactions, callback contexts, and referenced application buffers alive until the result is completely consumed.
- An input iterator is stateful and is normally consumed by one pipeline. Use a second source iterator or
mco_seq_tee()for independent consumers.- Check both constructor return codes and traversal return codes. Value-dependent errors can occur during traversal.
MCO_S_CURSOR_ENDis normal iterator exhaustion, not a failure.- Use the reset callback installed in the iterator when a complete pipeline must be traversed again.
- Follow the constructing function's buffer or hash lifecycle. Temporary state is not recursively released merely because an iterator variable goes out of scope.
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_dateandclosing_pricecontain the time series of trade dates paired with closing prices, andsplit_datecontains 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
selectstatement: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
selectstatement 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()andclassname_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()andmco_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 returnsMCO_E_SEQ_NULL_VALUEfor 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.