bdf.save

bdf.save(df: pl.DataFrame | pl.LazyFrame | pd.DataFrame, pathlike: str | Path, *, metadata: Metadata | None = None, validate: bool = True, labels: Literal['preferred', 'machine', 'unchanged'] = 'unchanged', **opts) → None

Save a BDF table to a CSV/parquet/IPC/JSON/ndjson/xlsx artifact.

Detects format and compression from the file extension and creates parent directories as needed.

A LazyFrame reaches the target through the polars sink_* writer of the format, so polars streams the table and does not materialize it first. JSON and xlsx have no sink, so a LazyFrame collects for those two formats.

Parameters:

• df – BDF table to write.

• pathlike – Output file path; format/compression are inferred from its extension.

• metadata – Optional Metadata written alongside as a .metadata.json sidecar (mydata.bdf.parquet pairs with mydata.bdf.metadata.json). A Metadata carrying nothing deletes the sidecar, so the artifact keeps no metadata. Omit the argument only where the target has no sidecar: a save that omits it beside an existing sidecar raises, because the sidecar describes the data the previous save wrote. The message states each out, one of which is a save to a different path.

• validate – Check columns against the BDF ontology, raising on missing required ones (default True); False only warns.

• labels – Style of column names to use (default: “unchanged”): “preferred”: BDF preferred label, e.g. “Voltage / V” “machine”: BDF machine-readable label e.g. “voltage_volt” “unchanged”: Keep column names as-is

• **opts – Additional keyword arguments forwarded to the polars writer (write_csv/write_parquet/write_ipc/write_json/write_ndjson/ write_excel), or to the matching sink_* writer where df is a streamed LazyFrame.

Raises:

• ValueError – If the format is unsupported, or compression is requested for xlsx output.

• FileExistsError – If metadata is omitted and a .metadata.json sidecar already sits beside the target.