# 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](https://docs.synnaxlabs.com/reference/get-started/ui-overview#search-and-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](https://docs.synnaxlabs.com/reference/ranges/find#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](https://docs.synnaxlabs.com/reference/ranges/reference#saved-and-local-ranges), 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](https://docs.synnaxlabs.com/reference/ranges/aliases).
* **Snapshot to** attaches [snapshots](https://docs.synnaxlabs.com/reference/ranges/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**.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/console/ranges/active/324a1d88ad3f-dark.mp4#t=0.001)

## 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 bar 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](https://docs.synnaxlabs.com/reference/ranges/reference#stages).
* **Labels** -> add or remove [labels](https://docs.synnaxlabs.com/reference/ranges/metadata#labels).
* **Child ranges** -> lists the child ranges. Click to add one.
* **Metadata** -> lists the [metadata](https://docs.synnaxlabs.com/reference/ranges/metadata) of the range.
* **Snapshots** -> lists the [snapshots](https://docs.synnaxlabs.com/reference/ranges/snapshots) of the range.

The Console saves each change at once. Buttons in the header download the data as CSV (see [export data](https://docs.synnaxlabs.com/reference/ranges/export)), 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. The client raises `NotFoundError` when no range matches, and `MultipleFoundError` when more than one range has the name. To get one range for any other filter, pass `one=True` in Python or `one: true` in TypeScript.

**Python**

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

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

**TypeScript**

```typescript
// 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, or a filter, to retrieve several ranges. A name or key that matches no range is left out of the result. Results match all the filters. A name pattern takes the same [operators](https://docs.synnaxlabs.com/reference/channels/find#by-pattern) as a channel name.

**Python**

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

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

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

# By name pattern
hotfires = client.ranges.retrieve(
    name=sy.filter.String(contains="hotfire", case_insensitive=True)
)

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

# By time: the ranges that overlap a time range
today = client.ranges.retrieve(overlaps=sy.TimeRange(start, end))

# By parent: the child ranges of one or more ranges
children = client.ranges.retrieve(parents=[my_range.key])
```

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

```python
order = sy.ranger.Order(field="time_range_start")
page = client.ranges.retrieve(order=order, limit=100)
if len(page) == 100:
    last = page[-1]
    after = sy.ranger.Cursor(key=last.key, time_range_start=last.time_range.start)
    next_page = client.ranges.retrieve(order=order, after=after, limit=100)
```

**TypeScript**

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

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

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

// By name pattern
const hotfires = await client.ranges.retrieve({
  where: { name: { contains: "hotfire", caseInsensitive: true } },
});

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

// By time: the ranges that overlap a time range
const today = await client.ranges.retrieve(new TimeRange(start, end));

// By parent: the child ranges of one or more ranges
const children = await client.ranges.retrieve({ where: { parents: [myRange.key] } });
```

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

```typescript
const order = { field: "time_range_start" } as const;
const page = await client.ranges.retrieve({ order, limit: 100 });
if (page.length === 100) {
  const last = page[page.length - 1];
  const after = { key: last.key, timeRangeStart: last.timeRange.start };
  const nextPage = await client.ranges.retrieve({ order, after, limit: 100 });
}
```

### Child

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

**Python**

```python
child_ranges = my_range.children
```

**TypeScript**

```typescript
const childRanges = await myRange.retrieveChildren();
```

### Parent

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

**Python**

```python
if my_range.parent is not None:
    parent = client.ranges.retrieve(key=my_range.parent)
```

`my_range.parent` is the key of the parent range, or `None` when the range has no parent.

**TypeScript**

```typescript
const parentRange = await myRange.retrieveParent();
```
