---
sidebar:
  hidden: true
title: roboto.experimental.topics.operations
---
## Module Contents

### FieldAddress

```python
class roboto.experimental.topics.operations.FieldAddress(/, **data: Any)
```

`from roboto.experimental.topics import FieldAddress`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/operations.py#L18-L40)

Bases: `pydantic.BaseModel`

Addresses a schema field, and the subtree nested under it, by exactly one of two forms.

A `path` names the field by its `path_in_schema` components directly (no string delimiter, so a component may itself contain a `.`); a `field_id` names it opaquely and resolves server-side to the same path. Either form designates the field and every field nested under it.

**Parameters**

- **data** (`Any`)

**Attributes**

- **FieldAddress.field_id** (`str | None`) = `None`: The field's opaque id (`sf_*`).
- **FieldAddress.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **FieldAddress.path** (`tuple[str, ...] | None`) = `None`: The field's `path_in_schema` components; `()` addresses the schema root.

### ReadPlanRequest

```python
class roboto.experimental.topics.operations.ReadPlanRequest(/, **data: Any)
```

`from roboto.experimental.topics import ReadPlanRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/operations.py#L115-L207)

Bases: `pydantic.BaseModel`

The body of a read-plan request: the logical read question to resolve into a physical plan.

`session_id`, `file_id`, `dataset_id` and `device_id` are restrictions: each limits the read to the topic's data in one session, file, dataset or device. Every restriction the request names narrows the read, and restrictions named together intersect.

**Parameters**

- **data** (`Any`)

**Attributes**

- **ReadPlanRequest.dataset_id** (`str | None`) = `None`: Limits the read to the topic's data in this dataset's files; `None` adds no dataset restriction.

- **ReadPlanRequest.device_id** (`str | None`) = `None`: Limits the read to the topic's data in this device's files; `None` adds no device restriction.

  A file belongs to the device it names, or, when it names none, to the device its dataset names.

- **ReadPlanRequest.end_time** (`int | None`) = `None`: Inclusive window upper bound, absolute Unix-epoch nanoseconds.

  May be `None` on the same terms as `start_time`; the bound then defaults to the latest time of the topic's data within the request's restrictions.

- **ReadPlanRequest.fields_exclude** (`tuple[FieldAddress, ...] | None`) = `None`: Field subtrees to drop from the projection; `None` drops none.

- **ReadPlanRequest.fields_include** (`tuple[FieldAddress, ...] | None`) = `None`: Field subtrees to project; `None` projects every field.

- **ReadPlanRequest.file_id** (`str | None`) = `None`: Limits the read to the topic's data in this file; `None` adds no file restriction.

- **ReadPlanRequest.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

- **ReadPlanRequest.prefer** (`RepresentationPreference | None`) = `None`: Per-subtree representation preference; `None` applies default selection everywhere.

- **ReadPlanRequest.schema_checksum** (`str | None`) = `None`: Schema to use, by checksum, or `None`.

- **ReadPlanRequest.schema_id** (`str | None`) = `None`: Schema to use, by id, or `None` to default to the sole in-window schema.

- **ReadPlanRequest.session_id** (`str | None`) = `None`: Limits the read to the topic's data in this Session's files, each over the part of its time span the Session holds; `None` adds no session restriction.

- **ReadPlanRequest.start_time** (`int | None`) = `None`: Inclusive window lower bound, absolute Unix-epoch nanoseconds.

  May be `None` only when the request names a `file_id`, `dataset_id` or `device_id`; the bound then defaults to the earliest time of the topic's data within the request's restrictions, across every timeline source. An explicit bound narrows the read and never widens it.

- **ReadPlanRequest.timeline_source_id** (`str | None`) = `None`: Timeline source to resolve partition extents with, by id, or `None`.

- **ReadPlanRequest.timeline_source_name** (`str | None`) = `None`: Timeline source to resolve partition extents with, by name, or `None`.

### RepresentationOverride

```python
class roboto.experimental.topics.operations.RepresentationOverride(/, **data: Any)
```

`from roboto.experimental.topics import RepresentationOverride`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/operations.py#L43-L52)

Bases: `pydantic.BaseModel`

Applies a representation selector to one field subtree, overriding the request default.

**Parameters**

- **data** (`Any`)

**Attributes**

- **RepresentationOverride.field** (`FieldAddress`): The subtree this override covers.
- **RepresentationOverride.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **RepresentationOverride.selector** (`roboto.experimental.topics.record.RepresentationSelector`): The selector to apply within that subtree.

### RepresentationPreference

```python
class roboto.experimental.topics.operations.RepresentationPreference(/, **data: Any)
```

`from roboto.experimental.topics import RepresentationPreference`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/operations.py#L55-L112)

Bases: `pydantic.BaseModel`

Selects which stored variant of each field to read, per subtree.

A `default` selector applies to every field unless a more specific `override` covers it. Where several overrides cover a field, the one whose addressed subtree is the longest prefix of the field's path wins; this rule is [`selector_for()`](/reference/python-sdk/roboto/experimental/topics/operations#roboto.experimental.topics.operations.RepresentationPreference.selector_for).

The governing selector and its matching rule are contract: a selector never substitutes a non-matching variant, and a read fails when a selector that sets any criterion is satisfied by no stored representation for a requested field — the plan never silently omits a field an explicit requirement covers. Which of the representations that satisfy the selector the service ultimately schedules is service policy and may change between releases.

**Parameters**

- **data** (`Any`)

**Attributes**

- **RepresentationPreference.default** (`roboto.experimental.topics.record.RepresentationSelector`): The selector applied to any field no override covers; matches anything when unset.
- **RepresentationPreference.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **RepresentationPreference.overrides** (`tuple[RepresentationOverride, ...]`) = `()`: Per-subtree selector overrides, resolved longest-matching-prefix wins.

#### RepresentationPreference.selector_for()

```python
def selector_for(
    field_path: tuple[str, ...],
) -> roboto.experimental.topics.record.RepresentationSelector
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/operations.py#L80-L112)

