Version: 1.9.0

tabsdata.tableframe


`Column`	Represents a single column definition in a :class:`TableFrame`.
`concat`	Combine multiple TableFrames by stacking their rows.
`empty`	Creates an empty (no column - no row) TableFrame.
`from_dict`	Creates tableframe from a dictionary, or None.
`from_pandas`	Creates tableframe from a pandas dataframe, or None.
`from_polars`	Creates tableframe from a polars dataframe or lazyframe, or None.
`lit`	Expression for the given literal value.
`Schema`
`SysCol`
`TableFrame`	> Private Functions
`TableFrame.assert_has_cols`	Ensures that the (non-system) columns in the TableFrame match the expected columns.
`TableFrame.cast`	Cast columns to a new data type.
`TableFrame.clear`	Clears all rows of the `TableFrame` preserving the schema.
`TableFrame.columns`
`TableFrame.drop`	Discard columns from the `TableFrame`.
`TableFrame.drop_nans`	Drop rows with `NaN` values.
`TableFrame.drop_nulls`	Drop rows with null values.
`TableFrame.empty`	Creates an empty (no column - no row) TableFrame.
`TableFrame.extract_as_columns`	Extract a slice of rows from the table as a column-oriented dictionary.
`TableFrame.extract_as_rows`	Extract a slice of rows from the TableFrame as a list of dictionaries.
`TableFrame.fill_nan`	Replace all `NaN` values in the `TableFrame` with the given value.
`TableFrame.fill_null`	Replace all `null` values in the `TableFrame` with the given value.
`TableFrame.filter`	Filter the `TableFrame` based on the given predicates.
`TableFrame.first`	Return a `TableFrame` with the first row.
`TableFrame.first_row`	Return a `tuple` or `dictionary` with the first row, or None if no row.
`TableFrame.from_dict`	Creates tableframe from a dictionary, or None.
`TableFrame.from_pandas`	Creates tableframe from a pandas dataframe, or None.
`TableFrame.from_polars`	Creates tableframe from a polars dataframe or lazyframe, or None.
`TableFrame.grok`	Parse log text into structured fields using a Grok pattern.
`TableFrame.group_by`	Perform a group by on the `TableFrame`.
`TableFrame.has_cols`	Verifies the presence of (non-system) columns in the TableFrame.
`TableFrame.has_same_schema`	Verifies if the schema of the current TableFrame is same than the provided TableFrame.
`TableFrame.head`	Return a `TableFrame` with the first `n` rows.
`TableFrame.is_empty`	Checks if a TableFrame has no rows.
`TableFrame.item`	Returns a scalar value if the TableFrame contains exactly one user column and one row.
`TableFrame.join`	Join the `TableFrame` with another `TableFrame`.
`TableFrame.last`	Return a `TableFrame` with the last row.
`TableFrame.last_row`	Return a `tuple` or `dictionary` with the last row, or None if no row.
`TableFrame.limit`	Return a `TableFrame` with the first `n` rows.
`TableFrame.rename`	Rename columns from the `TableFrame`.
`TableFrame.select`	Select column(s) from the `TableFrame`.
`TableFrame.slice`	Return a `TableFrame` with a slice of the original `TableFrame`
`TableFrame.sort`	Sort the `TableFrame` by the given column(s) or expression(s).
`TableFrame.tail`	Return a `TableFrame` with the last `n` rows.
`TableFrame.to_dict`	Creates a dictionary from this tableframe.
`TableFrame.to_pandas`	Creates a pandas dataframe from this tableframe.
`TableFrame.to_polars_df`	Creates a polars dataframe from this tableframe.
`TableFrame.to_polars_lf`	Creates a polars lazyframe from this tableframe.
`TableFrame.udf`	Apply a user-defined function (UDF) to the columns resolved by `expr`.
`TableFrame.unique`	Deduplicate rows from the `TableFrame`.
`TableFrame.unnest`	Expand one or more struct columns so that each field within the struct becomes a separate column in the `TableFrame`.
`TableFrame.with_columns`	Add columns to the `TableFrame`.
`to_dict`	Creates dictionary from a tableframe, or None.
`to_pandas`	Creates pandas dataframe from a tableframe, or None.
`to_polars_df`	Creates polars dataframe from a tableframe, or None.
`to_polars_lf`	Creates polars lazyframe from a tableframe, or None.
`UDF`
`UDF.columns`
`UDF.on_batch`	Creating UDFs:
`UDF.on_element`	Creating UDFs:
`UDF.with_columns`

