ursa.backends.lance

Lance-backed reader for StorageFormat.LANCE modalities.

Used by genuinely-event modalities (keyboard, mouse, browser, notes, battery, location). High-density “almost-regular” streams like pupillabs-gaze deliberately go to Zarr instead — see the Zarr-vs-Lance rule of thumb (fixed payload + dense → Zarr; variable payload or sparse → Lance).

Two callable surfaces:

• The materialized opener wired through the temporal-class dispatcher (:func:ursa.IrregularTimeSeries.from_uri → backend factory) loads the whole table and populates an IrregularTimeSeries instance.

• The free-standing :class:LazyLanceIrregularTimeSeries exposes a column-on-access __getattr__ that pushes timestamp >= t0 AND timestamp < t1 filters down to DataFusion on the next read after :meth:slice. Reach for it via

  func:

  open_lance_irregular_lazy_freestanding (or the class directly) when DataInterface.materialize(lazy=False) would materialize too much.

Sort-by-timestamp contract: writers MUST sort by timestamp and emit an ursa.sorted_by="timestamp" flag in the dataset’s user metadata. Readers warn (don’t raise) if the flag is absent — the slice still works but the scan is unbounded.

Timestamp-unit contract: the timestamp column MUST be float64 recording-relative seconds. The reader rejects other Arrow types (notably int64 nanoseconds) up-front via :func:_check_timestamp_column so a writer that picks the wrong unit fails fast instead of silently producing a series with a ~55-billion-year domain.

Module Contents

Classes

LazyLanceIrregularTimeSeries

Streaming-pointer Lance reader for irregular event streams.

Functions

open_lance_irregular_lazy_freestanding	Construct the free-standing :class:LazyLanceIrregularTimeSeries.
_open_lance_irregular_materialized
_open_lance_irregular_lazy

API

class ursa.backends.lance.LazyLanceIrregularTimeSeries(uri: str, *, store: ursa.store.base.ObjectStore, metadata: ursa.catalog.schemas.ModalityRow | None = None)

Streaming-pointer Lance reader for irregular event streams.

Construction reads only dataset metadata (schema + row count + sort-metadata check). Column access via __getattr__ triggers a per-column Lance scan; if :meth:slice was called first, the scan is pushed down to a half-open timestamp >= t0 AND timestamp < t1 filter via DataFusion.

Free-standing on purpose: the upstream

Class:

temporaldata.LazyIrregularTimeSeries materialization gate expects h5py.Dataset- or zarr.Array-shaped column handles, and Lance’s column-scan model doesn’t slot in cleanly. The class exposes the same external surface (.slice(), attribute-style column access, .metadata) so callers don’t need to branch on backend type.

Initialization

_RESERVED

‘frozenset(…)’

property metadata: ursa.catalog.schemas.ModalityRow | None

__len__() → int

__repr__() → str

__getattr__(name: str) → Any

_fetch_column(name: str) → numpy.ndarray

Issue the Lance scan for one column with optional time pushdown.

slice(start: float, end: float, reset_origin: bool = True) → ursa.backends.lance.LazyLanceIrregularTimeSeries

Return a new lazy view restricted to [start, end).

reset_origin=True (default) is recorded for downstream materialization — when the timestamps column is fetched, the values are shifted by -start before being returned, matching

Meth:

temporaldata.IrregularTimeSeries.slice’s default.

Both bounds must be finite. inf/nan would flow into the DataFusion filter as literal inf/nan and produce an opaque parse error deep inside Lance; we catch that here and raise a clean ValueError instead.

property timestamps: numpy.ndarray

Materialize the timestamp column, applying the slice-origin shift.

ursa.backends.lance.open_lance_irregular_lazy_freestanding(uri: str, store: ursa.store.base.ObjectStore, metadata: ursa.catalog.schemas.ModalityRow | None) → ursa.backends.lance.LazyLanceIrregularTimeSeries

Construct the free-standing :class:LazyLanceIrregularTimeSeries.

NOT the dispatcher opener — that’s :func:_open_lance_irregular_lazy above and intentionally raises (see its docstring). This helper exists for callers (notably :meth:DataInterface.materialize) that want column-on-demand Lance access via the free-standing class rather than through LazyIrregularTimeSeries.from_uri.

ursa.backends.lance._open_lance_irregular_materialized(instance: Any, uri: str, *, store: ursa.store.base.ObjectStore, metadata: ursa.catalog.schemas.ModalityRow | None, max_fallback_bytes: int | None = None) → None

ursa.backends.lance._open_lance_irregular_lazy(instance: Any, uri: str, *, store: ursa.store.base.ObjectStore, metadata: ursa.catalog.schemas.ModalityRow | None, max_fallback_bytes: int | None = None) → None