Heading

Table heading and attributes

Heading management for DataJoint tables.

This module provides the Heading class for managing table column metadata, including attribute types, constraints, and lineage information.

Attribute

Bases: namedtuple('_Attribute', default_attribute_properties)

Properties of a table column (attribute).

Attributes:

Name	Type	Description
name	str	Attribute name.
type	str	Database type string.
in_key	bool	True if part of primary key.
nullable	bool	True if NULL values allowed.
default	any	Default value.
comment	str	Attribute comment/description.
codec	Codec	Codec for encoding/decoding values.
lineage	str	Origin of attribute for semantic matching.

todict

todict()

Convert to dictionary.

sql_type property

sql_type

Return the SQL datatype string.

Returns:

Type	Description
str	Database type (usually same as self.type).

sql_comment property

sql_comment

Return the full SQL comment including type markers.

Returns:

Type	Description
str	Comment with optional :uuid: prefix.

sql property

sql

Generate SQL clause for this attribute in CREATE TABLE.

Used for declaring foreign keys in referencing tables. Default values are not included.

Returns:

Type	Description
str	SQL attribute declaration.

original_name property

original_name

Return the original attribute name before any renaming.

Returns:

Type	Description
str	Original name from attribute_expression or current name.

Heading

Table heading containing column metadata.

Manages attribute information including names, types, constraints, and lineage for semantic matching.

Parameters:

Name	Type	Description	Default
attribute_specs	list	List of attribute specification dictionaries.	None
table_info	dict	Database table information for lazy loading.	None
lineage_available	bool	Whether lineage information is available. Default True.	True

Attributes:

Name	Type	Description
attributes	dict	Mapping of attribute names to Attribute objects.

lineage_available property

lineage_available

Whether lineage tracking is available for this heading's schema.

table_status property

table_status

Table status information from database.

attributes property

attributes

Mapping of attribute names to Attribute objects.

Excludes hidden attributes (names starting with _).

names property

names

List of visible attribute names.

primary_key property

primary_key

List of primary key attribute names.

secondary_attributes property

secondary_attributes

List of non-primary-key attribute names.

determines

determines(other)

Check if self determines other (self → other).

A determines B iff every attribute in PK(B) is in A. This means knowing A's primary key is sufficient to determine B's primary key through functional dependencies.

Parameters:

Name	Type	Description	Default
other	Heading	Another Heading object.	required

Returns:

Type	Description
bool	True if self determines other.

blobs property

blobs

List of blob attribute names.

non_blobs property

non_blobs

Attributes that are not blobs or JSON.

new_attributes property

new_attributes

Attributes with computed expressions (projections).

has_autoincrement property

has_autoincrement

Check if any attribute has auto_increment.

as_dtype property

as_dtype

Return heading as a numpy dtype.

Returns:

Type	Description
dtype	Structured dtype for creating numpy arrays.

as_sql

as_sql(fields, include_aliases=True, adapter=None)

Generate SQL SELECT clause for specified fields.

Parameters:

Name	Type	Description	Default
fields	list[str]	Attribute names to include.	required
include_aliases	bool	Include AS clauses for computed attributes. Default True.	True
adapter	DatabaseAdapter	Database adapter for identifier quoting. If not provided, attempts to get from table_info connection.	None

Returns:

Type	Description
str	Comma-separated SQL field list.

select

select(select_list, rename_map=None, compute_map=None)

Derive a new heading by selecting, renaming, or computing attributes.

In relational algebra these operators are known as project, rename, and extend. This low-level method performs no error checking.

Parameters:

Name	Type	Description	Default
select_list	list	The full list of existing attributes to include.	required
rename_map	dict	Dictionary of renamed attributes: keys=new names, values=old names.	None
compute_map	dict	A dictionary of computed attributes.	None

Returns:

Type	Description
Heading	New heading with selected, renamed, and computed attributes.

join

join(other, nullable_pk=False)

Join two headings into a new one.

The primary key of the result depends on functional dependencies:

• A -> B: PK = PK(A), A's attributes first
• B -> A (not A -> B): PK = PK(B), B's attributes first
• Both: PK = PK(A), left operand takes precedence
• Neither: PK = PK(A) | PK(B), A's PK first then B's new PK attrs

It assumes that self and other are headings that share no common dependent attributes.

Parameters:

Name	Type	Description	Default
other	Heading	The other heading to join with.	required
nullable_pk	bool	If True, skip PK optimization and use combined PK from both operands. Used for left joins that bypass the A -> B constraint, where the right operand's PK attributes could be NULL. Default False.	False

Returns:

Type	Description
Heading	New heading resulting from the join.

set_primary_key

set_primary_key(primary_key)

Create a new heading with the specified primary key. This low-level method performs no error checking.

make_subquery_heading

make_subquery_heading()

Create a new heading with removed attribute sql_expressions. Used by subqueries, which resolve the sql_expressions.