Schema

Schema and VirtualModule classes

Schema management for DataJoint.

This module provides the Schema class for binding Python table classes to database schemas, and utilities for schema introspection and management.

ordered_dir

ordered_dir(class_)

List class attributes respecting declaration order.

Similar to the dir() built-in, but preserves attribute declaration order as much as possible.

Parameters:

Name	Type	Description	Default
class_	type	Class to list members for.	required

Returns:

Type	Description
list[str]	Attributes declared in class_ and its superclasses.

Schema

Decorator that binds table classes to a database schema.

Schema objects associate Python table classes with database schemas and provide the namespace context for foreign key resolution.

Parameters:

Name	Type	Description	Default
schema_name	str	Database schema name. If omitted, call activate() later.	None
context	dict	Namespace for foreign key lookup. None uses caller's context.	None
connection	Connection	Database connection. Defaults to dj.conn().	None
create_schema	bool	If False, raise error if schema doesn't exist. Default True.	True
create_tables	bool	If False, raise error when accessing missing tables. Default from dj.config.database.create_tables (True unless configured).	None
add_objects	dict	Additional objects for the declaration context.	None

Examples:

>>> schema = dj.Schema('my_schema')
>>> @schema
... class Session(dj.Manual):
...     definition = '''
...     session_id : int
...     '''

is_activated

is_activated()

Check if the schema has been activated.

activate

activate(schema_name=None, *, connection=None, create_schema=None, create_tables=None, add_objects=None)

Associate with a database schema.

If the schema does not exist, attempts to create it on the server.

Parameters:

Name	Type	Description	Default
schema_name	str	Database schema name. None asserts schema is already activated.	None
connection	Connection	Database connection. Defaults to dj.conn().	None
create_schema	bool	If False, raise error if schema doesn't exist.	None
create_tables	bool	If False, raise error when accessing missing tables.	None
add_objects	dict	Additional objects for the declaration context.	None

Raises:

Type	Description
DataJointError	If schema_name is None and schema not yet activated, or if schema already activated for a different database.

size_on_disk property

size_on_disk

Return the total size of all tables in the schema.

Returns:

Type	Description
int	Size in bytes (data + indices).

make_classes

make_classes(into=None)

Create Python table classes for tables in the schema.

Introspects the database schema and creates appropriate Python classes (Lookup, Manual, Imported, Computed, Part) for tables that don't have corresponding classes in the target namespace.

Parameters:

Name	Type	Description	Default
into	dict	Namespace to place created classes into. Defaults to caller's local namespace.	None

drop

drop(prompt=None)

Drop the associated schema and all its tables.

Parameters:

Name	Type	Description	Default
prompt	bool	If True, show confirmation prompt before dropping. If False, drop without confirmation. If None (default), use dj.config['safemode'] setting.	None

Raises:

Type	Description
AccessError	If insufficient permissions to drop the schema.

exists property

exists

Check if the associated schema exists on the server.

Returns:

Type	Description
bool	True if the schema exists.

Raises:

Type	Description
DataJointError	If schema has not been activated.

lineage_table_exists property

lineage_table_exists

Check if the ~lineage table exists in this schema.

Returns:

Type	Description
bool	True if the lineage table exists.

lineage property

lineage

Get all lineages for tables in this schema.

Returns:

Type	Description
dict[str, str]	Mapping of 'schema.table.attribute' to its lineage origin.

rebuild_lineage

rebuild_lineage()

Rebuild the ~lineage table for all tables in this schema.

Recomputes lineage for all attributes by querying FK relationships from the information_schema. Use to restore lineage for schemas that predate the lineage system or after corruption.

Notes

After rebuilding, restart the Python kernel and reimport to pick up the new lineage information.

Upstream schemas (referenced via cross-schema foreign keys) must have their lineage rebuilt first.

jobs property

jobs

Return Job objects for auto-populated tables with job tables.

Only returns Job objects when both the target table and its ~~table_name job table exist in the database. Job tables are created lazily on first access to table.jobs or populate(reserve_jobs=True).

Returns:

Type	Description
list[Job]	Job objects for existing job tables.

save

save(python_filename=None)

Generate Python code that recreates this schema.

Parameters:

Name	Type	Description	Default
python_filename	str	If provided, write the code to this file.	None

Returns:

Type	Description
str	Python module source code defining this schema.

Notes

This method is in preparation for a future release and is not officially supported.

list_tables

list_tables()

Return all user tables in the schema.

Excludes hidden tables (starting with ~) such as ~lineage and job tables (~~).

Returns:

Type	Description
list[str]	Table names in topological order.

get_table

get_table(name)

Get a table instance by name.

Returns a FreeTable instance for the given table name. This is useful for accessing tables when you don't have the Python class available.

Parameters:

Name	Type	Description	Default
name	str	Table name (e.g., 'experiment', 'session__trial' for parts). Can be snake_case (SQL name) or CamelCase (class name). Tier prefixes are optional and will be auto-detected.	required

Returns:

Type	Description
FreeTable	A FreeTable instance for the table.

Raises:

Type	Description
DataJointError	If the table does not exist.

Examples:

>>> schema = dj.Schema('my_schema')
>>> experiment = schema.get_table('experiment')
>>> experiment.fetch()

VirtualModule

Bases: ModuleType

A virtual module representing a DataJoint schema from database tables.

Creates a Python module with table classes automatically generated from the database schema. Useful for accessing schemas without Python source.

Parameters:

Name	Type	Description	Default
module_name	str	Display name for the module.	required
schema_name	str	Database schema name.	required
create_schema	bool	If True, create the schema if it doesn't exist. Default False.	False
create_tables	bool	If True, allow declaring new tables. Default False.	False
connection	Connection	Database connection. Defaults to dj.conn().	None
add_objects	dict	Additional objects to add to the module namespace.	None

Examples:

>>> lab = dj.VirtualModule('lab', 'my_lab_schema')
>>> lab.Subject.fetch()

list_schemas

list_schemas(connection=None)

List all accessible schemas on the server.

Parameters:

Name	Type	Description	Default
connection	Connection	Database connection. Defaults to dj.conn().	None

Returns:

Type	Description
list[str]	Names of all accessible schemas.

virtual_schema

virtual_schema(schema_name, *, connection=None, create_schema=False, create_tables=False, add_objects=None)

Create a virtual module for an existing database schema.

This is the recommended way to access database schemas when you don't have the Python source code that defined them. Returns a module-like object with table classes as attributes.

Parameters:

Name	Type	Description	Default
schema_name	str	Database schema name.	required
connection	Connection	Database connection. Defaults to dj.conn().	None
create_schema	bool	If True, create the schema if it doesn't exist. Default False.	False
create_tables	bool	If True, allow declaring new tables. Default False.	False
add_objects	dict	Additional objects to add to the module namespace.	None

Returns:

Type	Description
VirtualModule	A module-like object with table classes as attributes.

Examples:

>>> lab = dj.virtual_schema('my_lab')
>>> lab.Subject.fetch()
>>> lab.Session & "subject_id='M001'"

See Also

Schema : For defining new schemas with Python classes. VirtualModule : The underlying class (prefer virtual_schema function).