columnar tuple

The columnar tuple is a special type of tuple, whose elements can be either scalars or vectors with the same data type. Data retrieval from a columnar tuple is in the same way as that from an array vector.

Starting from version 2.00.9, DolphinDB supports storing a columnar tuple as a column of a table (DFS tables are not supported yet).

Creating a columnar tuple

To convert a regular tuple into a columnar tuple, you can use function setColumnarTuple!.

To check whether a tuple is a columnar tuple, you can use function isColumnarTuple.

$ tp = [[1.3,2.5,2.3], [4.1,5.3], 6.3]
$ isColumnarTuple(tp)
false

$ tp.setColumnarTuple!()
$ isColumnarTuple(tp)
true

Retrieving data from a columnar tuple

If you retrieve data from a regular tuple, the element with the specified index is returned. For columnar tuples or array vectors, a vector of values with the specified index taken from each element is returned.

$ tp = [[1.3,2.5,2.3], [4.1,5.3], 6.3]
$ ctp = [[1.3,2.5,2.3], [4.1,5.3], 6.3].setColumnarTuple!()
$ av = array(DOUBLE[], 0, 20).append!([[1.3,2.5,2.3], [4.1,5.3], 6.3])

// accessing by index
$ tp[0]
[1.3,2.5,2.3]

$ ctp[0]
[1.3,4.1,6.3]

$ av[0]
[1.3,4.1,6.3]

When you retrieve data from a columnar tuple by slicing (i.e., x[start:end]), if the range exceeds the length of its element, the NULL values will be automatically filled.

When the elements are not of STRING or SYMBOL type, and the end index of the slicing is specified, it returns an array vector, otherwise it returns a columnar tuple.

//accessing by slicing
$ a = ctp[0:3]
$ a
[[1.3,2.5,2.3],[4.1,5.3,00F],[6.3,6.3,6.3]]

$ b = ctp[0:]
$ b
([1.3,2.5,2.3],[4.1,5.3],6.3)

You can use the row function to retrieve rows from a columar tuple.

$ ctp.row(0)
[1.3,2.5,2.3]

Appending data to a columnar tuple

$ ctp = [[1.3,2.5,2.3], [4.1,5.3], 6.3].setColumnarTuple!()
$ ctp.append!([3.3,2.1])
$ ctp
([1.3,2.5,2.3],[4.1,5.3],6.3,[3.3,2.1])

Calculating columnar tuples by row

$ ctp = [[1.3,2.5,2.3], [4.1,5.3], 6.3].setColumnarTuple!()
$ rowSum(ctp)
[6.1,9.4,6.3]

Creating an in-memory table with a columnar tuple

Regular tuples with elements of unequal length are stored as columnar tuples in a DolphinDB in-memory table.

$ sym = `st1`st2`st3
$ price = [[3.1,2.5,2.8], [3.1,3.3], [3.2,2.9,3.3]]
$ t = table(sym, price)
$ t;

sym price
--- -------------
st1 [3.1,2.5,2.8]
st2 [3.1,3.3]
st3 [3.2,2.9,3.3]

Note: For tuples with elements of equal length, to store each element by row, you can first convert them to columnar tuples with the setColumnarTuple! function.

$ id = 1 2 3
$ val = [[1,2,3], [4,5,6],[7,8,9]]
$ table(id, val)
id  col1    col2    col3
1   1       4       7
2   2       5       8
3   3       6       9

$ table(id, val.setColumnarTuple!())
id val
-- -------
1  [1,2,3]
2  [4,5,6]
3  [7,8,9]