Databases¶

database ¶

The schema model: tables, relationships, and the database that holds them.

Database¶

Database ¶

Database(name)

A collection of related tables that DFS can synthesize features over.

Create an empty database.

Parameters:

Name	Type	Description	Default
`name`	`str`	Human-readable identifier for this database.	required

name `instance-attribute` ¶

name = name

table_names `property` ¶

table_names

Names of every table in the database.

relationships `property` ¶

relationships

Every relationship in the database, in insertion order.

add_table ¶

add_table(
    name,
    table,
    primary_key=None,
    row_creation_time=None,
    *,
    validate=False,
)

Add a table to the database.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name to register the table under.	required
`table`	`Any`	A native frame or a narwhals frame, eager or lazy. It is lazified on the way in, so the two forms are interchangeable and may be mixed within one database.	required
`primary_key`	`str \| None`	Column uniquely identifying a row. Required for a table used as a relationship parent or as the DFS target.	`None`
`row_creation_time`	`str \| None`	Column recording when a row became knowable. Required for order-dependent primitives on this table.	`None`
`validate`	`bool \| str \| Iterable[str]`	Checks to run against the data before registering the table. `False` (the default) runs none and reads no rows; `True` runs every check; a check name or an iterable of names runs those. A failing check raises :class:`~tusk.exceptions.ValidationError` and the table is not registered.	`False`

Returns:

Type	Description
`Database`	This database, to allow chaining.

Raises:

Type	Description
`SchemaError`	If the name is taken, a declared column is missing, a key is composite, or the backend differs from earlier tables.

Warns:

Type	Description
`MissingPrimaryKeyWarning`	If `primary_key` is omitted.

add_relationship ¶

add_relationship(
    parent,
    child,
    foreign_key,
    *,
    validate="matching_key_dtypes",
)

Link a parent table to a child table.

Parameters:

Name	Type	Description	Default
`parent`	`str`	Name of the parent table. Must have a `primary_key`.	required
`child`	`str`	Name of the child table.	required
`foreign_key`	`str`	The child's column pointing at the parent's primary key.	required
`validate`	`bool \| str \| Iterable[str]`	Which relationship checks to run before registering the link. Defaults to `"matching_key_dtypes"`, which reads the declared dtypes and no rows, so it costs nothing; `True` also runs `"overlapping_keys"`, which joins the two tables. `False` runs none. A failing check raises :class:`~tusk.exceptions.ValidationError` and the relationship is not registered.	`'matching_key_dtypes'`

Returns:

Type	Description
`Database`	This database, to allow chaining.

Raises:

Type	Description
`SchemaError`	If a table is unknown, the parent has no primary key, the foreign key is composite, or the child lacks that column.

validate ¶

validate(*, database=True, tables=True, relationships=True)

Run validation checks against the database.

Each argument selects from its own registry, and takes the same forms as validate= on :meth:add_table: True for every check in that scope, False for none, a check name, or an iterable of names. A name outside the scope it is given to raises :class:ValueError.

Table checks run against every table in insertion order, then relationship checks against every relationship, then database-wide checks once. The first failure raises :class:~tusk.exceptions.ValidationError.

Parameters:

Name	Type	Description	Default
`database`	`bool \| str \| Iterable[str]`	Checks spanning the whole database.	`True`
`tables`	`bool \| str \| Iterable[str]`	Checks run against each table.	`True`
`relationships`	`bool \| str \| Iterable[str]`	Checks run against each relationship.	`True`

Returns:

Type	Description
`Database`	This database, to allow chaining.

schema ¶

schema(name)

Return a table's schema.

Parameters:

Name	Type	Description	Default
`name`	`str`	Table name.	required

Returns:

Type	Description
`TableSchema`	The table's schema.

Raises:

Type	Description
`SchemaError`	If the table is unknown.

frame ¶

frame(name)

Return a table's lazy frame.

Parameters:

Name	Type	Description	Default
`name`	`str`	Table name.	required

Returns:

Type	Description
`LazyFrame`	The table's narwhals LazyFrame.

Raises:

Type	Description
`SchemaError`	If the table is unknown.

children_of ¶

