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.12 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 synnaxThe TypeScript client is available on
npm, and can be installed with your
package manager of choice. This documentation uses npm, but yarn, pnpm, or any
other package manager will work.
npm install @synnaxlabs/clientCreate 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,
)import { Synnax } from "@synnaxlabs/client";
const client = new 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,
)import { DataType } from "@synnaxlabs/client";
// Index Channel
const timeChannel = await client.channels.create({
name: "time",
dataType: DataType.TIMESTAMP,
isIndex: true,
});
// Data Channel
const tempChannel = await client.channels.create({
name: "my_temp_sensor",
dataType: DataType.FLOAT32,
index: timeChannel.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)const start = TimeStamp.now();
const timestamps = new BigInt64Array([
start.valueOf(),
start.add(TimeSpan.seconds(1)).valueOf(),
start.add(TimeSpan.seconds(2)).valueOf(),
start.add(TimeSpan.seconds(3)).valueOf(),
start.add(TimeSpan.seconds(4)).valueOf(),
]);
const temperatures = new Float32Array([20.0, 20.1, 20.2, 20.3, 20.4]);
// Write the timestamps to the index first
await timeChannel.write(start, timestamps);
// Then write the data
await tempChannel.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_rangeconst channel = await client.channels.retrieve("my_temp_sensor");
const start = new Date("2025-02-12T12:30:00Z");
const end = new Date("2025-02-12T14:30:00Z");
const series = await channel.read(start, end);
The returned data is a Series, which
maintains a very similar interface to a JavaScript typed array (e.g. Float32Array,
Int32Array, etc.). Convert the returned data to a JavaScript array easily:
const data = Array.from(series);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.