PolarsExportHandler#

class nominal.thirdparty.polars.polars_export_handler.PolarsExportHandler(client: NominalClient, points_per_request: int = DEFAULT_POINTS_PER_REQUEST, points_per_dataframe: int = DEFAULT_POINTS_PER_DATAFRAME, channels_per_request: int = DEFAULT_CHANNELS_PER_REQUEST, num_workers: int = DEFAULT_NUM_WORKERS)#

Bases: object

Streams data out of Nominal into Polars DataFrames.

Pipeline:

  • Filter to exportable channel types (DOUBLE/INT/STRING).

  • Confirm each channel has data in the range (via filter_channels_with_data) and estimate per-channel peak points-per-second.

  • Compute a batch duration such that each DataFrame batch stays under points_per_dataframe, unless the caller passes an explicit batch_duration.

  • Bin-pack channels into per-request groups within the points_per_request rate budget; channels whose rate exceeds the budget are split across sub-slices of the time range.

  • For each time slice, fetch channel groups in parallel and stitch the results back into a single DataFrame (via vertical concat within equal-column groups, outer-join across groups on the timestamp column) before yielding.

Initialize export handler

export(channels: Sequence[Channel], start: int, end: int, tags: Mapping[str, str] | None = None, batch_duration: timedelta | None = None, timestamp_type: Iso8601 | Epoch | Relative | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] = 'epoch_seconds', buckets: int | None = None, resolution: int | None = None, join_batches: bool = True) → Iterator[DataFrame]#

Yield exported data one DataFrame at a time.

Only DOUBLE, INT, and STRING channels flow through the export pipeline; channels of any other data type are filtered out with a warning.

Parameters:

  • channels – Channels to export.

  • start – Start of the export time range (nanoseconds UTC).

  • end – End of the export time range (nanoseconds UTC).

  • tags – Key-value pairs used to filter channel data server-side.

  • batch_duration – Explicit per-batch time window. If omitted, one is computed from total channel rate and points_per_dataframe.

  • timestamp_type – Output timestamp representation (epoch_seconds, iso8601, etc.).

  • buckets – Decimate each channel to at most this many buckets per request. Mutually exclusive with resolution.

  • resolution – Decimate each channel to samples at this interval (nanoseconds). Mutually exclusive with buckets.

  • join_batches – If True (default), each yielded DataFrame is the outer-joined merge of all channel groups for a single time slice. If False, yields one DataFrame per channel group without merging.

Yields:

Polars DataFrames covering successive time slices of the export range.