Skip to content

Spans

rerun.experimental.spans

Annotate and query time spans within dataset recordings.

SpanTable

Time span annotations for a dataset.

Data columns and one duration or timestamp timeline are fixed at creation. Every row requires inclusive start and end boundaries, stored in nanoseconds. Sequence timelines are unsupported.

Span annotations have an independent lifecycle from their dataset.

dataset property
dataset: DatasetEntry

The dataset whose recordings the spans select.

table property
table: TableEntry

The table containing these span annotations.

__init__
def __init__(dataset: DatasetEntry, table: TableEntry) -> None

Wrap an existing span table; SpanTable.open finds a table by name.

PARAMETER DESCRIPTION
dataset

The dataset whose segments the spans annotate.

TYPE: DatasetEntry

table

A table with a span schema, as created by SpanTable.create.

TYPE: TableEntry

RAISES DESCRIPTION
ValueError

If table is not a span table, or its timeline is not in dataset with the same type.

append
def append(
    *,
    segment_id: str,
    start: timedelta | timedelta64,
    end: timedelta | timedelta64,
    data: Mapping[str, Any] | None = None,
) -> str
def append(
    *,
    segment_id: str,
    start: datetime | datetime64,
    end: datetime | datetime64,
    data: Mapping[str, Any] | None = None,
) -> str
def append(
    *,
    segment_id: str,
    start: _Boundary,
    end: _Boundary,
    data: Mapping[str, Any] | None = None,
) -> str

Append one span and return its generated ID; data values populate declared columns.

segment_id must name a segment of the dataset. start and end are inclusive. Duration timelines take datetime.timedelta or numpy.timedelta64 boundaries. Timestamp timelines take datetime.datetime or numpy.datetime64 boundaries; naive datetimes are UTC. Values convert exactly to nanoseconds.

RAISES DESCRIPTION
TypeError

If a boundary type does not match the timeline kind.

ValueError

If a boundary is not exact in nanoseconds, start is after end, data names an undeclared or managed column, or segment_id is not in the dataset.

arrow_schema
def arrow_schema() -> Schema

Returns the Arrow schema of the underlying table entry, which is fixed at creation.

create classmethod
def create(
    dataset: DatasetEntry,
    index: str,
    *,
    name: str | None = None,
    schema: Schema | None = None,
    url: str | None = None,
) -> SpanTable

Create an empty table on the duration or timestamp timeline index; schema declares data columns.

name defaults to a name in the catalog's spans folder derived from the dataset ID.

RAISES DESCRIPTION
AlreadyExistsError

If a table named name already exists.

ValueError

If index is not a duration or timestamp timeline of the dataset, or schema declares a reserved column.

delete
def delete() -> None

Delete this table without deleting its dataset.

open classmethod
def open(
    dataset: DatasetEntry, *, name: str | None = None
) -> SpanTable

Open a span table of dataset.

name defaults to a name in the catalog's spans folder derived from the dataset ID.

RAISES DESCRIPTION
LookupError

If no table named name exists.

reader
def reader() -> DataFrame

Build a lazy DataFusion query on one timeline, joined with recording properties.

Filtering selects whole spans without altering boundaries or subtracting overlaps. Spans on segments no longer in the dataset are omitted, as are properties named like a span column. Low-level table writes remain responsible for valid span rows.

upsert
def upsert(
    *,
    segment_id: str,
    start: timedelta | timedelta64,
    end: timedelta | timedelta64,
    span_id: str,
    data: Mapping[str, Any] | None = None,
) -> str
def upsert(
    *,
    segment_id: str,
    start: datetime | datetime64,
    end: datetime | datetime64,
    span_id: str,
    data: Mapping[str, Any] | None = None,
) -> str
def upsert(
    *,
    segment_id: str,
    start: _Boundary,
    end: _Boundary,
    span_id: str,
    data: Mapping[str, Any] | None = None,
) -> str

Insert or fully replace a row by its required ID; omitted nullable data columns become null.

start and end follow the same typed boundary rules as SpanTable.append.

RAISES DESCRIPTION
TypeError

If span_id is not a string, or a boundary type does not match the timeline kind.

ValueError

If span_id is empty, or for the same invalid spans as SpanTable.append.

write
def write(
    spans: Table | RecordBatch,
    *,
    mode: Literal[
        "append", "upsert", "overwrite"
    ] = "append",
) -> None

Write Arrow rows, generating missing IDs; overwrite with empty input clears the table.

Caller-supplied IDs must remain unique. Upsert replaces entire rows rather than patching columns.

RAISES DESCRIPTION
ValueError

If a column is undeclared, duplicated, or has the wrong ID type; a required column contains nulls; an ID is empty; a start is the minimum 64-bit value or after its end; or a rerun_segment_id is not in the dataset.