Store#

featherstore.store.create_store(store_name, *, errors='raise')[source]#

Creates a new store.

Parameters

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

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

Return type

Store

featherstore.store.rename_store(store_name, *, to)[source]#

Renames a store

Parameters

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

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

featherstore.store.drop_store(store_name, *, errors='raise')[source]#

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

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

featherstore.store.list_stores(*, like=None)[source]#

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)[source]#
class featherstore.store.Store(store_name)[source]#

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

rename(*, to)[source]#

Renames the current store

Parameters

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

drop(*, errors='raise')[source]#

Deletes the current store

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

Parameters

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

list_tables(*, like=None)[source]#

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)[source]#
read_arrow(table_name, *, cols=None, rows=None, mmap=None)[source]#

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

read_pandas(table_name, *, cols=None, rows=None, mmap=None)[source]#

Reads Pandas DataFrame 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

read_polars(table_name, *, cols=None, rows=None, mmap=None)[source]#

Reads Polars DataFrame 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

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

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, Pyarrow Table, or Polars DataFrame) – 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

append_table(table_name, df, warnings='warn')[source]#

Appends data to a table

Parameters

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

  • df (Pandas DataFrame or Series, Pyarrow Table, or Polars DataFrame) – 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

rename_table(table_name, *, to)[source]#

Renames a table

Parameters

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

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

drop_table(table_name)[source]#

Deletes a table

Parameters

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

select_table(table_name)[source]#

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)[source]#

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.