[JosteinGj]

Stacked on #175 — review that first; this diff is only the streaming change.

What

• TimeSeriesService::stream_datapoints_binary returns a Stream of BinaryDatapoints, one item per frame, decoded on spawn_blocking (at most min(cores, 8) frames in flight, kept in order) while the rest of the response downloads. A FrameAssembler cuts the body into frames however the HTTP chunks fall. The blocking client has it as an iterator.
• retrieve_datapoints_binary now collects that stream and merges each series once at its final size, so the buffered call decodes during the download too.
• Python: retrieve_datapoints_binary_stream(filters) returns a single-use BinaryDatapointReader. Iterate it for one BinaryDatapoints per frame (mixed value types fine), or pass it to polars.DataFrame(reader) / reader.to_polars() for one long table of timeseries_id, timestamp and the value columns; reader.external_ids maps the ids. A read mixing value types can't share one Arrow schema and must be iterated.

Behaviour to know

A refusal is still the Err before there is a stream. A response that breaks off is an error item after the items that arrived, so a consumer acting on items as they come must treat what it took as incomplete. The buffered call remains all-or-nothing. Documented in the Rust docs, the .pyi, README and AGENTS.md.

The long table has no external_id column on purpose: as a dictionary column, polars spent ~0.76 s per 100M rows making it categorical, more than everything else.

Measured

100M float rows, 10 series, release build, against the platform branch:

	time	SDK overhead over the server
server alone (curl)	6.54 s	—
buffered, before this PR	7.08 s	+0.90 s
retrieve_datapoints_binary → polars	6.78 s	+0.24 s
retrieve_datapoints_binary_stream(...).to_polars()	6.56 s	+0.02 s

Tests

• Offline (Rust): frames split at any chunk size (1 to 64 KiB), items arriving before the body ends (the test server holds the rest back), a cut-short stream, a bad frame mid-stream.
• Offline (Python): a chunked stand-in server for the same cases plus the long table, read-once, mixed schemas and empty reads.
• Live: the streamed twin in test_datapoints_binary_read and the Python live test match the buffered read.

One table, buffered or streamed (2bebeaf)

retrieve_datapoints_binary now returns a BinaryReadResult instead of a plain list. It is still a sequence of per-series BinaryDatapoints, so indexing and iteration are unchanged, but it gains what the streamed reader has: external_ids, the long-table Arrow stream and to_polars. Both call one pure-Python helper (_tables.py), so the two cannot drift.

to_polars(wide=True) gives one row per timestamp and one column per series, named by external id ({external_id}.{column} for mixed and aggregate series), nulls where a series has no point:

path	when	100M rows
side by side	every series on the same timestamps	~0 s
pivot on a numeric key	one value column of one type	1.7 s
align	different value types or several value columns	slower, keeps each type

Measured end to end, 10 × 10M float rows: buffered and streamed, long or wide, all land within 0.07–0.50 s of the server's 6.5 s.

Docs

Affects datahub-sdk-docs docs/guides/query-and-aggregate.mdx (streaming reads, the long table and the error semantics) and the Python reference from the .pyi stub.

🤖 Generated with Claude Code

[JosteinGj]

Included in #177, which now targets main and carries this PR's commits unchanged.