roboto.experimental.topics.read_plan#

Module Contents#

roboto.experimental.topics.read_plan.PLAN_VERSION: int = 1#

Contract version stamped on every plan.

ReadPlan validation refuses a plan whose version it does not recognize, so a consumer on an older contract fails at parse time instead of misreading a newer plan.

class roboto.experimental.topics.read_plan.ReadPlan(/, **data)#

Bases: pydantic.BaseModel

Resolves a read of one topic over a time window into the files to fetch and how to interpret them.

Parameters:: data (Any)

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

next_page_token: str | None = None#

always None today, meaning the plan is complete inline.

The field exists so a later contract revision can page large partition sets without a breaking envelope change.

Type:: Reserved pagination seam

partitions: tuple[ReadPlanPartition, Ellipsis] = ()#: One entry per partition in the window, each its own fetch-and-interpret plan.

plan_version: int = 1#: Contract version of this plan. Validation refuses a version this model does not recognize.

projection: ReadPlanProjection#: The output fields a consumer projects decoded rows to.

schema_: ReadPlanSchemaRef | None = None#

The resolved schema on a non-empty plan. Serializes as schema.

None exactly when the plan is empty: the window contains no partitions, or a schema_id/schema_checksum matches no in-window partition (data may exist in the window under a different schema).

topic_id: str#: The topic this plan reads.

window: ReadPlanWindow#: The time window the plan resolves over.

class roboto.experimental.topics.read_plan.ReadPlanExtent(/, **data)#

Bases: pydantic.BaseModel

A partition’s time bounds, clipped to the plan window.

Parameters:: data (Any)

max: int#: Inclusive upper bound, in absolute Unix-epoch nanoseconds.

min: int#: Inclusive lower bound, in absolute Unix-epoch nanoseconds.

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

class roboto.experimental.topics.read_plan.ReadPlanFieldRef(/, **data)#

Bases: pydantic.BaseModel

A schema field named by both its id and its path components in the schema.

Parameters:: data (Any)

field_id: str#: Identifier of the schema field.

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

path: tuple[str, Ellipsis]#: The field’s path components within the schema, from the root to the field.

class roboto.experimental.topics.read_plan.ReadPlanObjectRef(/, **data)#

Bases: pydantic.BaseModel

Points to the file backing a scan task. A consumer fetches the file’s bytes from it.

Parameters:: data (Any)

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

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

class roboto.experimental.topics.read_plan.ReadPlanPartition(/, **data)#

Bases: pydantic.BaseModel

Everything needed to fetch and interpret one in-window partition’s bytes.

Parameters:: data (Any)

extent: ReadPlanExtent#: The partition’s time bounds, clipped to the window.

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

scan_tasks: tuple[ReadPlanScanTask, Ellipsis] = ()#: The files to read for this partition; empty when the partition has no readable data.

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

timestamp: ReadPlanTimestamp#: Where this partition’s row timestamps come from.

topic_part_id: str#: Identifier of the partition.

class roboto.experimental.topics.read_plan.ReadPlanProjection(/, **data)#

Bases: pydantic.BaseModel

The output fields the plan resolves rows to.

The projection takes exactly one of two forms: either every field in the schema (all is true, and the field list is left implicit so the plan need not enumerate a large schema) or an explicit fields list.

Parameters:: data (Any)

all: bool = False#: True when the projection covers every field in the schema.

classmethod all_fields()#

Return a projection covering every field in the schema.

Return type:: ReadPlanProjection

fields: tuple[ReadPlanFieldRef, Ellipsis] | None = None#: The resolved field set when the read is narrowed; None when all is true.

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

classmethod narrowed(fields)#

Return a projection narrowed to an explicit field set.

Parameters:: fields (Iterable[ReadPlanFieldRef])
Return type:: ReadPlanProjection

class roboto.experimental.topics.read_plan.ReadPlanScanTask(/, **data)#

Bases: pydantic.BaseModel

One file to open, with the format and transformations needed to interpret it.

Which of the representations satisfying the governing selector backs a scan task is service policy and may change between releases; only the selector’s hard-filter matching rule is contract.

Parameters:: data (Any)

format: roboto.domain.topics.RepresentationStorageFormat#: The format the bytes are stored in; selects the decoder a consumer applies.

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

object: ReadPlanObjectRef#: The single file this scan task resolves to.

precedence: int#: Where two scan tasks’ scopes overlap, the one with the higher precedence wins.

scope: ReadPlanFieldRef | None = None#: The field subtree this scan task covers; None covers the whole schema.

transformations: tuple[str, Ellipsis] = ()#: Transformations applied to produce this variant, in order; empty on the original.

class roboto.experimental.topics.read_plan.ReadPlanSchemaRef(/, **data)#

Bases: pydantic.BaseModel

Identifies the single topic schema the plan uses.

Parameters:: data (Any)

checksum: str#: Checksum of the schema’s content. A consumer can cache the schema by this value.

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

schema_id: str#: Identifier of the resolved topic schema.

class roboto.experimental.topics.read_plan.ReadPlanTimestamp(/, **data)#

Bases: pydantic.BaseModel

Where a partition’s row timestamps come from.

Timestamps are either read out of a schema field (kind is "schema_field", and field names which one) or taken from the storage envelope (message log or publish time), in which case no schema field is involved and field is None.

Parameters:: data (Any)

field: ReadPlanFieldRef | None = None#: The schema field timestamps are read from; set exactly when kind is "schema_field".

kind: roboto.domain.topics.TimelineSourceKind#

from a schema field, or from the storage envelope.

Type:: How timestamps are sourced

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

class roboto.experimental.topics.read_plan.ReadPlanWindow(/, **data)#

Bases: pydantic.BaseModel

The absolute time window, in Unix-epoch nanoseconds, the plan resolves over.

Parameters:: data (Any)

end: int#: Inclusive upper bound, in nanoseconds since the Unix epoch.

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

start: int#: Inclusive lower bound, in nanoseconds since the Unix epoch.