children_of(name)

Return relationships where this table is the parent.

Parameters:

Name	Type	Description	Default
`name`	`str`	Table name.	required

Returns:

Type	Description
`list[Relationship]`	Matching relationships, in insertion order.

parents_of ¶

parents_of(name)

Return relationships where this table is the child.

Parameters:

Name	Type	Description	Default
`name`	`str`	Table name.	required

Returns:

Type	Description
`list[Relationship]`	Matching relationships, in insertion order.

input_excluded_columns ¶

input_excluded_columns(name)

Return columns that may not be fed to a primitive as an input.

Join keys only: the primary key and every foreign key. They identify rows rather than measure anything, so MEAN(customer_id) is noise. Foreign keys remain usable as groupby keys.

The row_creation_time is deliberately not here. It is a real measurement — MONTH(signed_up_at)-style temporal transforms, and N_UNIQUE or CUM_COUNT over a temporal column, are exactly the features this split unblocks — and excluding it would leave a zero-configuration run with no transform features at all. Contrast :meth:output_excluded_columns, which does exclude it; conflating the two sets is a bug this split exists to prevent.

Parameters:

Name	Type	Description	Default
`name`	`str`	Table name.	required

Returns:

Type	Description
`frozenset[str]`	The table's join-key column names.

output_excluded_columns ¶

output_excluded_columns(name)

Return raw columns that never appear in the feature matrix.

Everything in :meth:input_excluded_columns, plus the row_creation_time: passing the time index through as a feature invites target leakage, and featuretools drops it from the matrix for the same reason. Derived features over the row creation time, such as MONTH(signed_up_at), are unaffected — only the raw column is dropped.

Parameters:

Name	Type	Description	Default
`name`	`str`	Table name.	required

Returns:

Type	Description
`frozenset[str]`	Column names to omit from the feature matrix.

Relationship¶

Relationship `dataclass` ¶

Relationship(parent, child, foreign_key)

A one-to-many link from a parent table to a child table.

The parent side is always the parent's primary_key; foreign_key names the child's column.

Attributes:

Name	Type	Description
`parent`	`str`	Name of the parent table.
`child`	`str`	Name of the child table.
`foreign_key`	`str`	Column on the child pointing at the parent's primary key.

parent `instance-attribute` ¶

parent

child `instance-attribute` ¶

child

foreign_key `instance-attribute` ¶

foreign_key

TableSchema¶

TableSchema `dataclass` ¶

TableSchema(name, primary_key, row_creation_time, dtypes)

Everything phase 1 knows about a table.

Attributes:

Name	Type	Description
`name`	`str`	Table name within the database.
`primary_key`	`str \| None`	Column uniquely identifying a row, if declared.
`row_creation_time`	`str \| None`	Column recording when a row became knowable.
`dtypes`	`Mapping[str, Any]`	Mapping of column name to narwhals dtype.

name `instance-attribute` ¶

name

primary_key `instance-attribute` ¶

primary_key

row_creation_time `instance-attribute` ¶

row_creation_time

dtypes `instance-attribute` ¶

dtypes

Databases¶

database ¶

Database¶

Database ¶

name instance-attribute ¶

table_names property ¶

relationships property ¶

add_table ¶

add_relationship ¶

validate ¶

schema ¶

frame ¶

children_of ¶

parents_of ¶

input_excluded_columns ¶

output_excluded_columns ¶

Relationship¶

Relationship dataclass ¶

parent instance-attribute ¶

child instance-attribute ¶

foreign_key instance-attribute ¶

TableSchema¶

TableSchema dataclass ¶

name instance-attribute ¶

primary_key instance-attribute ¶

row_creation_time instance-attribute ¶

dtypes instance-attribute ¶

name `instance-attribute` ¶

table_names `property` ¶

relationships `property` ¶

Relationship `dataclass` ¶

parent `instance-attribute` ¶

child `instance-attribute` ¶

foreign_key `instance-attribute` ¶

TableSchema `dataclass` ¶

name `instance-attribute` ¶

primary_key `instance-attribute` ¶

row_creation_time `instance-attribute` ¶

dtypes `instance-attribute` ¶