---
sidebar:
  label: roboto.roboto_search
  order: 22
title: roboto.roboto_search
---
## Module Contents

### RobotoSearch

```python
class roboto.roboto_search.RobotoSearch(
    query_client: Optional[roboto.query.QueryClient] = None,
)
```

`from roboto import RobotoSearch`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L41-L241)

A high-level interface for querying the Roboto data platform.

In most cases, using this class should be as simple as:

```python
from roboto import RobotoSearch
rs = RobotoSearch()
for dataset in rs.find_datasets(...):
    ...
```

**Parameters**

- **query_client** (`Optional[roboto.query.QueryClient]`)

#### RobotoSearch.find_collections()

```python
def find_collections(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.collections.Collection, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L88-L97)

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.collections.Collection, None, None]`

#### RobotoSearch.find_datasets()

```python
def find_datasets(
    query: Optional[roboto.query.Query] = None,
    content_mode: roboto.query.QueryContentMode = QueryContentMode.RecordOnly,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.datasets.Dataset, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L99-L112)

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **content_mode** (`roboto.query.QueryContentMode`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.datasets.Dataset, None, None]`

#### RobotoSearch.find_devices()

```python
def find_devices(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.devices.Device, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L114-L134)

Yield `Device` objects matching `query`, one at a time.

Results stream lazily as you iterate; `timeout_seconds` bounds how long iteration waits for results before stopping.

**Usage**

```python
from roboto import RobotoSearch
searcher = RobotoSearch()
for device in searcher.find_devices("tags CONTAINS 'warehouse'"):
    print(device.device_id)
```

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.devices.Device, None, None]`

#### RobotoSearch.find_events()

```python
def find_events(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.events.Event]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L180-L187)

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.events.Event]`

#### RobotoSearch.find_files()

```python
def find_files(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.files.File, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L136-L145)

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.files.File, None, None]`

#### RobotoSearch.find_message_paths()

```python
def find_message_paths(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.topics.MessagePath, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L147-L156)

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.topics.MessagePath, None, None]`

#### RobotoSearch.find_sessions()

```python
def find_sessions(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.experimental.sessions.Session, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L190-L241)

Yield `Session` objects matching `query`, one at a time.

Submits `query` against the structured-query API targeting Sessions and lazily materializes each row into a `Session` instance bound to the caller's `RobotoClient`. Iteration drives server-side pagination under the hood; `timeout_seconds` bounds the total wall-clock time spent waiting for query results before iteration stops.

Filterable fields:

- `session_id` (alias `id`).
- `name`.
- `min_timestamp_ns` (alias `start_time`) — inclusive lower bound of the session's recorded time window.
- `max_timestamp_ns` (alias `end_time`) — inclusive upper bound of the session's recorded time window.
- `duration` — synthetic numeric field equal to `max_timestamp_ns - min_timestamp_ns`; accepts integer nanoseconds only.
- `dataset.dataset_id` (alias `dataset.id`) — matches sessions that include at least one file from the given dataset. `=` / `!=` only.
- `device.device_id` (alias `device.id`) — matches sessions attached to the given device. `=` / `!=` only.
- `collection.collection_id` (alias `collection.id`) — matches sessions that are a member of the given collection. `=` / `!=` only.
- `metric.<name>` (alias `metrics.<name>`) — matches sessions by a session metric named `<name>`; dots are part of the metric name (e.g. `metric.cpu.load.max`). Accepts value and existence comparators. The value comparators `=`, `!=`, `>`, `>=`, `<`, `<=` require a numeric value, and only match sessions that have the metric *and* whose value satisfies the comparison. The presence comparators take no value: `IS_NOT_NULL` / `EXISTS` match sessions that have the metric (any value); `IS_NULL` / `NOT_EXISTS` match sessions that lack it.

The four time-window fields accept any shape [`roboto.time.Time`](/reference/python-sdk/roboto/time#roboto.time.Time) permits — integer epoch nanoseconds, float / Decimal / `<sec>.<nsec>` string seconds, ISO8601 strings, or a `datetime` (read as UTC when it carries no timezone) — and the server normalizes the value to epoch nanoseconds before the comparison runs.

Sortable fields: `session_id`, `min_timestamp_ns`, and `duration`.

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.experimental.sessions.Session, None, None]`

#### RobotoSearch.find_topics()

```python
def find_topics(
    query: Optional[roboto.query.Query] = None,
    timeout_seconds: float = math.inf,
) -> collections.abc.Generator[roboto.domain.topics.Topic, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L158-L178)

**Usage**

```python
import matplotlib.pyplot as plt
from roboto import RobotoSearch
searcher = RobotoSearch()
for topic in searcher.find_topics("msgpaths[cpuload.load].max > 0.9"):
    df = topic.get_data_as_df(message_paths_include=["cpuload.load"])
    plt.plot(df.index, df["cpuload.load"], label=topic.topic_id)
plt.legend()
plt.show()
```

**Parameters**

- **query** (`Optional[roboto.query.Query]`)
- **timeout_seconds** (`float`)

**Returns**

- `collections.abc.Generator[roboto.domain.topics.Topic, None, None]`

#### RobotoSearch.for_roboto_client()

```python
@classmethod
def for_roboto_client(
    roboto_client: roboto.http.RobotoClient,
    org_id: Optional[str] = None,
) -> RobotoSearch
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L56-L57)

**Parameters**

- **roboto_client** (`roboto.http.RobotoClient`)
- **org_id** (`Optional[str]`)

**Returns**

- `RobotoSearch`

#### RobotoSearch.from_env()

```python
@classmethod
def from_env() -> RobotoSearch
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/roboto_search.py#L60-L83)

Create a RobotoSearch instance configured from environment variables.

Reads authentication credentials and endpoint configuration from environment variables (\$ROBOTO_API_KEY/\$ROBOTO_BEARER_TOKEN, \$ROBOTO_SERVICE_ENDPOINT) or the config file at \$ROBOTO_CONFIG_FILE (default: \~/.roboto/config.json). If using the config file, \$ROBOTO_PROFILE can be used to select a profile from the config.

\$ROBOTO_ORG_ID can be used to set the organization ID to query. When it is unset, the organization queried is the `org_id` of the config file profile in use, which `roboto setup` saves. Naming an organization should only be necessary if you belong to multiple organizations.

**Returns**

- `RobotoSearch`: A configured RobotoSearch instance ready to query the Roboto platform.

**Usage**

```python
import roboto
roboto_search = roboto.RobotoSearch.from_env()
for dataset in roboto_search.find_datasets():
    print(dataset.name)
```