data_def Class Reference

A data_def object describes the structure of a table. More...

Detailed Description

A data_def object describes the structure of a table.

Each table field is defined by its:

• field name (must be unique to the table)
• field type
• field length (only required for strings)

One of the idiosyncracies of the series_base database is that all tables exclusively store timeseries data. This mean that all records in all tables must have a timestamp. As a result of this requirement, a 'timestamp' field was implicitly added to all tables and, as a result, user must no longer add a date_time field meant as record timestamp. It is still possible to add date and date_time fields, but these won't be interpreted as the record timestamp.

There are two ways of defining a data_def structure. The first is via a string that describes the table fields (data-definition-string), and the second involves repeatedly calling the add_field() member with the corresponding field information.

Data Definition String

A data-definition-string is a comma separated list of unique field names, each followed by a colon and a single letter representing the datatype. Character string fields must be followed by a second colon followed by the maximum allowed string length. Space characters before and after commas are ignored. Field names must not contain space characters.

Legal 'type characters' are:

• 'd' or 'D' - 64 bit floating point
• 'f' or 'F' - 32 bit floating point
• 'i' or 'I' - 32 bit integer
• 'u' or 'U' - 32 bit unsigned integer
• 'l' or 'L' - 64 bit integer
• 'b' or 'B' - boolean
• 's' or 'S' - character string of fixed length
• 't' or 'T' - date_time
• 'a' or 'A' - date

The following is an example data-definition-string that declares fields of all available types:

data_def ddef;
ddef.set("double-fld:d, float-fld:f, int-fld:i, long-fld:l, uint-fld:u, bool-fld:b, string-fld:s:10, date_time-fld:t, date-fld:a");

series_base db(<...>);
db.create_table("my_table_1", ddef);

// data_def argument can take the data-definition-string directly
db.create_table("my_table_2", "open:d, high:d, low:d, close:d, volume:d");

Note

Type 'double' is the default type, and so it is not necessary to add the ':d' postfix when working with 'double' fields

//fields without postfix default to type 'double'
db.create_table("my_table_2", "open, high, low, close, volume");

Note

It is recommened to always use type 'double' for numeric database fields, as most API functions/functors declare parameters of type 'double' or series<double>, and built-in series names also rely on type 'double'.

Defining Data Programmatically

Programmatically populating a data_def object with field information involves repeatedly calling its add_field() member with the field's value-type and name arguments. Note that for string fields the maximum number of allowed characters must also be given.

data_def ddef;

ddef.add_field(type_t::float64,   "double-field");
ddef.add_field(type_t::float32,    "float-field");
ddef.add_field(type_t::int32,      "int-field");
ddef.add_field(type_t::uint32,     "uint-field");
ddef.add_field(type_t::int8,     "long-field");
ddef.add_field(type_t::boolean,     "bool-field");
ddef.add_field(type_t::string,   "string-field", 10);  // max length for strings!
ddef.add_field(type_t::datetime, "date_time-field");

series_base db(<...>);
db.create_table("my_table_3", ddef);

2) Using a 'schema definition string'