roboto.experimental.topics.operations#

Module Contents#

class roboto.experimental.topics.operations.FieldAddress(/, **data)#

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)

field_id: str | None = None#: The field’s opaque id (sf_*).

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

path: tuple[str, ...] | None = None#: The field’s path_in_schema components; () addresses the schema root.

class roboto.experimental.topics.operations.ReadPlanRequest(/, **data)#

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)

dataset_id: str | None = None#: Limits the read to the topic’s data in this dataset’s files; None adds no dataset restriction.

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.

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.

fields_exclude: tuple[FieldAddress, ...] | None = None#: Field subtrees to drop from the projection; None drops none.

fields_include: tuple[FieldAddress, ...] | None = None#: Field subtrees to project; None projects every field.

file_id: str | None = None#: Limits the read to the topic’s data in this file; None adds no file restriction.

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

prefer: RepresentationPreference | None = None#: Per-subtree representation preference; None applies default selection everywhere.

schema_checksum: str | None = None#: Schema to use, by checksum, or None.

schema_id: str | None = None#: Schema to use, by id, or None to default to the sole in-window schema.

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.

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.

timeline_source_id: str | None = None#: Timeline source to resolve partition extents with, by id, or None.

timeline_source_name: str | None = None#: Timeline source to resolve partition extents with, by name, or None.

class roboto.experimental.topics.operations.RepresentationOverride(/, **data)#

Bases: pydantic.BaseModel

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

Parameters:: data (Any)

field: FieldAddress#: The subtree this override covers.

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

selector: roboto.experimental.topics.record.RepresentationSelector#: The selector to apply within that subtree.

class roboto.experimental.topics.operations.RepresentationPreference(/, **data)#

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().

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)

default: roboto.experimental.topics.record.RepresentationSelector#: The selector applied to any field no override covers; matches anything when unset.

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

overrides: tuple[RepresentationOverride, ...] = ()#: Per-subtree selector overrides, resolved longest-matching-prefix wins.

selector_for(field_path)#

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:: 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.
Return type:: roboto.experimental.topics.record.RepresentationSelector

class roboto.experimental.topics.operations.SetTopicUnixOffsetRequest(/, **data)#

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() for the write’s reach.

Parameters:: data (Any)

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

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.

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 at runtime, read as roboto.time.to_epoch_nanoseconds() reads it; convert with that function first to satisfy a type checker.