Channels

Learn how to work with channels using the Synnax Python client.

The Python client provides interfaces for creating, retrieving, and deleting channels. We’ll cover the details of each of these operations in this guide.

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

Creating Channels

We can create channels using the channels.create method on the client.

Creating a Data Channel and its Index

Creating a data channel first requires us to create an index channel to store its timestamps:

# Create a time channel to store the timestamps of our data channel
time_index_channel = client.channels.create(
    name="time",
    # Index channels must have a data type of TIMESTAMP and is_index 
    # set to True
    data_type=sy.DataType.TIMESTAMP, 
    is_index=True,
)

# Create a data channel that stores 32-bit floats
my_sensor = client.channels.create(
    name="my_sensor",
    data_type=sy.DataType.FLOAT32,
    index=time_index_channel.key, # Pass the key of the index channel here.
)

Creating Multiple Channels

We can create multiple channels by passing a list to the create method. This is more efficient than creating many channels individually, and provides the atomic guarantee that either all or no channels will be created.

Keep in mind that we need to create index channels before we can create the channels that use them. We’re working on adding functionality to the client that will allow us to create all of these channels in a single call.

import numpy as np

# We need to create the index first, that way we can provide the index
# key to our data channels.
time_index = client.channels.create(
    name="time",
    data_type=sy.DataType.TIMESTAMP,
    is_index=True,
)

sensor_one = sy.Channel(
    name="sensor_one",
    data_type=np.float32, # You can use numpy to define data types
    index=time_index.key,
)

sensor_two = sy.Channel(
    name="sensor_two",
    data_type="float32" # Or you can use strings
    index=time_index.key,
)

sensor_three = sy.Channel(
    name="sensor_three",
    data_type=sy.DataType.FLOAT32, # Or you can use Synnax data types
    index=time_index.key,
)

client.channels.create([
    sensor_one,
    sensor_two,
    sensor_three,
])

Only Create a Channel if it Doesn’t Exist

There are situations where we want to ensure that a channel with a particular name exists, but don’t want it duplicated if it has already been created. To accomplish this, we can use the retrieve_if_name_exists flag:

# Create a channel if it doesn't exist
my_channel = client.channels.create(
    name="my_channel",
    data_type=sy.DataType.FLOAT32,
    index=my_index.key,
    retrieve_if_name_exists=True,
)

This also works when creating multiple channels:

# Create multiple channels if they don't exist
my_channels = client.channels.create(
    [my_channel_one, my_channel_two, my_channel_three],
    retrieve_if_name_exists=True,
)

Retrieving Channels

We can retrieve channels using the channels.retrieve method.

Retrieving a Single Channel

To retrieve a single channel, pass the channel’s name or key to the retrieve method:

# By name
my_sensor = client.channels.retrieve("my_sensor")
# If you know the key, you can also retrieve by key
my_sensor = client.channels.retrieve(my_sensor.key)

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

Retrieving Multiple Channels

To retrieve multiple channels, pass a list of names or a list of keys to the retrieve method:

# By name
my_channels = client.channels.retrieve(["sensor_one", "sensor_two"])
# By key if you know them
my_channels = client.channels.retrieve([sensor_one.key, sensor_two.key])
# This won't work!
my_channels = client.channels.retrieve(["sensor_one", sensor_two.key])

Note that Synnax will not raise a NotFoundError if it cannot find a channel matching a key or name. Instead, the missing channel will simply be omitted from the list of results.

Retrieving a Channel Using a Range

If you’ve queried a range, you can access channels as properties. If the channel name is not a valid Python identifier, you can use the dictionary accessor ([]) instead:

# Retrieve the range - see the highlighted link above for how these work
test_one = client.ranges.retrieve("02/22/23 Testing")

# Grab a channel
ch = test_one["sensor_one"]
# Or like this
ch = test_one.sensor_one

Retrieving Channels Using Regular Expressions

If you’re familiar with regular expressions, you can use them to retrieve channels that match a pattern. For example, if we wanted to retrieve all channels that start with “sensor”, we could do the following:

sensor_channels = client.channels.retrieve(["^sensor"])

It’s important to note that if we’re expecting multiple channels to match our pattern, we need to pass in a list to the retrieve method, otherwise the client will raise a MultipleFoundError.

Deleting Channels

To delete a channel, we can use the channels.delete method:

# Delete a single channel
client.channels.delete("my_sensor")
# Delete multiple channels
client.channels.delete(["sensor_one", "sensor_two"])
# Delete by key
client.channels.delete(sensor_three.key)
# Delete many 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.

Next Steps

Now that we know how to create and retrieve channels, we can start reading and writing data to them. Check out the reading data and writing data guides to learn more.