roboto.experimental.topics.record

Module Contents

class roboto.experimental.topics.record.RepresentationRecord(/, **data)

Bases: pydantic.BaseModel

One stored variant of a topic partition’s data, optionally narrowed to a subset of its fields.

A representation pairs a stored file with the data of a single topic partition. field_id narrows it to one field and the fields nested under it; None covers every field in the partition.

The same partition can have several representations that differ in storage_format, content_format, and transformations. A consumer picks the one whose attributes suit it: a viewer of image data, for example, may prefer a JPEG- or PNG-encoded variant over the untransformed original.

Parameters:

data (Any)

content_format: str | None = None

The format of the data inside the stored file. For image data, this may be the image encoding (e.g. "jpeg", "png") on a transformed variant. None when unspecified.

created: datetime.datetime | None = None

created_by: str

field_id: str | None = None

The field this representation is narrowed to, covering that field and the fields nested under it. None when the representation covers every field in the partition.

fs_node_id: str

Identifier of the file backing this representation.

model_config

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

modified: datetime.datetime | None = None

modified_by: str

org_id: str

representation_id: str

storage_format: roboto.domain.topics.RepresentationStorageFormat

Container the representation data is stored in (e.g. MCAP, Parquet).

topic_part_id: str

Identifier of the topic partition this representation belongs to.

transformations: list[str] = None

The transformations applied to the source data to produce this variant, in the order applied. Empty on the untransformed original.

Each entry is a "<kind>:<param>" string whose <kind> is a TransformationKind member, e.g. ["downsample:0.5", "encode:jpeg"].

class roboto.experimental.topics.record.RepresentationSelector(/, **data)

Bases: pydantic.BaseModel

Selects which stored variant of a field to read when several are available.

A selector has three optional criteria — storage_format, content_format, and transformations — one for each attribute on which stored variants of the same field can differ (see RepresentationRecord). A criterion that is set is a requirement a variant must meet to be selected; a criterion left None places no requirement, and any value is acceptable.

A selector never falls back to a variant other than the one it describes. If any criterion is set and no stored variant of a requested field meets every requirement — whether the variants that exist all fall short, or the field has no stored variant at all — the read fails with an error rather than quietly leave out the field. Only under a selector with no criteria set is a field with no stored variant simply absent from the result; such a selector requires nothing, so nothing requested is missing.

Successor to roboto.domain.topics.RepresentationSelector, which get_data() uses. This class keeps the same no-fallback matching, and adds an explicit storage_format criterion and a more expressive way to specify required transformations.

Parameters:

data (Any)

content_format: str | None = None

Required content encoding (e.g. "jpeg") by scalar equality; None does not constrain it.

There is no legacy carve-out: a representation whose content_format is None does not satisfy an explicit request.

matches(representation)

Return whether representation satisfies every set axis of this selector.

Parameters:

representation (RepresentationRecord)

Return type:

bool

model_config

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

classmethod raw()

Select the untransformed original (a representation with no transformations).

Return type:

RepresentationSelector

storage_format: roboto.domain.topics.RepresentationStorageFormat | None = None

Required container (e.g. MCAP, Parquet) by scalar equality; None does not constrain it.

transformations: tuple[str, Ellipsis] | None = None

Required transformations; None does not constrain, () requires the untransformed original.

A non-empty tuple is all-of: every token must be satisfied by some descriptor on the representation, which may carry additional transformations. A token is either a bare kind (e.g. "downsample"), satisfied by any descriptor whose kind prefix equals it, or a full "<kind>:<param>" descriptor (e.g. "encode:jpeg"), satisfied only by an exact match. The grammar is open string matching; the recognized vocabulary (TransformationKind) is enforced by the service at the request boundary, which rejects a token naming an unrecognized kind.