colstore.open

colstore.open(path: str | PathLike[str], **kwargs: Any) → ColStoreReader[source]
colstore.open(path: Sequence[str | PathLike[str]], **kwargs: Any) → ColStoreDataset

Open an existing .cstore file, or several as one logical dataset.

A single literal path (str or os.PathLike) returns a ColStoreReader, equivalent to ColStoreReader(path, **kwargs). A list or tuple of paths returns a ColStoreDataset spanning the files in order (all must share one schema), including for a one-element list (a single-file dataset) and an empty list (an empty dataset, which can be grown later). The dataset owns the files it opened and closes them on close(). Each file must exist and be valid; otherwise FileNotFoundError or FormatError propagates.

A str containing a shell glob (*, ?, [; ** is recursive) is expanded to its matches and returns a ColStoreDataset – e.g. open("run_*.cstore") opens every matching file as one logical table. Matches are ordered numerically (run_2 before run_10), since file order is the dataset’s row order, and a pattern matching no files raises FileNotFoundError. Globbing applies to path arguments only – column selection is always explicit – and a list element may itself be a glob.

A directory path returns a ColStoreDataset over its .cstore shards in numeric order – the managed dataset that append() / appender() write to (an empty directory is an empty dataset).

For a multi-file dataset, on_mismatch chooses how files whose schemas differ are reconciled. "strict" (the default) requires every file to share one schema – the same column names and dtypes, though the column order may differ since reads are by name – and raises ValueError otherwise. "drop" instead opens the files anyway, exposing only the columns common to every file with one consistent dtype and warning about the rest – useful for opening a set of files where a column’s dtype drifted between writes. It is moot for a single file.

Parameters:
Return type:

ColStoreReader | ColStoreDataset