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.

Introduction

A channel is a logical collection of samples representing the values of a single source. This source is typically a sensor, although channels can also hold actuator commands, post-processed results, or any other time-ordered data.

Channels are used for both data storage and real-time communication. A sensor recording samples 25 times per second (or 25Hz) would write data to a channel in order to store it permanently within Synnax, while at the same time streaming the data for live consumption.

The following diagram shows a sensor writing samples to a channel, which are then stored and forwarded to a visualization tool and analysis script.

Channels are comparable to tags in a time-series database like InfluxDB or SCADA system like Ignition. It’s common for a single Synnax database to have hundreds or thousands of channels, each of which represents a different data source.

Channel Types

There are three different types of channels in Synnax. Index channels exclusively store timestamps, and are used to retrieve the samples in data channels. Data channels store actual telemetry values, such as sensor readings. Virtual channels are only used for data streaming, and do not persist their samples to the database.

Index Channels

An index channel (or just index) is a special type of channel optimized for fast lookups on timestamps. Index channels always have a data type of timestamp, meaning that they must contain ordered int64 nanosecond UTC timestamps.

These channels are comparable to the index in a book. To find a particular piece of information, you first look through the index, which then points you to the relevant page. In Synnax, index channels are used in a similar fashion. To find the samples in a data channel for a particular time range, Synnax will first look through the index channel to find the relevant timestamps, and then retrieve the samples from the data channel.

Data Channels

Data channels are the primary method for storing telemetry samples in Synnax. Data channels can store sensor readings, actuator commands, calculated values, or any other time-ordered points.

Every sample in a data channel must have the same, fixed size data type. This means that data channels cannot store variable length values, such as strings or JSON objects.

Every data channel must have an associated index channel, which is used to look up samples at a particular time. It’s common to have multiple data channels associated with a single index channel.

Virtual Channels

Virtual channels are only used for real-time data streaming. Their values are not persisted to disk. Virtual channels do not have an associated index channel, and have the benefit of being able to support variable length data types.

It’s common to send strings, logs, JSON values, or other complex data types over virtual channels.

Channel Fields

All channel types have a common set of fields. There may be slight variations in the naming conventions between the various Synnax client libraries, but the core concepts remain the same.

Key

A channel’s key is a single, 32-bit number that is automatically assigned by Synnax when the channel is created. This key uniquely identifies the channel within the database, and cannot be edited.

Name

A human-readable name for the channel. This is the most common way to search for and reference a channel. Synnax does not prevent duplicate names, although it is highly recommended that you keep them unique.

Data Type

All channel’s must have a consistent data type. Index channels must always have a data type of timestamp, while data channels can have any of the following types:

In addition to these basic types, virtual channels also support the following variable length data types:

Is Index

A boolean field indicating whether the channel should be treated as an index channel. This field defaults to false, and should only be set to true for index channels.

Virtual

A boolean field indicating whether the channel is virtual. Virtual channels cannot be indexes. This field defaults to false, and should only be set to true for virtual channels.

Index

This field is only used for data channels, and specifies the key of the index channel associated with the data channel. This field will be ignored for index and virtual channels.