Instants and Intervals
Overview
To organize time based data in XINA, we use instants, referring to a single moment in time, and intervals, referring to a range of time. The goal for these components is to make it easy to find, compare, and trend data. Each has their own databases and include fields for:
- type indicate how the instant/interval should be viewed and interpretted
- UUID (universally unique identifier)
- numeric primary and secondary IDs (meaning can depend on subtype)
- plain text label (up to 128 bytes)
- plain text or HTML content
- optional JSON object metadata
Why all these IDs? The UUID uniquely identifies an instant / interval, and is the only way to permanently, globally specify it. It should be applied at the time of creation to ensure consistency even if data is reprocessed. The primary / secondary IDs are optional, and can be used as needed. The general idea is that its much faster and more reliable to query numbers than text, so this is the best way to relate instants and intervals.
Instants
Instants provide a reference to a single moment in time. They are not intended to imply any duration.
Instant Database
Default Location
<model>.data.ins
<model>.data.insf (single file per instant)
<model>.data.insfs (multi file per instant)
Required Fields
| field | type | description |
|---|---|---|
|
uuid |
UUID |
p_id |
int(8) |
primary ID |
s_id |
int(8) |
secondary ID |
t |
instant(us) |
time |
type |
int(2) |
instant type code |
level |
int(1) |
level code |
label |
utf8vstring(128) |
plain text label |
content |
utf8text |
extended text / CSV / HTML |
meta |
jsonobject |
additional metadata as needed |
conf |
jsonobject |
additional information specific to type |
Standard Types
| type | code | description |
|---|---|---|
message |
0 |
Basic instant, recommended to use standard IDs to indicate common events |
alert |
1 |
Higher priority variant of message |
2D dataset (CSV) |
100 |
General purpose 1D/2D data set (see below) |
Intervals
Intervals provide a reference to a span of time, specified by a start time and an end time.
Interval Database
Default Location
<model>.data.int
<model>.data.intf (single file per interval)
<model>.data.intfs (multi file per interval)
Required Fields
| field | type | description |
|---|---|---|
|
uuid |
UUID |
p_id |
int(8) |
primary ID |
s_id |
int(4) |
secondary ID |
t_start |
instant(us) |
start time (inclusive) |
t_end |
instan(us)t |
end time (exclusive) |
duration |
duration |
t_end - t_start |
type |
int(2) |
interval type code |
level |
int(1) |
level code |
label |
utf8vstring(128) |
plain text label |
content |
utf8text |
extended text / CSV / HTML |
meta |
jsonobject |
additional metadata as needed |
conf |
jsonobject |
additional information specific to type |
Standard Types
| type | code | description |
|---|---|---|
marker |
0 |
Basic interval, recommended to use standard IDs to indicate common events |
test |
1 |
TODO |
2D dataset (CSV) |
100 |
General purpose 1D/2D data set (see below) |