Quick Start

Get started with the Synnax client in 5 minutes - from installation to reading and writing data.

Synnax provides first-class Python support and TypeScript support. Our client delivers many capabilities, including

Direct integration with pandas and numpy.
Tooling to implement automated control of your hardware.
Change data capture (CDC) infrastructure to build automated analysis pipelines.

Installation

The synnax library requires Python 3.11 or higher, and is available on PyPI. Install it directly using pip or define it as a requirement in your virtual environment of choice:

pip install synnax

Create a Client

To authenticate with a Synnax Core, simply instantiate a new client with your connection parameters and credentials:

import synnax as sy

client = sy.Synnax(
    host="demo.synnaxlabs.com",
    port=9090,
    username="synnax",
    password="seldon",
    secure=True,
)

Create a Channel

Create a channel using the channels.create client method. First create an “index” channel to store timestamps for your data channel.

# Index Channel
time_channel = client.channels.create(
    name="time",
    data_type=sy.DataType.TIMESTAMP,
    is_index=True,
)

# Data Channel
temp_channel = client.channels.create(
    name="my_temp_sensor",
    data_type=sy.DataType.FLOAT32,
    index=time_channel.key,
)

Write Data

Write data to the time and temperature channels. The index channel must be written to before writing to the data channel.

start = sy.TimeStamp.now()
times = [
    start,
    start + 1 * sy.TimeSpan.MINUTE,
    start + 2 * sy.TimeSpan.MINUTE,
    start + 3 * sy.TimeSpan.MINUTE,
    start + 4 * sy.TimeSpan.MINUTE,
]
temperatures = [55, 55.1, 55.7, 57.2, 58.1]

# Write the timestamps to the index
time_channel.write(start, times)

# Write the data to the channel
temp_channel.write(start, temperatures)

Notice how the two arrays are aligned using the common start timestamp. This tells Synnax that the first sample in the temperatures array is associated with the first timestamp in the timestamps array.

Synnax will raise a ValidationError if the index channel does not contain a corresponding timestamp for every sample in the data channel. After all, it wouldn’t make sense to have a temperature reading without an associated timestamp.

Read Data

The simplest way to read data from Synnax is to use the read method on a Channel object:

channel = client.channels.retrieve("my_temp_sensor")
start = sy.TimeStamp("2025-02-12 12:30:00")
end = sy.TimeStamp("2025-02-12 14:30:00")

data = channel.read(start, end)

The returned data is a Series object, which contains the time-range occupied by the data. Notably, the Series can be treated exactly like a numpy.ndarray.

data = data - 273.15
tr = data.time_range

Data can also be read in chunks with iterators or live-streamed with streamers. Data can also be read from a specific time range with ranges.

Next Steps

Now that you’ve completed the quick start, here are some recommended next steps:

Authentication: Learn about authentication methods, connection parameters, and troubleshooting.
Channels: Master channel creation, retrieval, renaming, and deletion.
Reading Data: Explore different ways to read data from Synnax.
Writing Data: Learn best practices for writing data to Synnax.
Examples: Browse full working examples for common use cases.

Authentication