Column

classView source ↗

class Column(name: str | None = None, dtype: td_DataType = String)

Represents a single column definition in a :class:TableFrame.

A Column defines both the name and the data type of a column, along with other relevant metadata in the future. This abstraction provides a consistent way to declare and validate schema definitions for TableFrame objects.

Attributes:

attribute

namestr | None

The name of the column, or None if no name was provided.

attribute

dtypetd_DataType

The declared data type of the column.

Example:

Create a column with a name and type:

>>> import tabsdata as td
>>> Column("customer_id", td.Int64)
<Column name='customer_id' dtype=Int64>

Use columns to define a TableFrame schema:

>>> import tabsdata as td
>>> schema = [
...     Column("customer_id", td.Int64),
...     Column("signup_date", td.Datetime),
... ]
>>> for column in schema:
...     print(column.name, column.dtype)
customer_id Int64
signup_date Datetime

empty

functionView source ↗

def empty() -> TableFrame

Creates an empty (no column - no row) TableFrame.

from_dict

functionView source ↗

def from_dict(data: td_TableDictionary | None = None) -> TableFrame

Creates tableframe from a dictionary, or None. None produces as an empty (no column - no row) tableframe.

Parameters:

parameter

data

Input data.

from_pandas

functionView source ↗

def from_pandas(data: DataFrame | None = None) -> TableFrame

Creates tableframe from a pandas dataframe, or None. None produces as an empty (no column - no row) tableframe.

Parameters:

parameter

data

Input data.

from_polars

functionView source ↗

def from_polars(data: LazyFrame | DataFrame | None = None) -> TableFrame

Creates tableframe from a polars dataframe or lazyframe, or None. None produces as an empty (no column - no row) tableframe.

Parameters:

parameter

data

Input data.

Schema

classView source ↗

class Schema(
    schema: Iterable[Column] | Mapping[str, td_SchemaInitDataType] | Iterable[tuple[str, td_SchemaInitDataType] | td_ArrowSchemaExportable] | td_ArrowSchemaExportable | None = None,
    check_dtypes: bool = True,
)

Bases: Schema

SysCol

classView source ↗

class SysCol(*args, **kwds)

Bases: StrEnum

to_dict

functionView source ↗

def to_dict(data: TableFrame) -> dict[str, list[Any]]

Creates dictionary from a tableframe, or None. None produces and empty (no key) dictionary.

Parameters:

parameter

data

Input data.

to_pandas

functionView source ↗

def to_pandas(data: TableFrame) -> DataFrame

Creates pandas dataframe from a tableframe, or None. None produces and empty (no column - no row) pandas dataframe.

Parameters:

parameter

data

Input data.

to_polars_df

functionView source ↗

def to_polars_df(data: TableFrame) -> DataFrame

Creates polars dataframe from a tableframe, or None. None produces and empty (no column - no row) polars dataframe.

Parameters:

parameter

data

Input data.

to_polars_lf

functionView source ↗

def to_polars_lf(data: TableFrame) -> LazyFrame

Creates polars lazyframe from a tableframe, or None. None produces and empty (no column - no row) polars lazyframe.

Parameters:

parameter

data

Input data.

UDF

classView source ↗

class UDF(
    output_columns: list[tuple[str, Boolean | Categorical | Date | Datetime | Decimal | Duration | Enum | Float16 | Float32 | Float64 | Int8 | Int16 | Int64 | Int32 | Int128 | Null | String | Time | UInt8 | UInt16 | UInt32 | UInt64]] | tuple[str, Boolean | Categorical | Date | Datetime | Decimal | Duration | Enum | Float16 | Float32 | Float64 | Int8 | Int16 | Int64 | Int32 | Int128 | Null | String | Time | UInt8 | UInt16 | UInt32 | UInt64],
)

