Store

featherstore.store.create_store(store_name, *, warnings='warn')

Creates a new store.

Parameters:

• store_name (str) – The name of the store to be created

• warnings (str, optional) – Whether or not to warn if the store already exist. Can be either warn or ignore, ignore passes silently if the store already exists, by default warn

Return type:

Store

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• ForbiddenStoreNameError – If store_name is reserved.

• TypeError – If store_name is not a str.

• ValueError – If warnings is not 'warn' or 'ignore'.

featherstore.store.rename_store(store_name, *, to)

Renames a store

Parameters:

• store_name (str) – The name of the store to be renamed.

• to (str) – The new name of the store.

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• StoreAlreadyExistsError – If the new store name already exists.

• ForbiddenStoreNameError – If the new store name is reserved.

• TypeError – If store_name or to is not a str.

featherstore.store.drop_store(store_name, *, warnings='warn')

Deletes a store

Warning: You can not delete a store containing tables. All tables must be deleted first.

Parameters:

• store_name (str) – The name of the store to be deleted

• warnings (str, optional) – Whether or not to warn if the store doesn’t exist. Can be either warn or ignore, by default warn

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotEmptyError – If the store still contains tables.

• TypeError – If store_name is not a str.

• ValueError – If warnings is not 'warn' or 'ignore'.

featherstore.store.list_stores(*, like=None)

Lists stores in database

Parameters:

like (str, optional) –

Filters out stores not matching string pattern, by default None.

There are two wildcards that can be used in conjunction with like:

• Question mark (?) matches any single character

• The percent sign (%) matches any number of any characters

Returns:

A list of the tables in the store

Return type:

List

featherstore.store.store_exists(store_name)

class featherstore.store.Store(store_name)

Bases: object

A class for doing basic tasks with tables within a store.

Stores are directories for organizing data in logical groups within your FeatherStore database.

Parameters:

store_name (str) – The name of the store to be selected

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenStoreNameError – If store_name is reserved.

• TypeError – If store_name is not a str.

rename(*, to)

Renames the current store

Parameters:

to (str) – The new name of the store.

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreAlreadyExistsError – If the new store name already exists.

• ForbiddenStoreNameError – If the new store name is reserved.

• TypeError – If to is not a str.

drop(*, warnings='warn')

Deletes the current store

Warning: You can not delete a store containing tables. All tables must be deleted first.

Parameters:

warnings (str, optional) – Whether or not to warn if the store doesn’t exist. Can be either warn or ignore, by default warn

list_tables(*, like=None)

Lists tables in store

Parameters:

like (str, optional) –

Filters out tables not matching string pattern, by default None.

There are two wildcards that can be used in conjunction with like:

• Question mark (?) matches any single character

• The percent sign (%) matches any number of any characters

Returns:

A list of the tables in the store

Return type:

List

table_exists(table_name)

read_arrow(table_name, *, cols=None, rows=None, mmap=None)

Reads PyArrow Table from store

Parameters:

• cols (Collection, optional) – List of column names or, filter-predicates in the form of {‘like’: pattern}. If not provided, all columns are read.

• rows (Collection, optional) – List of index values or filter-predicates in the form of {keyword: value}, where keyword can be either before, after, or between. If not provided, all rows are read.

• mmap (bool, optional) – Use memory mapping when opening table on disk, by default False on Windows and True on other systems.

Return type:

pyarrow.Table

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenTableNameError – If table_name is reserved.

• TableNotFoundError – If the table does not exist.

• ColumnNotFoundError – If any requested column is not in the table.

• RowNotFoundError – If any requested row is not in the table.

• IndexTypeMismatchError – If row values do not match the table index dtype.

• TypeError – If table_name, cols, or rows has an invalid type.

• ValueError – If mmap is not a bool or None.

read_pandas(table_name, *, cols=None, rows=None, mmap=None)

Reads Pandas DataFrame or Series from store

Parameters:

• cols (Collection, optional) – List of column names or, filter-predicates in the form of {‘like’: pattern}. If not provided, all columns are read.

• rows (Collection, optional) – List of index values or filter-predicates in the form of {keyword: value}, where keyword can be either before, after, or between. If not provided, all rows are read.

• mmap (bool, optional) – Use memory mapping when opening table on disk, by default False on Windows and True on other systems.

Return type:

pandas.DataFrame or pandas.Series

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenTableNameError – If table_name is reserved.

• TableNotFoundError – If the table does not exist.

• ColumnNotFoundError – If any requested column is not in the table.

• RowNotFoundError – If any requested row is not in the table.

• IndexTypeMismatchError – If row values do not match the table index dtype.

• TypeError – If table_name, cols, or rows has an invalid type.

• ValueError – If mmap is not a bool or None.

