v0.61.3
ReferenceChannelsFind

Find channels

Find channels in the Console, or retrieve them in code by name, key, pattern, or search term.

In the Console, you find a channel to plot it or to add it to a schematic. In a script, you retrieve a channel before you read or write its data.

Find a channel in the Console

The channels toolbar lists all of the channels in Synnax. To open it, click or press C. Drag a channel onto a line plot or a schematic, or double-click it to add it to the open line plot.

To filter the toolbar, click in its header and type part of a name. Under an active range, the search also matches aliases. Click to show the results in their groups. Press Escape in the field to close the search.

You can also find a channel from anywhere in the Console. Click at the top of the left bar, or press Ctrl+P (Cmd+P on macOS), to open the search palette. Then type part of the name. Select a result to add the channel to the open line plot, or to a new line plot. A virtual channel opens in a log.

Retrieve channels in code

A script gets a channel from the Core before it reads or writes its data. Retrieve channels by name or key, by a pattern, or by a search term.

By name or key

# One channel, by name or by key
tank_pressure = client.channels.retrieve("tank_pressure")
tank_pressure = client.channels.retrieve(tank_pressure.key)

# Many channels, by names or by keys
channels = client.channels.retrieve(["tank_pressure", "tank_temperature"])
channels = client.channels.retrieve([tank_pressure.key, tank_temperature.key])

When you pass one name or key, retrieve returns one channel. It raises sy.NotFoundError when no channel matches, and sy.MultipleFoundError when more than one channel has the name. When you pass a list, retrieve returns a list and leaves out the channels that it does not find. To get one channel for any other filter, pass one=True.

Pass names or keys, not both in one list. A key never changes, but a name can change. Store keys in programs that run for a long time.

By pattern

A name filter selects channels by a pattern in their name. Set one or more operators. A channel must match all of them. A plain name, as in the section above, always matches exactly.

Python TypeScript Matches names that
contains contains Hold the text.
starts_with startsWith Start with the text.
regex regex Match the regular expression, in Go RE2 syntax.
in_ in Equal one of the names in the list.
case_insensitive caseInsensitive Set to true, the other operators ignore case.

A regex can match any part of the name, so start it with ^ to match from the start. For example, ^tank_ matches tank_pressure and tank_time, but not ox_tank_pressure.

import synnax as sy

# Returns list[sy.Channel]
tank_channels = client.channels.retrieve(
    where=sy.channel.Where(name=sy.filter.String(regex="^tank_"))
)
pressures = client.channels.retrieve(
    where=sy.channel.Where(
        name=sy.filter.String(contains="pressure", case_insensitive=True)
    )
)

By search term

Both clients can search channels by a part of their name and filter them by their properties.

import synnax as sy

matches = client.channels.retrieve(search_term="pressure", limit=10)
floats = client.channels.retrieve(data_types=[sy.DataType.FLOAT32], is_index=False)

The filters are search_term, data_types, not_data_types, is_index, virtual, internal, node_key, and limit. Results match all the filters. Use range_key to include aliases from a range and search those aliases too. Set include_status=True to attach each channel’s status; a channel with no status gets None.

To read past the first page, sort with order and pass the position of the last channel as after:

order = sy.channel.Order(field="name")
page = client.channels.retrieve(order=order, limit=100)
last = page[-1]
after = sy.channel.Cursor(key=last.key, name=last.name)
next_page = client.channels.retrieve(order=order, after=after, limit=100)

Find the channels of a range

A range can give channels a different name, called an alias. To find channels by alias, or to read their data in a range, see read and write range data.