PolarsExportHandler#

class nominal.thirdparty.polars.polars_export_handler.PolarsExportHandler(client, points_per_request=DEFAULT_POINTS_PER_REQUEST, points_per_dataframe=DEFAULT_POINTS_PER_DATAFRAME, channels_per_request=DEFAULT_CHANNELS_PER_REQUEST, num_workers=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, start, end, tags=None, batch_duration=None, timestamp_type='epoch_seconds', buckets=None, resolution=None, join_batches=True)#

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 (Sequence[Channel])

    Channels to export.

  • start (int)

    Start of the export time range (nanoseconds UTC).

  • end (int)

    End of the export time range (nanoseconds UTC).

  • tags (Mapping[str, str] | None)

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

  • batch_duration (timedelta | None)

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

  • timestamp_type (Iso8601 | Epoch | Relative | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'])

    Output timestamp representation (epoch_seconds, iso8601, etc.).

  • buckets (int | None)

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

  • resolution (int | None)

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

  • join_batches (bool)

    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.

Return type:

Iterator[DataFrame]