read_polars(table_name, *, cols=None, rows=None, mmap=None)

Reads Polars DataFrame or Series from store

Parameters:

• cols (Collection, optional) – List of column names or, filter-predicates in the form of {‘like’: pattern}. If not provided, all columns are read.

• rows (Collection, optional) – List of index values or filter-predicates in the form of {keyword: value}, where keyword can be either before, after, or between. If not provided, all rows are read.

• mmap (bool, optional) – Use memory mapping when opening table on disk, by default False on Windows and True on other systems.

Return type:

polars.DataFrame or polars.Series

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenTableNameError – If table_name is reserved.

• TableNotFoundError – If the table does not exist.

• ColumnNotFoundError – If any requested column is not in the table.

• RowNotFoundError – If any requested row is not in the table.

• IndexTypeMismatchError – If row values do not match the table index dtype.

• TypeError – If table_name, cols, or rows has an invalid type.

• ValueError – If mmap is not a bool or None.

write_table(table_name, df, /, index=None, *, partition_size=134217728, errors='raise', warnings='warn')

Writes a DataFrame to the current store as a partitioned table

The DataFrame index column, if provided, must be either of type int, str, or datetime. FeatherStore sorts the DataFrame by the index before storage.

Parameters:

• table_name (str) – The name of the table the DataFrame will be stored as

• df (pandas DataFrame or Series, polars DataFrame or Series, or pyarrow Table) – The DataFrame to be stored

• index (str, optional) – The name of the column to be used as index. Uses current index for Pandas or a standard integer index for Arrow and Polars if index not provided, by default None

• partition_size (int, optional) – The size of each partition in bytes, by default 128 MB

• errors (str, optional) – Whether or not to raise an error if the table already exist. Can be either raise or ignore, ignore overwrites existing table, by default raise

• warnings (str, optional) – Whether or not to warn if a unsorted index is about to get sorted. Can be either warn or ignore, by default warn

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenTableNameError – If table_name is reserved.

• TableAlreadyExistsError – If errors='raise' and the table already exists.

• DuplicateColumnNamesError – If column names are not unique.

• DuplicateIndexValuesError – If index values are not unique.

• IndexNameMismatchError – If the index name does not match the stored table.

• IndexNotInColumnsError – If index is not among the table columns.

• IndexTypeMismatchError – If the index type does not match the stored table.

• UnsupportedIndexTypeError – If the index type is not supported.

• MultiTypeColumnError – If a column contains multiple dtypes.

• TypeError – If arguments have invalid types.

• ValueError – If errors or warnings is invalid.

append_table(table_name, df, *, warnings='warn')

Appends data to a table

Parameters:

• table_name (str) – The name of the table you want to append to

• df (Pandas DataFrame or Series, Polars DataFrame or Series, or Pyarrow Table) – The data to be appended

• warnings (str, optional) – Whether or not to warn if a unsorted index is about to get sorted. Can be either warn or ignore, by default warn

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenTableNameError – If table_name is reserved.

• TableNotFoundError – If the table does not exist.

• AppendIndexError – If append index is not strictly after stored data.

• ColumnDtypeMismatchError – If column dtypes are incompatible.

• ColumnMismatchError – If column names do not match the stored table.

• DuplicateColumnNamesError – If column names are not unique.

• DuplicateIndexValuesError – If index values are not unique.

• IndexNameMismatchError – If the index name does not match the stored table.

• IndexTypeMismatchError – If the index type does not match the stored table.

• MissingIndexError – If an index is required but not provided.

• TypeError – If arguments have invalid types.

• ValueError – If warnings is invalid.

rename_table(table_name, *, to)

Renames a table

Parameters:

• table_name (str) – The name of the table to be renamed

• to (str) – The new name of the table.

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• StoreNotFoundError – If the store does not exist.

• ForbiddenTableNameError – If table_name or to is reserved.

• TableAlreadyExistsError – If the new table name already exists.

• TypeError – If table_name or to is not a str.

drop_table(table_name, *, warnings='warn')

Deletes a table

Parameters:

• table_name (str) – The name of the table to be deleted

• warnings (str, optional) – Whether or not to warn if the table doesn’t exist. Can be either warn or ignore, by default warn

select_table(table_name)

Selects a single table.

Table objects have more features for editing stored tables.

Parameters:

table_name (str) – The name of the table to be returned

Return type:

Table

create_snapshot(path)

Creates a compressed backup of the store.

The store can later be restored by using snapshot.restore_store().

Parameters:

path (str) – The path to the snapshot archive.

Raises:

• NotConnectedError – If FeatherStore is not connected to a database.

• SnapshotTargetNotFoundError – If the store path does not exist.

• TypeError – If path is not a str.