Find ranges

Find, open, and retrieve ranges in the Console or in code.

Find a range in the Console and open its range overview, or retrieve it in code.

Range explorer

The range explorer lists all the ranges in Synnax. To open it, click in the ranges toolbar, or run the “Open range explorer” command from the command palette.

In the range explorer, you can:

• Search for a range by name, and filter the list by label.
• Click a range to open its range overview.
• Click the stage icon of a range to start, complete, or reopen it.
• Hold Shift or Ctrl (Cmd on macOS) and click to select more than one range.
• Right-click a range to rename, favorite, or delete it, or to create a child range.

Favorites

The ranges toolbar shows your favorite ranges. A range joins the ranges toolbar when you create it, add it to a plot, open it from the command palette or from a link, or drag it onto the toolbar. To add a range, click beside it in the range explorer or on its range overview, or right-click it in the range explorer and select Favorite.

To remove a range from the ranges toolbar, right-click it and select Unfavorite. Unfavorite deletes a local range, because the toolbar is the only place it lives.

Active range

The Console uses the active range in these places:

• A new line plot shows the active range instead of the last 30 seconds.
• Set alias and Remove alias in the channels toolbar apply to the active range. Channel searches show its aliases.
• Snapshot to attaches snapshots to it.

To make a range active, click it in the ranges toolbar, or right-click it and select Set as active range. Opening a link to a range also makes it active. To clear it, right-click the active range and select Clear active range.

Range overview

The range overview shows all the information about one range. To open it, do one of these steps:

• Click the range in the range explorer.
• Right-click the range in the ranges toolbar and select View details.
• Right-click a range annotation on a line plot and select View details.

The range overview has these parts:

• Name -> click the name to change it.
• Child range of -> a child range shows a link to its parent range.
• Timeline -> click the stage to start, complete, or reopen the range. Click the start or end time to change it. See stages.
• Labels -> add or remove labels.
• Child ranges -> lists the child ranges. Click to add one.
• Metadata -> lists the metadata of the range.
• Snapshots -> lists the snapshots of the range.

The Console saves each change at once. Buttons in the header download the data as CSV (see export data), copy Python or TypeScript code that retrieves the range, and copy a link to it. Synnax Desktop does not show the copy link button.

Retrieve ranges

Single

Retrieve a range by its name or key. In Python, catch QueryError when no range or more than one range matches. In TypeScript, the client throws NotFoundError or MultipleFoundError.

# By name
my_range = client.ranges.retrieve(name="My Range")

# By key
my_range = client.ranges.retrieve(key=my_range.key)

// By name
const myRange = await client.ranges.retrieve("My Range");

// By key
const sameRange = await client.ranges.retrieve(myRange.key);

Multiple

Pass a list of names or keys to retrieve several ranges. A name that matches no range is left out of the result. In TypeScript, a missing key is left out too. In Python, a missing key raises NotFoundError.

# By name
my_ranges = client.ranges.retrieve(names=["My Range", "My Other Range"])

# By key
my_ranges = client.ranges.retrieve(keys=[my_range.key, my_other_range.key])

# By search term
ranges = client.ranges.retrieve(search_term="Hotfire")

# By label
passed = client.ranges.retrieve(has_labels=[pass_label.key])

// By name
const myRanges = await client.ranges.retrieve(["My Range", "My Other Range"]);

// By key
const myRanges = await client.ranges.retrieve([myRange.key, myOtherRange.key]);

// By search term
const ranges = await client.ranges.retrieve({ searchTerm: "Hotfire" });

// By label
const passed = await client.ranges.retrieve({ hasLabels: [passLabel.key] });

Child

If a range has child ranges, you can retrieve them directly from the parent range.

child_ranges = my_range.children

const childRanges = await myRange.retrieveChildren();

Parent

Navigate up the hierarchy by retrieving a child range’s parent.

my_range = client.ranges.retrieve(key=my_range.key, include_parent=True)
parent = my_range.parent

const parentRange = await myRange.retrieveParent();