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.
__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:
|
table
|
A table with a span schema, as created by
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If |
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, |
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 |
ValueError
|
If |
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 |
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 |
ValueError
|
If |
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 |