Channels
Learn how channels represent data in Synnax.
This page walks you through what channels are, their important properties, and how to use them when structuring your cluster.
If you’re looking for a practical guide on creating or retrieving channels, visit the respective pages for the Python and TypeScript clients.
What is a Channel?
A channel is a logical collection of samples emitted by or representing the values of a single source. Practically, a channel holds sensor data such as speedometer, pressure transducer, or memory usage readings. It can also hold post-processed results such as the noise-filtered signal of another channel. The only restrictions are that samples in a channel must be time-ordered and share the same data type.
A Brief Primer on Domains
Channel data is stored in regions of continuously written samples called domains. A domain is marked by a time range, where the starting point is the timestamp of the first sample in the domain, and the ending point is the timestamp of the last sample.
Domains are used to identify and separate periods of continuous recording, and typically correlate to different tests or experiments run over the course of several hours, weeks, or years. It’s common for channels to have thousands or even millions of domains.
Domains are covered in detail here, although this introduction should be enough for the subsequent sections.
Channel Types
Synnax is a time-series database. Every respective channel must have a time channel that it is indexed to. These index channels allow for data lookup at a particular time. There are two main types of channels:
- Indexed Channels - Stores data arriving at a variable rate. The samples in these channels are ‘indexed’ by a specified index channel.
- Index Channels - Stores the timestamps for samples in one or more indexed channels. The samples in these channels must be time-ordered, nanosecond integers. Timestamps in index channels are used to look up the samples in the channels ‘indexed’ by them.
An index channel (or just “index”) is a special type of channel optimized for
fast lookups on timestamps. The values in an indexed channel must be
time-ordered, int64
nanosecond UTC timestamps. Synnax provides utilities for
converting between timestamp formats and timezones.
Indexed channels are ‘indexed’ by the values in an index channel, which means that each sample in the indexed channel has a correlated timestamp in its index. Multiple indexed channels can have the same channel as their index. By efficiently finding the location of the timestamp, Synnax can also quickly retrieve the associated samples.
Index channels play a similar role to primary keys in relational databases. The primary key (in Synnax’s case, a timestamp) can be used to fetch related values in one or more columns quickly.
Channel Fields
Key
A channel’s key is auto-assigned by the cluster and is guaranteed to be unique.
Name
A human-readable name for the channel. Synnax does not prevent duplicate names, but we highly recommend that you keep them unique.
Data Type
The data type of the samples stored in the channel. A channel’s data type must have a fixed density i.e. the number of bytes per sample is constant. Synnax has a number of built in data types:
Data Type | Description | Density |
---|---|---|
bool | Boolean value | 1 byte |
int8 | Signed 8-bit integer | 1 byte |
int16 | Signed 16-bit integer | 2 bytes |
int32 | Signed 32-bit integer | 4 bytes |
int64 | Signed 64-bit integer | 8 bytes |
uint8 | Unsigned 8-bit integer | 1 byte |
uint16 | Unsigned 16-bit integer | 2 bytes |
uint32 | Unsigned 32-bit integer | 4 bytes |
uint64 | Unsigned 64-bit integer | 8 bytes |
timestamp | 64-bit nanosecond UTC integer | 8 bytes |
float32 | 32-bit floating point | 4 bytes |
float64 | 64-bit floating point | 8 bytes |
We’re also planning on adding support for custom data types such as fixed-size JSON objects and arrays. If this is something that interests you, let us know.
Is Index
If this value is true, the channel is considered an index channel. Index
channels must have a data type of timestamp
, meaning that they must contain
ordered int64
nanosecond UTC timestamps.
Index
If the channel is not an index channel, this should be set to the key of the index channel. If this parameter is provided, the channel is considered an indexed channel. This field will be ignored for index channels, as they cannot be indexed.