ursa.get

Phase 1a (M2) — raw path only

For each modality with ingestion_status="raw", list the segment files under ModalityRow.raw_storage_uri (a prefix), fetch each segment’s bytes, and surface them on the returned Data as a

class:

ursa.RawBytes carrier under data.modalities[name]. No parsing, no time domain. data.metadata is the synthesized

class:

RecordingRow (ENG-1090 contract).

All raw formats — including RAW_VIDEO / RAW_AUDIO — materialize in full. Multi-hour video recordings can easily exceed several GB; memory-constrained callers should use :func:ursa.download instead.

Phase 1b / M3 — processed path

Deferred to ENG-1093. Once a modality has ingestion_status="processed", the modality field becomes an array-bearing :class:RegularTimeSeries /

class:

IrregularTimeSeries subclass. get() currently raises

class:

NotImplementedError for processed inputs as a defensive guard; the runtime path arrives with ENG-1093.

Concat

concat=True over multiple recordings would require aligned time domains, which only the processed path establishes — so the M2 stub validates alignment (raises :class:ValueError on mismatched modality sets) and then raises :class:NotImplementedError pointing at ENG-1093. The single-input case ignores concat (ticket spec: “single-input ergonomic case … regardless of concat”).

Materialize :class:QueryResult rows into in-memory :class:ursa.Data objects (ENG-890).

Second verb in the M2 three-verb read API (query → get → download): query() selects, get() reads bytes into memory, and download() (ENG-1091) writes them to disk. All filtering lives in query() — get() accepts a :class:QueryResult (or iterable of them) plus a single concat flag and nothing else.

Module Contents

Functions

get	Materialize target into in-memory :class:ursa.Data objects.
_get_one	Build a single :class:Data from one :class:QueryResult.
_recording_row_from	Project qr onto :class:RecordingRow’s field set.
_materialize_modality	Read all segment files under mrow.raw_storage_uri into a :class:RawBytes.
_validate_alignment	Raise ValueError if recordings have mismatched modality sets.

Data

__all__
_PROCESSED_PATH_TICKET
_RECORDING_ROW_FIELDS

API

ursa.get.__all__

[‘get’]

ursa.get._PROCESSED_PATH_TICKET

‘ENG-1093’

ursa.get._RECORDING_ROW_FIELDS: tuple[str, ...]

(‘recording_hash’, ‘participant_ids’, ‘start_time’, ‘duration’, ‘device_info’, ‘metadata’)

ursa.get.get(target: ursa.query.QueryResult | collections.abc.Iterable[ursa.query.QueryResult], *, concat: bool = False) → ursa.temporal.Data | list[ursa.temporal.Data]

Materialize target into in-memory :class:ursa.Data objects.

Parameters

target A single :class:QueryResult or any iterable of them. The single-input form returns a single :class:Data; the iterable form returns a list[Data] (including a one-element list when the iterable has one item — disambiguation is by type, not by length). concat When True and target is an iterable, concatenate the per-recording outputs along the time axis. M2 only — alignment is validated and NotImplementedError is raised because raw modalities carry no time domain. When target is a single :class:QueryResult, concat is ignored.

Returns

Data or list[Data] Each returned :class:Data has its metadata slot populated with a :class:RecordingRow synthesized from the source :class:QueryResult. Modality payloads are accessible as data.modalities[name] and are :class:ursa.RawBytes carriers in M2.

Raises

NotImplementedError If any matched modality has ingestion_status="processed" (deferred to ENG-1093) or if concat=True is requested over an aligned iterable. ValueError If concat=True is requested over recordings with mismatched modality sets.

Notes

All raw formats — including RAW_VIDEO / RAW_AUDIO — are materialized in full into memory. A multi-hour video recording can easily exceed several GB; callers running on memory-constrained hosts should use :func:ursa.download instead.

ursa.get._get_one(qr: ursa.query.QueryResult) → ursa.temporal.Data

Build a single :class:Data from one :class:QueryResult.

ursa.get._recording_row_from(qr: ursa.query.QueryResult) → ursa.catalog.schemas.RecordingRow

Project qr onto :class:RecordingRow’s field set.

Uses an explicit field tuple so a future :class:QueryResult schema change breaks here at validation time, not silently inside Pydantic.

ursa.get._materialize_modality(name: str, mrow: ursa.catalog.schemas.ModalityRow) → ursa.raw.RawBytes

Read all segment files under mrow.raw_storage_uri into a :class:RawBytes.

ursa.get._validate_alignment(results: list[ursa.temporal.Data]) → None

Raise ValueError if recordings have mismatched modality sets.