roboto.experimental.topics.read_plan

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

One entry per partition in the window, each its own fetch-and-interpret plan.

Ordered by when each file’s data begins. Partitions backed by the same file are contiguous in this tuple, ordered by where their data_range slice starts in that file, so they arrive in the order their data sits in it. This orders whole partitions, not rows.

Contract version of this plan. Validation refuses a version this model does not recognize.

The output fields a consumer projects decoded rows to.

The schema the plan reads under. Serializes as schema.

None when no partition of the topic lies in the window (within the request’s restrictions), and the plan then has no partitions. A plan that names a schema may also have no partitions.

The topic this plan reads.

The time window the caller asked to read, which the plan was resolved over.

A consumer selects rows by each partition’s ReadPlanPartition.window alone, which can be narrower than this one.

None only when the request omitted a bound and either its restrictions select no timestamped data for the topic, or the bound it gave lies past the far end of that data (a start after the data ends, or an end before it begins); the plan then has no partitions.

Identifier of the schema field.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The field’s path components within the schema, from the root to the field.

Identifier of the backing file. This id is stable, so a consumer can cache on it.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The source object’s size in bytes.

The slice of the file this partition owns, as (start, end), or None for the whole file.

start is the first owned position and end is one past the last, like a Python slice. Positions are in the addressing native to the file the slice was declared against: stored-row positions counted from 0, or nanoseconds of media time for video. Any slice a consumer decodes is a range of stored rows.

A slice appears when one file packs several partitions’ data (a LeRobot v3 data file, for example). Each of those partitions carries its own time_offset_ns and may cover the same instants as the partitions beside it in the file, so time alone cannot separate its rows from theirs. Restrict each scan task’s decode to this slice before filtering by time, or the read returns the neighboring partitions’ rows too.

A scan task may name a transformed representation of the file the slice was declared against (see ReadPlanScanTask.transformations) rather than that file itself. The slice still applies unchanged: a partition that owns a slice is served only by representations holding the same content at the same positions.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The files to read for this partition; empty when the partition has no readable data.

A partition may have several scan tasks, each covering a subtree of the schema or the whole schema; the read takes each field from the highest-precedence scan task whose subtree contains it.

Offset a consumer adds to each decoded row timestamp; the same for every row in the partition.

Where this partition’s row timestamps come from.

Identifier of the partition.

The window this partition’s rows are selected in, in absolute Unix-epoch nanoseconds.

A consumer keeps only the rows whose stored timestamp, once time_offset_ns is added, falls inside this window, inclusive on both ends. It is the only time filter a read applies.

It is the caller’s window intersected with the part of this partition’s backing file the read is scoped to, so it can be narrower than ReadPlan.window: a read scoped to a Session narrows it when the Session holds that file over only part of the file’s time span. The narrowing is stated per file, so every partition backed by one file carries the same window; ReadPlanPartition.data_range separates the partitions packed into one file.

True when the projection covers every field in the schema.

The resolved field set when the read is narrowed; None when all is true.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The format the bytes are stored in; selects the decoder a consumer applies.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The single file this scan task resolves to.

Where two scan tasks’ subtrees contain the same field, the read takes it from the higher-precedence one.

The field subtree this scan task covers; None covers the whole schema.

Name of the topic whose records this scan task reads from its file.

A file can hold several topics (an MCAP file does when its channels carry different topic names), so a reader selects the topic’s records by this name. None when the plan does not name the topic; a reader then reads the file as holding a single topic.

Transformations applied to produce this variant, in order; empty on the original.

Checksum of the schema’s content. A consumer can cache the schema by this value.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Identifier of the resolved topic schema.

The schema field timestamps are read from; set exactly when kind is "schema_field".

How timestamps are sourced: from a schema field, or from the storage envelope.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Time unit of the designated field’s stored values (a TimeUnit value, e.g. "ms").

Only meaningful for a "schema_field" source, and only set when the schema declares the field’s unit. None when the schema does not record one; a consumer then treats non-self-describing values as nanoseconds, the unit the plan’s windows and offsets are recorded in. Envelope-derived timestamps (message log/publish time) are always assumed nanoseconds.

Inclusive upper bound, in nanoseconds.

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Inclusive lower bound, in nanoseconds.