Channels

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

The TypeScript client provides interfaces for creating, retrieving and deleting the channels in a Synnax cluster. In this guide, we’ll cover the details of each of these operations.

If you’re unfamiliar with what channels are and how they work, check out the of 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:

import { DataType } from "@synnaxlabs/client";

// This channel is a special 'index' channel that is used to store timestamps for
// other channels.
const timeIndexChannel = await client.channels.create({
    name: "time",
    // Index channels must have a data type of TIMESTAMP and isIndex set to true
    dataType: DataType.TIMESTAMP,
    isIndex: true,
});

// This channel is used to store our actual data.
const tempChannel = await client.channels.create({
    name: "my_temp_sensor",
    dataType: DataType.FLOAT32,
    // Pass the key of the index channel here
    index: timeIndexChannel.key
});

Notice how we set the isIndex property to true on the "time" index channel. This tells Synnax that this channel will be used to store timestamps for other channels. We then pass the index property to the temperature sensor channel so it uses the "time" channel as its index.

Creating Multiple Channels

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

import { Channel } from "@synnaxlabs/client";

// We need to create the index first, that way we can provide
// its key to our data channels.
const timeIndexChannel = await client.channels.create({
    name: "time",
    dataType: DataType.TIMESTAMP,
    isIndex: true,
});

const sensorOne = new Channel({
    name: "sensor_one",
    dataType: DataType.FLOAT32,
    index: timeIndexChannel.key
});

const sensorTwo = new Channel({
    name: "sensor_two",
    dataType: DataType.FLOAT32,
    index: timeIndexChannel.key
});

const sensorThree = new Channel({
    name: "sensor_three",
    dataType: DataType.FLOAT32,
    index: timeIndexChannel.key
});

const sensors = await client.channels.create(
    [sensorOne, sensorTwo, sensorThree]
);

Retrieving Channels

Like creating them, we can retrieve channels using the channels.retrieve method on the client.

Retrieving a Single Channel

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

// By name
const tempChannel = await client.channels.retrieve("my_temp_sensor");
// If you know the key, you can use that too
const tempChannel = await client.channels.retrieve(tempChannel.key);

If Synnax finds no channels matching the query, the client will raise a NotFoundError. If more than one channel matches the query, the client will raise a MultipleFoundError. 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

We can also retrieve multiple channels by passing a list of names or keys to the retrieve method:

// By name
const channels = await client.channels.retrieve(
    ["my_temp_sensor", "time"]
);
// By key
const channels = await client.channels.retrieve(
    [tempChannel.key, timeIndexChannel.key]
);
// This won't work!!
const channels = await client.channels.retrieve(
    ["my_temp_sensor", timeIndexChannel.key]
);

Synnax will not raise a NotFoundError if no channels match the query. Instead, it will simply omit that channel from the list of results.

Deleting Channels

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

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