Resolve the selector that governs the field at `field_path`, longest-matching-prefix wins.

An override applies when its addressed subtree path is a prefix of `field_path`; among applicable overrides the deepest subtree wins, and a field no override covers gets `default`.

**Parameters**

- **field_path** (`tuple[str, ...]`): The `path_in_schema` components of the field whose selector is being resolved.

**Returns**

- `roboto.experimental.topics.record.RepresentationSelector`: The governing selector.

**Raises**

- `ValueError`: An override addresses its subtree by `field_id`. Resolving a `field_id` to a path takes the schema, which this value object does not hold; resolve every override address to its `path` form first.

### SetTopicUnixOffsetRequest

```python
class roboto.experimental.topics.operations.SetTopicUnixOffsetRequest(/, **data: Any)
```

`from roboto.experimental.topics import SetTopicUnixOffsetRequest`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/operations.py#L210-L241)

Bases: `pydantic.BaseModel`

Request body for `POST /v2/topics/id/<topic_id>/unix-offset`.

Anchors one Session's data on one topic to wall-clock time. See [`set_unix_offset()`](/reference/python-sdk/roboto/experimental/topics/topic#roboto.experimental.topics.topic.Topic.set_unix_offset) for the write's reach.

**Parameters**

- **data** (`Any`)

**Attributes**

- **SetTopicUnixOffsetRequest.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- **SetTopicUnixOffsetRequest.session_id** (`str`): Session whose data is anchored. Its files decide which of the topic's stored data the write reaches; the topic's data in files outside the Session keeps the anchor it already has.
- **SetTopicUnixOffsetRequest.unix_epoch_offset_ns** (`roboto.time._EpochNanosecondsFromTime`): Wall-clock instant of stored time 0 for the Session's data on this topic, in nanoseconds since the Unix epoch; each stored timestamp then reads as `stored_time_ns + unix_epoch_offset_ns`. Must fall after the Unix epoch, and must fit in the signed 64-bit integer the platform stores it in. Also accepts any [`roboto.time.Time`](/reference/python-sdk/roboto/time#roboto.time.Time) at runtime, read as [`roboto.time.to_epoch_nanoseconds()`](/reference/python-sdk/roboto/time#roboto.time.to_epoch_nanoseconds) reads it; convert with that function first to satisfy a type checker.