Bases: ABC

property

signatureLiteral['list', 'unpacked']

Defines how parameters are passed to on_batch and on_element methods.

Returns: "list": Parameters are passed as a single list (default). "unpacked": Each parameter is passed as a separate argument.

Override this property in your UDF subclass to change the parameter style.

method

View source ↗

columns

def columns(
,
) -> list[tuple[str, Boolean | Categorical | Date | Datetime | Decimal | Duration | Enum | Float16 | Float32 | Float64 | Int8 | Int16 | Int64 | Int32 | Int128 | Null | String | Time | UInt8 | UInt16 | UInt32 | UInt64]]

method

View source ↗

on_batch

def on_batch(*args) -> list[Series]

Creating UDFs:

Subclass :class:tabsdata.tableframe.udf.function.UDF.
Implement __init__ to call super().__init__(output_columns) where output_columns is a tuple or list of tuples (name, data type) specifying the UDF default output schema (column names and data types). Each tuple must contain a column name (string) and a data type (DataType).
Override exactly one of on_batch or on_element, to implement the UDF function logic.
Return a list of TabsData Series (for on_batch) or TabsData supported scalars (for on_element) with the same length as specified in the output schema.
If overriding the on_batch method, the return type must be a list of TabsData Series. If overriding the on_element method, the return type must be a list of supported TabsData scalar values. For both cases, the number of elements in the returned lists must match the number of elements in the output_columns list provided to the UDF constructor.

Using UDFs:

Instantiate a function created as above.
Pass it to TableFrame method udf().
Optionally use :meth:UDF.output_columns to override output column names or data types after instantiation.
By default, on_batch receives a list of series. Override the signature property to return "unpacked" to receive each series as a separate argument instead.

method

View source ↗

on_element

def on_element(*args) -> list[Any]

Creating UDFs:

Subclass :class:tabsdata.tableframe.udf.function.UDF.
Implement __init__ to call super().__init__(output_columns) where output_columns is a tuple or list of tuples (name, data type) specifying the UDF default output schema (column names and data types). Each tuple must contain a column name (string) and a data type (DataType).
Override exactly one of on_batch or on_element, to implement the UDF function logic.
Return a list of TabsData Series (for on_batch) or TabsData supported scalars (for on_element) with the same length as specified in the output schema.
If overriding the on_batch method, the return type must be a list of TabsData Series. If overriding the on_element method, the return type must be a list of supported TabsData scalar values. For both cases, the number of elements in the returned lists must match the number of elements in the output_columns list provided to the UDF constructor.

Using UDFs:

Instantiate a function created as above.
Pass it to TableFrame method udf().
Optionally use :meth:UDF.output_columns to override output column names or data types after instantiation.
By default, on_element receives a list of values. Override the signature property to return "unpacked" to receive each value as a separate argument instead.

method

View source ↗

with_columns

def with_columns(
    output_columns: tuple[str | None, Boolean | Categorical | Date | Datetime | Decimal | Duration | Enum | Float16 | Float32 | Float64 | Int8 | Int16 | Int64 | Int32 | Int128 | Null | String | Time | UInt8 | UInt16 | UInt32 | UInt64 | NoneType] | list[tuple[str | None, Boolean | Categorical | Date | Datetime | Decimal | Duration | Enum | Float16 | Float32 | Float64 | Int8 | Int16 | Int64 | Int32 | Int128 | Null | String | Time | UInt8 | UInt16 | UInt32 | UInt64 | NoneType]] | dict[int, tuple[str | None, Boolean | Categorical | Date | Datetime | Decimal | Duration | Enum | Float16 | Float32 | Float64 | Int8 | Int16 | Int64 | Int32 | Int128 | Null | String | Time | UInt8 | UInt16 | UInt32 | UInt64 | NoneType]],
) -> UDF