Channels

Learn the fundamentals of creating, retrieving, renaming, and deleting channels.

Channels are the fundamental building blocks for storing and organizing data in Synnax. This guide covers all the basic operations you need to work with Synnax channels.

If you’re unfamiliar with what channels are and how they work, check out the channels concepts guide.

Creating Channels

Parameter	Type	Default	Description
`name`	`str`	Required	A human-readable name for the channel. This name is not guaranteed to be unique.
`data_type`	`DataType`	Required	The data type of the samples stored in the channel (e.g., `DataType.FLOAT32`, `DataType.TIMESTAMP`).
`is_index`	`bool`	`False`	Set to `True` if the channel is an index channel, `False` otherwise. Index channels must have a data type of `DataType.TIMESTAMP`.
`index`	`int`	`0`	The key of the index channel that this channel is associated with. Not required for index channels.
`virtual`	`bool`	`False`	Set to `True` if the channel is virtual. Virtual channels do not store data in the database and are used for streaming purposes only.
`retrieve_if_name_exists`	`bool`	`False`	If `True`, retrieves the channel if one with the same name already exists instead of creating a duplicate.

time_index_channel = client.channels.create(
    name="time",
    data_type=sy.DataType.TIMESTAMP,
    is_index=True,
)

my_sensor = client.channels.create(
    name="my_sensor",
    data_type=sy.DataType.FLOAT32,
    index=time_index_channel.key,
)

Retrieving the Channel if it Already Exists

There are situations where you want to ensure a channel with a particular name exists, but don’t want it duplicated. To accomplish this, use the

retrieve_if_name_exists flag.

time_index_channel = client.channels.create(
    name="time",
    data_type=sy.DataType.TIMESTAMP,
    is_index=True,
    retrieve_if_name_exists=True,
)

my_sensor = client.channels.create(
    name="my_sensor",
    data_type=sy.DataType.FLOAT32,
    index=time_index_channel.key,
    retrieve_if_name_exists=True,
)

Creating Multiple Channels

Multiple channels can be created in a single call using the create method. This is more efficient than creating channels individually, and provides the atomic guarantee that either all or no channels will be created.

Keep in mind that the index channel(s) must still be created first.

import numpy as np
import synnax as sy

time_index = client.channels.create(
    name="time",
    data_type=sy.DataType.TIMESTAMP,
    is_index=True,
)

sensor_one = sy.Channel(
    name="sensor_one",
    data_type=sy.DataType.FLOAT32, # Use Synnax datatypes
    index=time_index.key,
)

sensor_two = sy.Channel(
    name="sensor_two",
    data_type=np.float32, # Or numpy
    index=time_index.key,
)

sensor_three = sy.Channel(
    name="sensor_three",
    data_type="float32", # Or strings
    index=time_index.key,
)

data_channels = client.channels.create(
  [
    sensor_one,
    sensor_two,
    sensor_three,
  ],
  retrieve_if_name_exists=True, # Optional
)

Retrieving Channels

To retrieve channel(s), pass the channel name(s) or key(s) to the retrieve method. Retrieving by key is faster than retrieving by name, and is recommended whenever possible.

Channels can also be retrieved using ranges.

Retrieving a Single Channel

# Method 1: By key
my_sensor = client.channels.retrieve(my_sensor.key)

# Method 2: By name
my_sensor = client.channels.retrieve("my_sensor")

The client will raise a NotFoundError if no channels match the query, and a MultipleFoundError if more than one channel matches the query. To accept no results or multiple results, provide a list to the retrieve method as shown in the next section.

Retrieving Multiple Channels

# Method 1: By key
my_channels = client.channels.retrieve([sensor_one.key, sensor_two.key])

# Method 2: By name
my_channels = client.channels.retrieve(["sensor_one", "sensor_two"])

# This won't work!
my_channels = client.channels.retrieve(["sensor_one", sensor_two.key])

Synnax will not raise a NotFoundError if one or more channels are not found. Instead, the missing channel will simply be omitted from the list of results.

Retrieving Channels with Regular Expressions

Channels can be retrieved using regular expression patterns. The Core treats any name starting with ^ or ending with $ as a regex pattern.

# Returns list[sy.Channel]
sensor_channels = client.channels.retrieve(["^sensor.*"])

Please note that if expecting multiple channels to match the pattern, you must pass in a list to the retrieve method, otherwise the client will raise a MultipleFoundError.

Renaming Channels

Rename channels using the channels.rename method. Currently, renaming must be done by key from the client or by calling the rename on an existing channel object.

# Rename an already existing channel
data_channel.rename("new_name")

# Renaming single channel
client.channels.rename(data_channel.key, "new_name")

# Renaming multiple channels
client.channels.rename([channel_one.key, channel_two.key], ["name_one", "name_two"])

Deleting Channels

To delete a channel, use the channels.delete method.

Deleting a channel will also delete all of the data stored for that channel in a Synnax Core. This is a permanent operation that cannot be undone. Be careful!

# Delete by name
client.channels.delete("my_sensor")

# Delete multiple by name
client.channels.delete(["sensor_one", "sensor_two"])

# Delete by key
client.channels.delete(sensor_three.key)

# Delete multiple by key
client.channels.delete([sensor_one.key, sensor_two.key, sensor_three.key])

Unlike with retrieving channels, Synnax will not raise an error if it cannot find a channel matching the key or name. This means that delete is an idempotent operation, and is safe to call even if the channel has already been deleted.

Deleting a channel by name will delete all channels with that name.

Aliasing Channels

Channels can be aliased to give them a more descriptive name for a specific test or operation.

Authentication

Ranges